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

TYPO3 Extension Architecture Reference

Official TYPO3 extension file structure for documentation extraction weighting and categorization.

Source: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Index.html

File Structure Hierarchy

🔴 Required Files (High Priority)

composer.json - Composer configuration

• Documentation Priority: HIGH
• Extract: Package name, description, dependencies, autoload configuration
• Map to RST: Introduction/Index.rst (overview), Installation requirements
• Weight: Critical for dependency documentation

ext_emconf.php - Extension metadata

• Documentation Priority: HIGH
• Extract: Title, description, version, author, constraints
• Map to RST: Introduction/Index.rst, Settings.cfg
• Weight: Essential metadata, version constraints

Index.rst (in Documentation/)

• Documentation Priority: CRITICAL
• Required: Main documentation entry point
• Must Exist: For TYPO3 Intercept deployment

Settings.cfg (in Documentation/)

• Documentation Priority: CRITICAL
• Required: Documentation build configuration
• Must Exist: For TYPO3 Intercept deployment

🟡 Core Structure Files (Medium-High Priority)

ext_localconf.php - Runtime configuration

• Documentation Priority: MEDIUM-HIGH
• Extract: Plugin registrations, hooks, service configurations
• Map to RST: Integration guides, Developer/Configuration.rst
• Weight: Important for integration documentation

ext_tables.php - Backend configuration

• Documentation Priority: MEDIUM
• Extract: Backend module registrations, permissions
• Map to RST: Developer/Backend.rst
• Weight: Backend-specific documentation

ext_tables.sql - Database schema

• Documentation Priority: MEDIUM
• Extract: Table structures, field definitions
• Map to RST: Developer/Database.rst, API/DataModel.rst
• Weight: Important for database documentation

ext_conf_template.txt - Extension configuration template

• Documentation Priority: HIGH
• Extract: All configuration options, types, defaults, security warnings
• Map to RST: Integration/Configuration.rst (confval directives)
• Weight: Critical - direct user-facing configuration

Directory Structure Weights

Classes/ (Weight: HIGH)

Purpose: PHP source code following PSR-4 autoloading

Priority Hierarchy:

