gh-netresearch-claude-code-marketplace-skills-typo3-conformance/references/extension-architecture.md

TYPO3 Extension Architecture Standards

Source: TYPO3 Core API Reference - Extension Architecture Purpose: File structure, directory hierarchy, and required files for TYPO3 extensions

Required Files

Essential Files

composer.json

• REQUIRED for all extensions
• Defines package metadata, dependencies, PSR-4 autoloading
• Example:

{
    "name": "vendor/extension-key",
    "type": "typo3-cms-extension",
    "require": {
        "typo3/cms-core": "^12.4 || ^13.0"
    },
    "autoload": {
        "psr-4": {
            "Vendor\\ExtensionKey\\": "Classes/"
        }
    }
}

ext_emconf.php

• REQUIRED for TER (TYPO3 Extension Repository) publication
• Contains extension metadata
• Example:

<?php
$EM_CONF[$_EXTKEY] = [
    'title' => 'Extension Title',
    'description' => 'Extension description',
    'category' => 'fe',
    'author' => 'Author Name',
    'author_email' => 'author@example.com',
    'state' => 'stable',
    'version' => '1.0.0',
    'constraints' => [
        'depends' => [
            'typo3' => '12.4.0-13.9.99',
        ],
    ],
];

Documentation/Index.rst

• REQUIRED for docs.typo3.org publication
• Main documentation entry point
• Must follow reStructuredText format

Documentation/Settings.cfg

• REQUIRED for docs.typo3.org publication
• Contains documentation project settings
• Example:

[general]
project = Extension Name
release = 1.0.0
copyright = 2024

[html_theme_options]
project_home = https://github.com/vendor/extension

Directory Structure

Core Directories

Classes/

• Contains all PHP classes
• MUST follow PSR-4 autoloading structure
• Namespace: \VendorName\ExtensionKey\
• Common subdirectories:
  • Classes/Controller/ - Extbase/backend controllers
  • Classes/Domain/Model/ - Domain models
  • Classes/Domain/Repository/ - Repositories
  • Classes/Service/ - Service classes
  • Classes/Utility/ - Utility classes
  • Classes/ViewHelper/ - Fluid ViewHelpers
  • Classes/EventListener/ - PSR-14 event listeners

Configuration/

• Contains all configuration files
• Required subdirectories:
  • Configuration/TCA/ - Table Configuration Array definitions
  • Configuration/Backend/ - Backend module configuration
  • Configuration/TypoScript/ - TypoScript configuration
  • Configuration/Sets/ - Configuration sets (TYPO3 v13+)
• Optional files:
  • Configuration/Services.yaml - Dependency injection configuration
  • Configuration/TsConfig/ - Page/User TSconfig
  • Configuration/RequestMiddlewares.php - PSR-15 middlewares

Resources/

• Contains all frontend/backend resources
• Structure:
  • Resources/Private/ - Non-public files
    • Resources/Private/Templates/ - Fluid templates
    • Resources/Private/Partials/ - Fluid partials
    • Resources/Private/Layouts/ - Fluid layouts
    • Resources/Private/Language/ - Translation files (XLIFF)
  • Resources/Public/ - Publicly accessible files
    • Resources/Public/Css/ - Stylesheets
    • Resources/Public/JavaScript/ - JavaScript files
    • Resources/Public/Icons/ - Extension icons
    • Resources/Public/Images/ - Images

Tests/

• Contains all test files
• Structure:
  • Tests/Unit/ - PHPUnit unit tests
  • Tests/Functional/ - PHPUnit functional tests
  • Tests/Acceptance/ - Codeception acceptance tests
• MUST mirror Classes/ structure

Documentation/

• Contains RST documentation
• MUST include Index.rst and Settings.cfg
• Common structure:
  • Documentation/Introduction/
  • Documentation/Installation/
  • Documentation/Configuration/
  • Documentation/Developer/
  • Documentation/Editor/

Reserved File Prefixes

Files with the ext_* prefix are reserved for special purposes:

ext_emconf.php

• Extension metadata (REQUIRED for TER)

ext_localconf.php

• Global configuration executed in both frontend and backend
• Register hooks, event listeners, XCLASSes
• Add plugins, content elements
• Register services

ext_tables.php

• Backend-specific configuration
• Register backend modules
• Add TCA modifications
• DEPRECATED in favor of dedicated configuration files

ext_tables.sql

• Database table definitions
• Executed during extension installation
• Contains CREATE TABLE and ALTER TABLE statements

ext_conf_template.txt

• Extension configuration template
• Defines settings available in Extension Configuration
• TypoScript-like syntax

File Naming Conventions

PHP Classes

• File name MUST match class name exactly
• PSR-4 compliant
• Example: Classes/Controller/MyController.php → class MyController

Database Tables

• Pattern: tx_<extensionkeyprefix>_<tablename>
• Example: tx_myext_domain_model_product
• Extension key must be converted to lowercase, underscores allowed

TCA Files

• Pattern: Configuration/TCA/<tablename>.php
• Returns TCA array
• Example: Configuration/TCA/tx_myext_domain_model_product.php

Language Files

• Pattern: Resources/Private/Language/<context>.xlf
• XLIFF 1.2 format
• Example: Resources/Private/Language/locallang.xlf

Architecture Best Practices

PSR-4 Autoloading

• All classes in Classes/ directory
• Namespace structure MUST match directory structure
• Example:
  • Class: Vendor\ExtensionKey\Domain\Model\Product
  • File: Classes/Domain/Model/Product.php

Dependency Injection

• Use constructor injection for dependencies
• Register services in Configuration/Services.yaml
• Example:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Vendor\ExtensionKey\:
    resource: '../Classes/*'

Configuration Files

• Separate concerns into dedicated configuration files
• Use Configuration/Backend/ for backend modules (not ext_tables.php)
• Use Configuration/TCA/ for table definitions
• Use Configuration/TypoScript/ for TypoScript

Testing Structure

• Mirror Classes/ structure in Tests/Unit/ and Tests/Functional/
• Example:
  • Class: Classes/Service/CalculationService.php
  • Unit Test: Tests/Unit/Service/CalculationServiceTest.php
  • Functional Test: Tests/Functional/Service/CalculationServiceTest.php

Common Issues

❌ Wrong: Mixed file types in root

my_extension/
├── MyController.php          # WRONG: PHP in root
├── config.yaml               # WRONG: Config in root
└── styles.css                # WRONG: CSS in root

✅ Right: Proper directory structure

my_extension/
├── Classes/Controller/MyController.php
├── Configuration/Services.yaml
└── Resources/Public/Css/styles.css

❌ Wrong: Non-standard directory names

Classes/
├── Controllers/              # WRONG: Plural
├── Services/                 # WRONG: Should be Service
└── Helpers/                  # WRONG: Use Utility

✅ Right: Standard TYPO3 directory names

Classes/
├── Controller/               # Singular
├── Service/                  # Singular
└── Utility/                  # Standard naming

Extension Key Naming

• Lowercase letters and underscores only
• Must start with a letter
• 3-30 characters
• Cannot start with tx_, user_, pages, tt_, sys_
• Example: my_extension, blog_example, news

Conformance Checklist

• composer.json present with correct structure
• ext_emconf.php present with complete metadata
• Documentation/Index.rst and Documentation/Settings.cfg present
• Classes/ directory follows PSR-4 structure
• Configuration/ subdirectories properly organized
• Resources/ separated into Private/ and Public/
• Tests/ mirror Classes/ structure
• No PHP files in extension root (except ext_* files)
• File naming follows conventions
• Database table names use tx__ prefix
• Extension key follows naming rules