533 lines
16 KiB
Markdown
533 lines
16 KiB
Markdown
# 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:**
|
|
```php
|
|
Classes/Controller/UserController.php
|
|
|
|
→ API/UserController.rst
|
|
|
|
.. php:class:: UserController
|
|
|
|
User management controller
|
|
|
|
.. php:method:: listAction(): ResponseInterface
|
|
```
|
|
|
|
**Models:**
|
|
```php
|
|
Classes/Domain/Model/User.php
|
|
|
|
→ API/User.rst
|
|
|
|
.. php:class:: User
|
|
|
|
User domain model
|
|
|
|
.. php:attr:: username
|
|
:type: string
|
|
```
|
|
|
|
**Repositories:**
|
|
```php
|
|
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:**
|
|
```php
|
|
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/
|