1. Classes/Controller/ (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: Action methods, parameters, return types
   • Map to RST: API/Controllers/, Developer/Plugins.rst
   • Pattern: MVC controllers extending ActionController

2. Classes/Domain/Model/ (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: Entity properties, getters/setters, relationships
   • Map to RST: API/Models/, Developer/DataModel.rst
   • Pattern: Extbase domain models

3. Classes/Domain/Repository/ (Weight: MEDIUM-HIGH)

   • Documentation Priority: MEDIUM-HIGH
   • Extract: Query methods, custom finders
   • Map to RST: API/Repositories/, Developer/DataAccess.rst
   • Pattern: Extends \TYPO3\CMS\Extbase\Persistence\Repository

4. Classes/ViewHelpers/ (Weight: MEDIUM)

   • Documentation Priority: MEDIUM
   • Extract: ViewHelper arguments, usage examples
   • Map to RST: Developer/ViewHelpers.rst
   • Pattern: Custom Fluid ViewHelpers

5. Classes/Utility/ (Weight: MEDIUM)

   • Documentation Priority: MEDIUM
   • Extract: Utility methods, static helpers
   • Map to RST: API/Utilities/
   • Pattern: Static helper classes

6. Classes/Service/ (Weight: MEDIUM-HIGH)

   • Documentation Priority: MEDIUM-HIGH
   • Extract: Service methods, dependencies
   • Map to RST: API/Services/
   • Pattern: Business logic services

Configuration/ (Weight: VERY HIGH)

Purpose: All TYPO3 configuration files

Priority Hierarchy:

1. Configuration/TCA/ (Weight: VERY HIGH)

   • Documentation Priority: VERY HIGH
   • Extract: Table definitions, field configurations, relationships
   • Map to RST: Developer/DataModel.rst, Editor/Fields.rst
   • Files: <tablename>.php
   • Pattern: Database table configuration arrays

2. Configuration/TCA/Overrides/ (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: Field additions, modifications to core tables
   • Map to RST: Integration/CoreExtensions.rst
   • Files: <tablename>.php
   • Pattern: TCA modifications

3. Configuration/TypoScript/ (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: Constants, setup, plugin configurations
   • Map to RST: Configuration/TypoScript.rst
   • Files: constants.typoscript, setup.typoscript
   • Pattern: TypoScript configuration

4. Configuration/Sets/ (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: Site set configurations, settings definitions
   • Map to RST: Configuration/SiteSets.rst
   • Files: config.yaml, settings.definitions.yaml, setup.typoscript
   • Pattern: Modern configuration approach (TYPO3 v13+)

5. Configuration/TsConfig/ (Weight: MEDIUM-HIGH)

   • Documentation Priority: MEDIUM-HIGH
   • Extract: Page TSconfig, User TSconfig
   • Map to RST: Editor/PageTSconfig.rst, Editor/UserTSconfig.rst
   • Subdirs: Page/, User/
   • Files: *.tsconfig

6. Configuration/Backend/ (Weight: MEDIUM)

   • Documentation Priority: MEDIUM
   • Extract: Backend routes, modules, AJAX routes
   • Map to RST: Developer/Backend.rst
   • Files: Routes.php, Modules.php, AjaxRoutes.php

7. Configuration/Services.yaml (Weight: HIGH)

   • Documentation Priority: HIGH
   • Extract: DI configuration, event listeners, console commands
   • Map to RST: Developer/DependencyInjection.rst, Developer/Events.rst
   • Pattern: Symfony-style service configuration

8. Configuration/Extbase/Persistence/Classes.php (Weight: MEDIUM)

   • Documentation Priority: MEDIUM
   • Extract: Model-to-table mappings
   • Map to RST: Developer/Persistence.rst

9. Configuration/Icons.php (Weight: LOW)

   • Documentation Priority: LOW
   • Extract: Icon identifiers
   • Map to RST: Developer/Icons.rst (if comprehensive)

Resources/ (Weight: MEDIUM)

Purpose: Asset files and templates

Priority Hierarchy:

1. Resources/Private/Language/ (Weight: MEDIUM-HIGH)

   • Documentation Priority: MEDIUM
   • Extract: Translation keys (for reference)
   • Map to RST: Developer/Localization.rst
   • Files: *.xlf (XLIFF format)
   • Note: Extract labels for API documentation context

2. Resources/Private/Templates/ (Weight: MEDIUM)

   • Documentation Priority: MEDIUM
   • Extract: Template structure (for developer reference)
   • Map to RST: Developer/Templating.rst
   • Files: [ControllerName]/[ActionName].html
   • Note: Document template variables and ViewHelpers used

3. Resources/Private/Layouts/ (Weight: LOW-MEDIUM)

   • Documentation Priority: LOW
   • Extract: Layout structure
   • Files: *.html

4. Resources/Private/Partials/ (Weight: LOW-MEDIUM)

   • Documentation Priority: LOW
   • Extract: Reusable template fragments
   • Files: *.html

5. Resources/Public/ (Weight: LOW)

   • Documentation Priority: LOW
   • Extract: Public asset information (if relevant)
   • Subdirs: CSS/, JavaScript/, Icons/, Images/
   • Note: Usually not documented in detail

Documentation/ (Weight: CRITICAL)

Purpose: Official RST documentation

Required Files:

• Index.rst - Main entry point
• Settings.cfg - Build configuration

Common Structure:

• Introduction/ - Overview, features, screenshots
• Installation/ - Installation and upgrade
• Configuration/ - TypoScript, extension settings
• Integration/ - Integration with other extensions
• Editor/ - User guide for editors
• Developer/ - Developer documentation
• API/ - PHP API reference
• Troubleshooting/ - Common issues

Priority: CRITICAL - This is the primary output target for extraction

Tests/ (Weight: LOW)

Purpose: Unit, functional, and acceptance tests

Documentation Priority: LOW

• Extract test class names for coverage documentation
• Generally not documented in user-facing docs
• May reference in Developer/Testing.rst if test examples provided

Structure:

• Tests/Unit/ - Unit tests
• Tests/Functional/ - Functional tests
• Tests/Acceptance/ - Acceptance tests (Codeception)

Extraction Weight Matrix

Primary Sources (Extract First)

Priority 1 - CRITICAL (Must Document):
├─ ext_emconf.php → Extension metadata
├─ ext_conf_template.txt → User configuration
├─ composer.json → Dependencies
└─ Configuration/TCA/*.php → Data model

Priority 2 - HIGH (Should Document):
├─ Classes/Controller/ → Controllers/Actions
├─ Classes/Domain/Model/ → Domain entities
├─ Classes/Service/ → Business logic
├─ Configuration/TypoScript/ → TypoScript config
├─ Configuration/Sets/ → Site sets (v13+)
└─ ext_localconf.php → Runtime registration

Priority 3 - MEDIUM (Consider Documenting):
├─ Classes/Domain/Repository/ → Data access
├─ Classes/ViewHelpers/ → Custom ViewHelpers
├─ Configuration/Backend/ → Backend modules
├─ Configuration/TsConfig/ → TSconfig
├─ Configuration/Services.yaml → DI/Events
└─ Resources/Private/Language/ → Translation context

Secondary Sources (Extract If Needed)

Priority 4 - MEDIUM-LOW:
├─ Classes/Utility/ → Utility functions
├─ ext_tables.php → Backend config
├─ ext_tables.sql → Database schema
└─ Configuration/TCA/Overrides/ → Core extensions

Priority 5 - LOW:
├─ Resources/Private/Templates/ → Template structure
├─ Resources/Public/ → Public assets
├─ Tests/ → Test coverage
└─ Configuration/Icons.php → Icon registry

Documentation Mapping Strategy

Extension Metadata → Introduction

Source: ext_emconf.php, composer.json, README.md

Target: Documentation/Introduction/Index.rst

Extract:

• Extension title → Main heading
• Description → First paragraph
• Version → Version marker
• Author → Credits section
• Constraints → Requirements section

Example Mapping:

ext_emconf.php:
  'title' => 'CKEditor Image Support'
  'version' => '13.1.0'
  'constraints' => ['typo3' => '12.4-13.5']

→ Introduction/Index.rst:
  ========================
  CKEditor Image Support
  ========================

  :Version: 13.1.0
  :Language: en

  Requirements
  ------------
  - TYPO3: 12.4 - 13.5

Configuration Options → Integration/Configuration

Source: ext_conf_template.txt

Target: Documentation/Integration/Configuration.rst

Extract Pattern:

# cat=category; type=boolean; label=Label: Description
settingName = defaultValue

→ .. confval:: settingName
     :type: boolean
     :Default: defaultValue
     :Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['ext_key']['settingName']

     Description text here

Security Warnings: Extract and map to .. warning:: directive

PHP Classes → API Documentation

Source: Classes/**/*.php

Target: Documentation/API/[ClassName].rst

Mapping by Type:

Controllers:

Classes/Controller/UserController.php

→ API/UserController.rst

  .. php:class:: UserController

     User management controller

     .. php:method:: listAction(): ResponseInterface

Models:

Classes/Domain/Model/User.php

→ API/User.rst

  .. php:class:: User

     User domain model

     .. php:attr:: username
        :type: string

Repositories:

Classes/Domain/Repository/UserRepository.php

→ API/UserRepository.rst

  .. php:class:: UserRepository

     User data repository

     .. php:method:: findByEmail(string $email): ?User

TCA Configuration → Developer/DataModel

Source: Configuration/TCA/*.php

Target: Documentation/Developer/DataModel.rst

Extract:

• Table name → Section heading
• ctrl['title'] → Table title
• columns → Field documentation

Example:

Configuration/TCA/tx_myext_domain_model_user.php:
  'ctrl' => ['title' => 'User']
  'columns' => [
    'username' => [...],
    'email' => [...]
  ]

→ Developer/DataModel.rst:

  Users Table
  ===========

  Database table: tx_myext_domain_model_user

  Fields
  ------

  username
    User login name

  email
    User email address

TypoScript → Configuration/TypoScript

Source: Configuration/TypoScript/*.typoscript

Target: Documentation/Configuration/TypoScript.rst

Extract:

• Constants → Configuration reference
• Setup → Implementation examples

Quality Weighting Algorithm

Documentation Coverage Score

Score = (P1_documented / P1_total) * 0.5 +
        (P2_documented / P2_total) * 0.3 +
        (P3_documented / P3_total) * 0.15 +
        (P4_documented / P4_total) * 0.05

Where:
  P1 = Priority 1 (CRITICAL) items
  P2 = Priority 2 (HIGH) items
  P3 = Priority 3 (MEDIUM) items
  P4 = Priority 4+ (LOW) items

Gap Analysis Priority

Priority = BaseWeight * Severity * UserImpact

BaseWeight (from file structure):
  ext_conf_template.txt config = 10
  Controllers = 9
  Models = 9
  TCA = 8
  ext_emconf.php = 8
  Services = 7
  Repositories = 6
  ViewHelpers = 5
  Utilities = 4

Severity:
  Missing completely = 3
  Outdated (wrong defaults) = 2
  Incomplete (missing examples) = 1

UserImpact:
  User-facing (config, editor features) = 3
  Integrator-facing (TypoScript, TSconfig) = 2
  Developer-facing (API) = 1

Example Calculation

Missing confval for "fetchExternalImages":
  Priority = 10 (ext_conf_template) * 3 (missing) * 3 (user-facing) = 90

Outdated Controller documentation:
  Priority = 9 (controller) * 2 (outdated) * 1 (developer) = 18

Missing Utility documentation:
  Priority = 4 (utility) * 3 (missing) * 1 (developer) = 12

Action: Document in priority order: 90 → 18 → 12

Official Structure Validation

Required Structure Checklist

Composer-Mode Installation:

• ✅ composer.json with "type": "typo3-cms-extension"
• ✅ PSR-4 autoload configuration
• ✅ Documentation/Index.rst
• ✅ Documentation/Settings.cfg

Classic-Mode Installation:

• ✅ ext_emconf.php
• ✅ Documentation/Index.rst
• ✅ Documentation/Settings.cfg

Reserved Prefixes

Root Directory:

• ext_* files are reserved for TYPO3 system use
• Only allowed: ext_emconf.php, ext_localconf.php, ext_tables.php, ext_tables.sql, ext_conf_template.txt

Never Create:

• ext_custom.php
• ext_myconfig.php
• Any other ext_* files

Best Practices for Extraction

1. Follow Official Structure: Extract based on official TYPO3 architecture
2. Weight by Location: Use file location to determine documentation priority
3. Respect Conventions: Map to RST sections based on TYPO3 conventions
4. Security First: Extract and highlight security warnings from configs
5. Version Awareness: Track version-specific features from ext_emconf.php
6. Dependency Mapping: Use composer.json and constraints for requirements
7. Complete Coverage: Prioritize user-facing config, controllers, models
8. Context Awareness: Understand file purpose from directory structure

Resources

• Official Structure: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/
• TCA Reference: https://docs.typo3.org/m/typo3/reference-tca/
• TypoScript Reference: https://docs.typo3.org/m/typo3/reference-typoscript/
• Extbase/Fluid: https://docs.typo3.org/m/typo3/book-extbasefluid/