<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# TYPO3 Extension Conformance Checker
A comprehensive Claude Code skill for evaluating TYPO3 extensions against official TYPO3 coding standards, architecture patterns, and best practices.
## ๐ Compatibility
This is an **Agent Skill** following the [open standard](https://agentskills.io) originally developed by Anthropic and released for cross-platform use.
**Supported Platforms:**
- โ
Claude Code (Anthropic)
- โ
Cursor
- โ
GitHub Copilot
- โ
Other skills-compatible AI agents
> Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.
## Overview
This skill enables systematic evaluation of TYPO3 extensions for conformance to official TYPO3 standards.
### Skill Ecosystem Integration
This conformance checker acts as an **orchestrator** that delegates to specialized skills for deep domain analysis:
**๐ง Testing Analysis: typo3-tests**
- Repository: https://github.com/netresearch/typo3-testing-skill
- Expertise: Deep PHPUnit configuration analysis, test quality patterns, TYPO3 Testing Framework validation
- Integration: Delegated for Testing Standards category (20 points)
**๐ Documentation Analysis: typo3-docs**
- Repository: https://github.com/netresearch/typo3-docs-skill
- Expertise: RST validation, TYPO3 documentation standards, rendering validation with Docker
- Integration: Delegated for Documentation Excellence (bonus category)
**Delegation Benefits:**
- **Depth:** Each skill provides domain expertise beyond surface-level checks
- **Accuracy:** Specialized validation reduces false positives/negatives
- **Modularity:** Skills can be used independently or together
- **Maintainability:** Each skill focuses on single responsibility
**Fallback Strategy:**
- Surface-level checks performed if specialized skills unavailable
- Basic validation ensures conformance reports always generate
- Full accuracy requires all ecosystem skills installed
### Standards Checked
| Standard | Version/Specification |
|----------|----------------------|
| **TYPO3 Core** | **14.3 LTS (default / gold standard)** / 13.4 LTS / 12.4 LTS |
| **PHP** | 8.2 / 8.3 / 8.4 / 8.5 (v14 floor: 8.2; ceiling: 8.5.99) |
| **Coding Style** | PSR-12 (Extended Coding Style) |
| **Architecture** | Dependency Injection (PSR-11), PSR-14 Events, PSR-15 Middleware, Fluid 5 strict VHs, Extbase PHP attributes |
| **Testing** | PHPUnit 11/12/13, TYPO3 Testing Framework 9.x, Playwright E2E |
| **Documentation** | reStructuredText (RST), TYPO3 Documentation Standards, XLIFF 2.x (v14+) |
### Conformance Areas
- **Extension Architecture** - File structure, naming conventions, required files
- **Coding Guidelines** - PSR-12 compliance, TYPO3-specific code style
- **PHP Architecture** - Dependency injection, services, events, Extbase patterns
- **Testing Standards** - Unit, functional, and Playwright E2E testing requirements
- **Best Practices** - Real-world patterns from Tea extension and core standards
## Features
### Automated Validation Scripts
- โ
**check-conformance.sh** - Main orchestration script
- ๐ **check-file-structure.sh** - File structure and directory validation
- ๐ **check-coding-standards.sh** - PSR-12 and TYPO3 code style checks
- ๐๏ธ **check-architecture.sh** - Dependency injection and architecture patterns
- ๐งช **check-testing.sh** - Testing infrastructure and coverage analysis
- ๐ **generate-report.sh** - Comprehensive conformance report generation
### Reference Documentation
**Core Standards:**
- **version-requirements.md** - Official TYPO3 and PHP version compatibility matrix
- **extension-architecture.md** - TYPO3 file structure standards
- **coding-guidelines.md** - PSR-12 and TYPO3 code style guide
- **php-architecture.md** - Dependency injection and architectural patterns
- **testing-standards.md** - Unit, functional, and Playwright E2E testing
- **best-practices.md** - Real-world patterns and project infrastructure
**Advanced Validation Guides:**
- **runtests-validation.md** - Validate Build/Scripts/runTests.sh against Tea extension reference
- **development-environment.md** - Validate DDEV/Docker development environment setup
- **directory-structure.md** - Validate .Build/ vs Build/ directory separation and organization
**Excellence Indicators:**
- **excellence-indicators.md** - Optional quality features for exceptional extensions (0-22 bonus points)
- Community & Internationalization: Crowdin, issue templates, .gitattributes, README badges
- Advanced Quality Tooling: Fractor, TYPO3 CodingStandards, StyleCI, Makefile, CI matrix
- Documentation Excellence: feature coverage for the extension scope (not file counts), modern tooling (guides.xml, screenshots.json)
- Extension Configuration: ext_conf_template.txt, composer doc scripts, multiple Sets
**Secondary References:**
- **georgringer/news** - Community reference extension demonstrating excellence patterns
### Quality Tool Configuration Templates
Production-ready configuration templates based on [TYPO3 Best Practices (Tea Extension)](https://github.com/TYPO3BestPractices/tea):
- **Build/phpstan/phpstan.neon** - PHPStan Level 10 with advanced security and type safety
- **Build/rector/rector.php** - Automated TYPO3 migrations and refactoring
- **Build/php-cs-fixer/php-cs-fixer.php** - TYPO3 coding standards with parallel execution
- **Build/composer-unused/composer-unused.php** - Dependency health monitoring
- **Build/typoscript-lint/TypoScriptLint.yml** - TypoScript quality enforcement
- **Build/eslint/.eslintrc.json** - JavaScript/TypeScript linting
- **Build/stylelint/.stylelintrc.json** - CSS/SCSS quality checks
- **Build/playwright/** - Playwright E2E and accessibility testing (Node >=22.18)
- **.github/workflows/publish-to-ter.yml** - TER publishing workflow
All templates are available in [`assets/`](assets/) and ready for direct use.
## Advanced Code Quality Tools
### PHPStan Advanced Configuration
PHPStan Level 10 represents the highest level of static analysis available, providing comprehensive type safety, security enforcement, and code quality checks. Level 10 enables bleeding-edge rules for maximum strictness and early adoption of future PHPStan features.
#### Key Features
**Type Coverage Enforcement**
The configuration enforces 100% type coverage for parameters and return types, with 95% coverage for properties. This eliminates ambiguity and enables better IDE support:
```yaml
type_coverage:
return_type: 100 # Every function must declare return type
param_type: 100 # Every parameter must have type hint
property_type: 95 # 95% of class properties must be typed
```
**Cognitive Complexity Limits**
Complexity limits prevent unmaintainable code by enforcing function and class complexity boundaries:
```yaml
cognitive_complexity:
class: 10 # Maximum complexity score per class
function: 5 # Maximum complexity score per function
```
Functions exceeding complexity limits should be refactored into smaller, focused methods. This improves testability and reduces bug density.
**Type Perfection Mode**
Advanced type safety features eliminate common type-related issues:
```yaml
type_perfect:
no_mixed_property: true # Prevents mixed type pollution
no_mixed_caller: true # Enforces concrete types in method calls
null_over_false: true # Prefers nullable types over boolean returns
narrow_param: true # Uses most specific parameter types
narrow_return: true # Uses most specific return types
```
**Security-Focused Disallowed Patterns**
The configuration integrates `spaze/phpstan-disallowed-calls` to prevent security vulnerabilities:
1. **PSR-7 Enforcement**: Disallows superglobals ($_GET, $_POST, $_SERVER, etc.), enforcing PSR-7 ServerRequestInterface usage
2. **Debug Function Prevention**: Blocks var_dump(), debug(), dd() to prevent information disclosure
3. **Legacy API Prevention**: Disallows deprecated functions like header() in favor of PSR-7 responses
Example violation and fix:
```php
// โ PHPStan Error: Use PSR-7 ServerRequestInterface instead
public function processForm(): void
{
$username = $_POST['username'];
}
// โ
Correct PSR-7 Implementation
public function processForm(ServerRequestInterface $request): void
{
$parsedBody = $request->getParsedBody();
$username = $parsedBody['username'] ?? '';
}
```
#### Setup Instructions
1. **Install Dependencies**
```bash
composer require --dev phpstan/phpstan:^1.12
composer require --dev phpstan/extension-installer:^1.4
composer require --dev saschaegerer/phpstan-typo3:^1.10
composer require --dev spaze/phpstan-disallowed-calls:^3.4
```
2. **Copy Configuration Template**
```bash
mkdir -p Build/phpstan
cp ~/.claude/skills/typo3-conformance/assets/Build/phpstan/phpstan.neon Build/phpstan/
cp ~/.claude/skills/typo3-conformance/assets/Build/phpstan/phpstan-baseline.neon Build/phpstan/
```
3. **Customize for Your Extension**
Edit `Build/phpstan/phpstan.neon`:
- Adjust `phpVersion` to match your ext_emconf.php constraint
- Modify `paths` if you have non-standard directories
- Update `type_coverage.property_type` if 95% is too strict initially
4. **Generate Baseline** (for existing projects)
```bash
vendor/bin/phpstan analyze --generate-baseline Build/phpstan/phpstan-baseline.neon
```
This captures existing violations, allowing gradual improvement without blocking development.
5. **Add Composer Script**
```json
{
"scripts": {
"ci:php:stan": "phpstan analyze --configuration Build/phpstan/phpstan.neon --no-progress"
}
}
```
6. **Integrate with CI**
```yaml
# .github/workflows/ci.yml
- name: PHPStan Analysis
run: composer ci:php:stan
```
#### Baseline Management
The baseline file captures known violations to prevent regression. As code improves, regenerate the baseline:
```bash
# Remove baseline to see all current violations
rm Build/phpstan/phpstan-baseline.neon
vendor/bin/phpstan analyze --configuration Build/phpstan/phpstan.neon
# Fix violations, then regenerate baseline for remaining issues
vendor/bin/phpstan analyze --generate-baseline Build/phpstan/phpstan-baseline.neon
```
**Best Practice**: Treat baseline regeneration as a quality gate. Each sprint, dedicate time to reducing baseline entries rather than expanding it.
#### Progressive Adoption
For extensions not yet at Level 10, adopt progressively:
1. Start at Level 6, establish baseline
2. Increase to Level 7, fix new violations
3. Add type_coverage with 80% thresholds
4. Increase to Level 8, fix violations
5. Add cognitive_complexity limits
6. Reach Level 9, add type_perfect rules
7. Increase to Level 10 for bleeding-edge rules
8. Gradually increase type_coverage to 100%
### Rector Integration
Rector provides automated refactoring and TYPO3 version migration capabilities, significantly reducing manual upgrade effort. The tea extension demonstrates comprehensive Rector integration for both PHP and TYPO3 modernization.
#### Core Capabilities
**TYPO3 Version Migration**
Rector automates the majority of breaking changes between TYPO3 versions:
```php
->withSets([
Typo3LevelSetList::UP_TO_TYPO3_12, // Applies all migrations up to TYPO3 12
])
```
Available migration sets:
- `UP_TO_TYPO3_11` - Migrates from TYPO3 v10 to v11
- `UP_TO_TYPO3_12` - Migrates from TYPO3 v10/11 to v12
- `UP_TO_TYPO3_13` - Migrates from TYPO3 v10/11/12 to v13
Each set includes dozens of automated transformations handling:
- Namespace changes and class renames
- Method signature updates
- Deprecated API replacements
- Configuration file format updates
**ExtEmConfRector - Automatic Constraint Maintenance**
The `ExtEmConfRector` automatically updates `ext_emconf.php` version constraints based on your configuration:
```php
->withConfiguredRule(ExtEmConfRector::class, [
ExtEmConfRector::PHP_VERSION_CONSTRAINT => '8.2.0-8.5.99',
ExtEmConfRector::TYPO3_VERSION_CONSTRAINT => '12.4.0-12.4.99',
])
```
When you migrate to TYPO3 v13, simply update the configuration:
```php
ExtEmConfRector::TYPO3_VERSION_CONSTRAINT => '13.0.0-13.99.99',
```
Rector will automatically update your `ext_emconf.php` during the next run, ensuring version constraints remain synchronized with code changes.
**PHPUnit Modernization**
The PHPUnit set modernizes test code to current best practices. Note that TYPO3 v13 and v14.3 LTS ship with `typo3/testing-framework:^9.5`, which accepts PHPUnit `^11.2.5 || ^12.1.2 || ^13.0.2` โ so this set delivers you from PHPUnit 9/10-era syntax into the 11/12/13-compatible space:
```php
->withSets([
PHPUnitSetList::PHPUNIT_100, // PHPUnit 10+ syntax (forward-compatible with 11/12/13)
])
```
Transformations include:
- `@expectedException` annotations โ `$this->expectException()`
- `assertContains()` for strings โ `assertStringContainsString()`
- Namespace updates for PHPUnit 10+ compatibility
- Test method visibility updates
**Code Quality Improvements**
TYPO3-specific code quality rules enforce best practices:
```php
->withSets([
Typo3SetList::CODE_QUALITY,
Typo3SetList::GENERAL,
])
```
Example transformations:
```php
// โ Before: Implicit global variable access
function myFunction() {
global $TYPO3_CONF_VARS;
return $TYPO3_CONF_VARS['SYS']['sitename'];
}
// โ
After: Explicit global declaration
function myFunction() {
return $GLOBALS['TYPO3_CONF_VARS']['SYS']['sitename'];
}
```
#### Migration Workflow
**1. Check Mode (Dry Run)**
Always start with a dry run to preview changes:
```bash
composer ci:rector -- --dry-run
```
This shows what Rector would change without modifying files, allowing review before application.
**2. Apply Changes**
After reviewing, apply transformations:
```bash
composer ci:rector
```
**3. Validate Results**
After Rector runs, validate the changes:
```bash
# Check for syntax errors
composer ci:php:lint
# Run static analysis
composer ci:php:stan
# Run tests to ensure behavior unchanged
composer ci:tests:unit
composer ci:tests:functional
```
**4. Iterative Refinement**
For large migrations, use Rector's `--skip` option to exclude problematic rules temporarily:
```php
->withSkip([
SomeProblematicRector::class => [
__DIR__ . '/../../Classes/Legacy/',
],
])
```
Fix high-value issues first, then progressively enable more rules.
#### Setup Instructions
1. **Install Dependencies**
```bash
composer require --dev rector/rector:^1.2
composer require --dev ssch/typo3-rector:^2.9
```
For testing framework support:
```bash
composer require --dev ssch/typo3-rector-testing-framework:^2.0
```
2. **Copy Configuration Template**
```bash
mkdir -p Build/rector
cp ~/.claude/skills/typo3-conformance/assets/Build/rector/rector.php Build/rector/
```
3. **Customize Configuration**
Edit `Build/rector/rector.php`:
```php
return RectorConfig::configure()
->withPhpVersion(PhpVersion::PHP_82) // Match your minimum PHP version
->withSets([
Typo3LevelSetList::UP_TO_TYPO3_12, // Your target TYPO3 version
])
->withConfiguredRule(ExtEmConfRector::class, [
ExtEmConfRector::PHP_VERSION_CONSTRAINT => '8.2.0-8.5.99',
ExtEmConfRector::TYPO3_VERSION_CONSTRAINT => '12.4.0-12.4.99',
]);
```
4. **Add Composer Scripts**
```json
{
"scripts": {
"ci:rector": "rector process --config Build/rector/rector.php --no-progress",
"fix:rector": "rector process --config Build/rector/rector.php"
}
}
```
5. **Integrate with CI**
```yaml
# .github/workflows/ci.yml
- name: Rector Check
run: composer ci:rector -- --dry-run
```
#### TYPO3 Version Upgrade Strategy
When upgrading between major TYPO3 versions:
1. **Prepare**: Review TYPO3 changelog for breaking changes
2. **Update Rector**: Ensure ssch/typo3-rector supports target version
3. **Configure**: Update `Typo3LevelSetList` to target version
4. **Dry Run**: `composer ci:rector -- --dry-run` to preview changes
5. **Backup**: Commit current state or create backup
6. **Apply**: `composer ci:rector` to apply transformations
7. **Manual Review**: Not all changes can be automated - review diff carefully
8. **Test**: Run full test suite, manual testing for critical functionality
9. **Update Constraints**: Verify ext_emconf.php constraints updated correctly
10. **Document**: Note any manual changes required in upgrade documentation
#### Common Rector Patterns
**Namespace Changes**
```php
// TYPO3 v12: Namespace consolidation
// Old: TYPO3\CMS\Core\Utility\ExtensionManagementUtility
// New: TYPO3\CMS\Core\Utility\ExtensionManagementUtility (no change in v12, but automated in future versions)
```
**API Replacements**
```php
// โ Before: Deprecated GeneralUtility method
GeneralUtility::getIndpEnv('TYPO3_REQUEST_HOST');
// โ
After: Modern API usage
$normalizedParams = $request->getAttribute('normalizedParams');
$host = $normalizedParams->getRequestHost();
```
**Configuration File Updates**
Rector can update TCA, TypoScript, and other configuration formats to current standards automatically.
### Frontend Code Quality
Modern TYPO3 extensions increasingly include JavaScript and CSS for backend modules and frontend functionality. The tea extension demonstrates parity between PHP and frontend quality tools, ensuring consistent code standards across all languages.
#### ESLint for JavaScript/TypeScript
ESLint enforces JavaScript code quality and catches common errors before runtime.
**Configuration Highlights** (`.eslintrc.json`):
```json
{
"extends": ["eslint:recommended"],
"env": {
"browser": true,
"es2021": true
},
"rules": {
"no-console": "warn", // Prevent console.log in production
"no-debugger": "error", // Block debugger statements
"no-alert": "warn", // Discourage alert() usage
"prefer-const": "error", // Enforce const for immutable variables
"no-var": "error" // Enforce let/const over var
}
}
```
**Key Benefits**:
- **Error Prevention**: Catches undefined variables, unreachable code, syntax errors
- **Modern JavaScript**: Enforces ES2021+ features (const/let, arrow functions, template literals)
- **Security**: Prevents debugger statements and console output in production builds
- **Consistency**: Standardizes code style across team members
**Setup**:
```bash
# Install ESLint
npm install --save-dev eslint
# Copy configuration
mkdir -p Build/eslint
cp ~/.claude/skills/typo3-conformance/assets/Build/eslint/.eslintrc.json Build/eslint/
# Add script to package.json
{
"scripts": {
"lint:js": "eslint Resources/Public/JavaScript --config Build/eslint/.eslintrc.json"
}
}
# Run linting
npm run lint:js
```
**CI Integration**:
```yaml
# .github/workflows/ci.yml
- name: JavaScript Linting
run: npm run lint:js
```
#### Stylelint for CSS/SCSS
Stylelint enforces CSS and SCSS quality, preventing errors and maintaining consistent styling conventions.
**Configuration Highlights** (`.stylelintrc.json`):
```json
{
"extends": "stylelint-config-standard",
"rules": {
"indentation": 2,
"string-quotes": "single",
"no-descending-specificity": null,
"selector-class-pattern": null
}
}
```
**Key Benefits**:
- **Error Prevention**: Catches invalid CSS, duplicate properties, unknown properties
- **Best Practices**: Enforces selector specificity limits, property order conventions
- **Consistency**: Standardizes indentation, quotes, and formatting
- **Framework Support**: Works with CSS, SCSS, Less, and CSS-in-JS
**Setup**:
```bash
# Install Stylelint
npm install --save-dev stylelint stylelint-config-standard
# Copy configuration
mkdir -p Build/stylelint
cp ~/.claude/skills/typo3-conformance/assets/Build/stylelint/.stylelintrc.json Build/stylelint/
# Add script to package.json
{
"scripts": {
"lint:css": "stylelint Resources/Public/Css --config Build/stylelint/.stylelintrc.json"
}
}
# Run linting
npm run lint:css
```
**CI Integration**:
```yaml
# .github/workflows/ci.yml
- name: CSS Linting
run: npm run lint:css
```
#### Package.json Structure
Comprehensive frontend tooling requires proper package.json configuration:
```json
{
"name": "typo3-extension-yourextension",
"version": "1.0.0",
"private": true,
"scripts": {
"lint:js": "eslint Resources/Public/JavaScript --config Build/eslint/.eslintrc.json",
"lint:css": "stylelint Resources/Public/Css --config Build/stylelint/.stylelintrc.json",
"lint": "npm run lint:js && npm run lint:css",
"fix:js": "eslint Resources/Public/JavaScript --config Build/eslint/.eslintrc.json --fix",
"fix:css": "stylelint Resources/Public/Css --config Build/stylelint/.stylelintrc.json --fix",
"fix": "npm run fix:js && npm run fix:css"
},
"devDependencies": {
"eslint": "^8.57.0",
"stylelint": "^16.8.0",
"stylelint-config-standard": "^36.0.0"
}
}
```
#### Local-CI Parity
The tea extension demonstrates critical architectural principle: **identical tooling locally and in CI**. This prevents "works on my machine" issues.
**Local Execution**:
```bash
npm run lint # Same command developers run locally
```
**CI Execution**:
```yaml
- name: Frontend Linting
run: npm run lint # Identical command in CI
```
Benefits:
- **Predictability**: CI failures reproducible locally
- **Fast Feedback**: Catch issues before pushing
- **Developer Experience**: Same commands across environments
### Supplementary Linting Tools
Beyond core PHP and frontend linting, the tea extension demonstrates additional specialized tools for comprehensive quality coverage.
#### TypoScript Linting
TypoScript configuration errors can cause runtime issues difficult to diagnose. TypoScriptLint provides static analysis for TypoScript files.
**Configuration** (`TypoScriptLint.yml`):
```yaml
sniffs:
- class: Indentation
parameters:
indentPerLevel: 2
useSpaces: true
- class: DeadCode # Detects unused TypoScript
- class: OperatorWhitespace
- class: DuplicateAssignment
- class: NestingConsistency
```
**Setup**:
```bash
composer require --dev helmich/typo3-typoscript-lint:^3.2
mkdir -p Build/typoscript-lint
cp ~/.claude/skills/typo3-conformance/assets/Build/typoscript-lint/TypoScriptLint.yml Build/typoscript-lint/
# Add composer script
{
"scripts": {
"ci:typoscript:lint": "typoscript-lint --config Build/typoscript-lint/TypoScriptLint.yml Configuration/TypoScript"
}
}
```
**Common Violations**:
```typoscript
# โ Inconsistent indentation
page = PAGE
page {
10 = TEXT
10.value = Hello
}
# โ
Consistent 2-space indentation
page = PAGE
page {
10 = TEXT
10.value = Hello
}
```
#### Composer Dependency Health
**composer-unused**: Identifies unused dependencies, reducing package bloat and security surface.
```bash
composer require --dev icanhazstring/composer-unused:^0.8
# Copy configuration
mkdir -p Build/composer-unused
cp ~/.claude/skills/typo3-conformance/assets/Build/composer-unused/composer-unused.php Build/composer-unused/
# Run analysis
vendor/bin/composer-unused --configuration Build/composer-unused/composer-unused.php
```
**composer-normalize**: Enforces consistent composer.json formatting.
```bash
composer require --dev ergebnis/composer-normalize:^2.43
# Add composer script
{
"scripts": {
"ci:composer:normalize": "composer-normalize --dry-run",
"fix:composer:normalize": "composer-normalize"
}
}
```
#### JSON and XLIFF Validation
**JSON Linting**: Prevents malformed JSON in extension configuration.
```json
{
"scripts": {
"ci:json:lint": "find . -name '*.json' -not -path './.Build/*' -exec php -l {} \\;"
}
}
```
**XLIFF Validation**: Ensures translation files are well-formed XML.
```bash
composer require --dev symfony/translation:^6.4
# Add validation script
{
"scripts": {
"ci:xliff:lint": "php Build/Scripts/validateXliff.php"
}
}
```
### Architectural Patterns and Best Practices
#### Progressive Quality Adoption
The tea extension demonstrates **progressive enhancement** philosophy for quality tools. Extensions at different maturity levels can adopt incrementally:
**Phase 1 - Foundation** (MVP Extensions):
- PHPStan Level 6
- Basic PSR-12 via php-cs-fixer
- Unit tests with >50% coverage
**Phase 2 - Intermediate** (Production Extensions):
- PHPStan Level 8 with type_coverage at 80%
- Rector for TYPO3 migrations
- Functional tests with >60% coverage
- CI integration for all tools
**Phase 3 - Advanced** (Reference Extensions):
- PHPStan Level 10 with 100% type_coverage
- Cognitive complexity limits
- Security-focused disallowed patterns
- Frontend linting (ESLint, Stylelint)
- >70% test coverage with mutation testing
**Phase 4 - Excellence** (Showcase Extensions like Tea):
- Type perfection mode
- Comprehensive CI matrix (multiple PHP/TYPO3 versions)
- Multi-database testing
- Accessibility compliance
- Performance budgets
#### Local-CI Parity Architecture
**Core Principle**: Every quality check runnable locally must use identical configuration and tooling in CI.
**Implementation**:
1. **Centralized Configuration**: All tool configs in `Build/` directory
2. **Composer Scripts**: Define all commands in composer.json scripts section
3. **CI Uses Scripts**: GitHub Actions/GitLab CI calls composer scripts, not direct tool invocation
Example:
```json
{
"scripts": {
"ci:php:lint": "find *.php Classes Configuration Tests -name '*.php' -print0 | xargs -0 -n1 -P4 php -dxdebug.mode=off -l",
"ci:php:stan": "phpstan analyze --configuration Build/phpstan/phpstan.neon",
"ci:rector": "rector process --config Build/rector/rector.php --dry-run",
"ci:tests:unit": "phpunit --configuration Build/phpunit/UnitTests.xml",
"ci": [
"@ci:php:lint",
"@ci:php:stan",
"@ci:rector",
"@ci:tests:unit"
]
}
}
```
**Benefits**:
- Developers run `composer ci` locally before pushing
- CI runs `composer ci` with identical behavior
- Configuration changes automatically apply to both environments
- Tool version consistency via composer.lock
#### Tool Responsibility Separation
Each tool has distinct responsibilities to prevent overlap and confusion:
| Tool | Responsibility | When to Run |
|------|----------------|-------------|
| **PHP Lint** | Syntax errors | Pre-commit, CI |
| **php-cs-fixer** | Code formatting, PSR-12 compliance | Pre-commit (auto-fix), CI |
| **PHPStan** | Type safety, static analysis, security | Pre-push, CI |
| **Rector** | Automated refactoring, migrations | Manual, CI (dry-run) |
| **PHPUnit** | Runtime correctness, behavior validation | Pre-push, CI |
| **ESLint** | JavaScript quality, errors | Pre-commit (auto-fix), CI |
| **Stylelint** | CSS quality, formatting | Pre-commit (auto-fix), CI |
**Anti-Pattern**: Don't use PHPStan to check formatting (use php-cs-fixer). Don't use php-cs-fixer for type checking (use PHPStan). Each tool excels at its purpose.
#### Parallel Execution Optimization
The tea extension demonstrates performance optimization for quality tools:
**php-cs-fixer Parallelization**:
```php
$config->setParallelConfig(ParallelConfigFactory::detect());
```
Automatically detects CPU cores and parallelizes analysis, reducing execution time by 60-80% on multi-core systems.
**PHPStan Parallelization**:
```yaml
parallel:
maximumNumberOfProcesses: 5
```
Limits parallel processes to prevent resource exhaustion while maintaining speed.
**CI Matrix Parallelization**:
```yaml
strategy:
matrix:
php: ['8.2', '8.3', '8.4']
typo3: ['12.4', '13.0']
```
Tests run concurrently across combinations, providing fast feedback on compatibility.
## Installation
### Marketplace (Recommended)
Add the [Netresearch marketplace](https://github.com/netresearch/claude-code-marketplace) once, then browse and install skills:
```bash
# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install typo3-conformance@netresearch-claude-code-marketplace
```
### Without a marketplace
Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own, including the commands this repo ships:
```bash
mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/typo3-conformance-skill.git \
~/.claude/skills/typo3-conformance
```
It loads as `typo3-conformance@skills-dir` on the next session. Update with `git -C ~/.claude/skills/typo3-conformance pull` and start a new session; remove it by deleting the directory. This route has no `claude plugin update`.
### npx ([skills.sh](https://skills.sh))
Install with any [Agent Skills](https://agentskills.io)-compatible agent:
```bash
npx skills add https://github.com/netresearch/typo3-conformance-skill --skill typo3-conformance
```
> **Limitation:** `npx skills` installs `SKILL.md`-based skills only. This repo also ships `commands`, which it does not install โ use the marketplace or the skills directory for those.
### Download Release
Download the [latest release](https://github.com/netresearch/typo3-conformance-skill/releases/latest) and extract to your agent's skills directory.
### Git Clone
```bash
git clone https://github.com/netresearch/typo3-conformance-skill.git
```
### Composer (PHP Projects)
```bash
composer require netresearch/typo3-conformance-skill
```
Requires [netresearch/composer-agent-skill-plugin](https://github.com/netresearch/composer-agent-skill-plugin).
## Usage
### Automated Conformance Checking
```bash
# Check current directory
cd /path/to/your-extension
~/.claude/skills/typo3-conformance/scripts/check-conformance.sh
# Check specific directory
~/.claude/skills/typo3-conformance/scripts/check-conformance.sh /path/to/your-extension
```
### Individual Checks
```bash
# File structure only
scripts/check-file-structure.sh /path/to/extension
# Coding standards only
scripts/check-coding-standards.sh /path/to/extension
# Architecture only
scripts/check-architecture.sh /path/to/extension
# Testing only
scripts/check-testing.sh /path/to/extension
```
### Claude Code Integration
#### Manual Invocation
```
/skill typo3-conformance
```
#### Automatic Activation
The skill activates automatically when:
- Analyzing TYPO3 extensions
- Checking code quality
- Reviewing standards compliance
- Evaluating extension architecture
### Example Workflows
**Quick Conformance Check:**
```
User: "Check if my TYPO3 extension follows current standards"
Claude: [Activates typo3-conformance skill]
- Analyzes file structure
- Checks coding standards
- Evaluates architecture patterns
- Reviews testing infrastructure
- Generates comprehensive conformance report
```
**Detailed Architecture Review:**
```
User: "Review the PHP architecture of my extension for TYPO3 best practices"
Claude: [Activates typo3-conformance skill]
- Focuses on dependency injection patterns
- Checks for deprecated patterns (GeneralUtility::makeInstance, $GLOBALS)
- Evaluates PSR-14 event system usage
- Reviews Extbase architecture if applicable
- Provides specific migration recommendations
```
**Pre-TER Publication Check:**
```
User: "My extension is ready for TER publication, please verify it meets all requirements"
Claude: [Activates typo3-conformance skill]
- Verifies all required files present (composer.json, ext_emconf.php, Documentation/)
- Checks file structure compliance
- Validates coding standards
- Reviews architecture patterns
- Assesses testing coverage
- Generates publication readiness report
```
## Conformance Report
The skill generates comprehensive markdown reports with dual scoring system:
### Dual Scoring System (0-122 Total)
**Base Conformance (0-100 points) - MANDATORY**
- Extension Architecture: 0-20 points
- Coding Guidelines: 0-20 points
- PHP Architecture: 0-20 points
- Testing Standards: 0-20 points
- Best Practices: 0-20 points
`scripts/check-conformance.sh` scores the base categories mechanically on the same scale: file structure (Extension Architecture), coding standards, PHP architecture and testing at up to 20 points each, and Best Practices as documentation (up to 10) plus PHPStan baseline hygiene (up to 10).
**Excellence Indicators (0-22 points) - OPTIONAL BONUS**
- Community & Internationalization: 0-6 points
- Advanced Quality Tooling: 0-9 points
- Documentation Excellence: 0-4 points
- Extension Configuration: 0-3 points
**Interpretation:**
- Base conformance (0-100): Core TYPO3 standards compliance (pass/fail criteria)
- Excellence indicators (0-22): Bonus points for exceptional quality (NEVER penalized if missing)
- Extensions scoring 100/100 base are fully conformant, regardless of excellence score
- Excellence indicators identify community reference-level extensions
### Detailed Analysis
- โ
Strengths and passed checks
- โ Critical issues requiring immediate action
- โ ๏ธ Warnings and recommendations
- ๐ Test coverage estimates
- ๐ก Migration guides and examples
- ๐ Excellence features detected (bonus category)
### Priority Action Items
- **High Priority** - Critical issues blocking functionality or security
- **Medium Priority** - Important conformance issues
- **Low Priority** - Minor style and optimization improvements
- **Excellence Opportunities** - Optional advanced features for reference-level quality
## Example Report Output
```markdown
# TYPO3 Extension Conformance Report
**Extension:** my_extension (v1.0.0)
---
## Score Summary
**Base Conformance:** 75/100
**Excellence Indicators:** 8/22 (Bonus)
**Total Score:** 83/122
### Base Conformance Breakdown
| Category | Score | Status |
|----------|-------|--------|
| Extension Architecture | 18/20 | โ
Passed |
| Coding Guidelines | 15/20 | โ ๏ธ Issues |
| PHP Architecture | 16/20 | โ
Passed |
| Testing Standards | 14/20 | โ ๏ธ Issues |
| Best Practices | 12/20 | โ ๏ธ Issues |
### Excellence Indicators (Bonus)
| Category | Score | Status |
|----------|-------|--------|
| Community & Internationalization | 4/6 | ๐ Good |
| Advanced Quality Tooling | 2/9 | โก Basic |
| Documentation Excellence | 1/4 | ๐ Standard |
| Extension Configuration | 1/3 | โ๏ธ Minimal |
**Excellence Highlights:**
- โ
Crowdin integration (+2)
- โ
Professional README badges (+2)
- โ
Fractor configuration (+2)
- โ
Documentation Excellence 1/4 (focused scope, user coverage โฅ60%)
- โ
Composer doc scripts (+1)
## Critical Issues
- โ 15 files missing declare(strict_types=1)
- โ 12 instances of GeneralUtility::makeInstance()
- โ Low test coverage (45% < 70% recommended)
## Recommendations
1. Add declare(strict_types=1) to all PHP files
2. Migrate to constructor injection
3. Increase unit test coverage
## Excellence Opportunities
- ๐ Add TYPO3 CodingStandards package (+1 point)
- ๐ Implement CI testing matrix (+2 points)
- ๐ Add modern documentation tooling (guides.xml, screenshots.json) โ raises documentation quality q
- ๐ Create multiple Configuration/Sets/ presets (+1 point)
```
## Reference Standards
This skill is based on official TYPO3 documentation:
- [Extension Architecture](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/)
- [Coding Guidelines](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/CodingGuidelines/)
- [PHP Architecture](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/PhpArchitecture/)
- [Testing](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Testing/)
- [Tea Extension (Best Practice)](https://github.com/TYPO3BestPractices/tea)
## Scoring System
### Base Conformance (0-100 points)
**Extension Architecture (20 points)**
- Required files present: 8 points
- Directory structure conformant: 6 points
- Naming conventions followed: 4 points
- No critical violations: 2 points
**Coding Guidelines (20 points)**
- PSR-12 compliance: 8 points
- Type declarations: 4 points
- PHPDoc completeness: 4 points
- Naming conventions: 4 points
**PHP Architecture (20 points)**
- Dependency injection: 8 points
- No deprecated patterns: 6 points
- Modern event system: 4 points
- Service configuration: 2 points
**Testing Standards (20 points)**
- Test coverage >70%: 10 points
- Proper test structure: 6 points
- Configuration files present: 4 points
**Best Practices (20 points)**
- Development environment (DDEV/Docker): 6 points
- Build scripts (runTests.sh): 6 points
- Directory structure (.Build/ vs Build/): 4 points
- Quality tools configured: 2 points
- Documentation complete: 2 points
### Excellence Indicators (0-22 bonus points)
**Community & Internationalization (0-6 points)**
- Crowdin integration: +2 points
- GitHub issue templates: +1 point
- .gitattributes export-ignore: +1 point
- Professional README badges: +2 points
**Advanced Quality Tooling (0-9 points)**
- Fractor configuration: +2 points
- TYPO3 CodingStandards package: +1 point
- StyleCI integration: +1 point
- Makefile with self-documenting help: +1 point
- CI testing matrix (3+ PHP versions + composerInstall variants): +2 points
- TER publish workflow: +2 points
**Documentation Excellence (0-4 points)** โ feature coverage, not file counts
- Scope by class count: focused (โค30) / medium (31-100) / large (>100)
- focused: user coverage โฅ90% + quality โฅ80% โ 3 (developer docs optional, never penalized)
- medium: user โฅ90% + developer โฅ80% โ 4; โฅ40% developer โ 3; user โฅ80% โ 2
- large: average of user+developer coverage โฅ90% โ 4; โฅ75% โ 3; โฅ60% โ 2
- Quality includes modern tooling (guides.xml, screenshots.json)
**Extension Configuration (0-3 points)**
- ext_conf_template.txt: +1 point
- Composer documentation scripts: +1 point
- Multiple Configuration/Sets/ presets: +1 point
**Excellence Interpretation:**
- 0-5 points: Standard extension (meets requirements)
- 6-10 points: Good practices (actively maintained)
- 11-15 points: Excellent quality (community reference level)
- 16-22 points: Outstanding (georgringer/news level)
## Common Issues Detected
### Critical (Must Fix)
- Missing composer.json or ext_emconf.php
- PHP files in extension root
- Missing Configuration/Services.yaml
- Using GeneralUtility::makeInstance() instead of DI
- Accessing $GLOBALS instead of DI
- No unit tests
### High Priority
- Missing declare(strict_types=1)
- Old array() syntax instead of []
- Missing PHPDoc comments
- ext_tables.php usage (deprecated)
- Missing test coverage
### Medium Priority
- Incomplete documentation
- Missing quality tools configuration
- No CI/CD pipeline
- Inconsistent code formatting
## Migration Guides
### From GeneralUtility::makeInstance to Constructor Injection
```php
// โ Before (Deprecated)
use TYPO3\CMS\Core\Utility\GeneralUtility;
class MyService
{
public function doSomething(): void
{
$repository = GeneralUtility::makeInstance(ProductRepository::class);
}
}
// โ
After (Modern)
class MyService
{
public function __construct(
private readonly ProductRepository $repository
) {}
public function doSomething(): void
{
// Use $this->repository
}
}
```
### From ext_tables.php to Configuration/Backend/Modules.php
```php
// โ Before (ext_tables.php - Deprecated)
ExtensionUtility::registerModule(
'MyExtension',
'web',
'mymodule',
'',
[
\Vendor\MyExtension\Controller\BackendController::class => 'list,show',
]
);
// โ
After (Configuration/Backend/Modules.php - Modern)
return [
'web_myext' => [
'parent' => 'web',
'position' => ['after' => 'web_info'],
'access' => 'user',
'path' => '/module/web/myext',
'labels' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_mod.xlf',
'extensionName' => 'MyExtension',
'controllerActions' => [
\Vendor\MyExtension\Controller\BackendController::class => [
'list',
'show',
],
],
],
];
```
## Contributing
Contributions are welcome! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/improvement`)
3. Make your changes
4. Test thoroughly
5. Commit your changes (`git commit -m 'Add improvement'`)
6. Push to the branch (`git push origin feature/improvement`)
7. Create a Pull Request
The commands for working on this repository are listed in [AGENTS.md](AGENTS.md#commands).
### Tests
`python3 tests/test_scripts.py` runs the behaviour tests for the shipped scripts. It needs Python 3 (standard library only), Bash and Git. Each test builds a small TYPO3 extension or Git repository in a temporary directory, runs one script as a subprocess and checks its exit code and output:
- the six check scripts under `skills/typo3-conformance/scripts/`: a conformant extension passes, and each defect they look for (missing files and directories, `$GLOBALS` access, `GeneralUtility::makeInstance()` outside tasks and form elements, missing `strict_types`, `array()`, a low test ratio, a grown PHPStan baseline, root PHP files) is reported with a non-zero exit code;
- `check-conformance.sh` and `generate-report.sh`: relative and absolute target paths, rejected targets, the summary table and the action checklist of the written report;
- `Build/Scripts/check-plugin-version.sh` and `scripts/verify-harness.sh`.
A failure prints the test name and the failed assertion; most assertions include the script's output. CI runs the suite on every pull request and every push to `main` through [`.github/workflows/tests.yml`](.github/workflows/tests.yml). New or changed script behaviour needs a test in `tests/test_scripts.py` in the same pull request.
`pre-commit run --all-files` runs the hooks of [`.pre-commit-config.yaml`](.pre-commit-config.yaml) locally (skill validator, version parity, markdownlint, yamllint, actionlint, Ruff, ShellCheck); Skill Validation runs the same linters in CI.
### Dependencies
- **Scripts:** Bash and the standard tools `grep`, `find`, `awk`, `sed`, `tr` and `git`; `check-plugin-version.sh` also uses `python3`, and `scripts/verify-harness.sh` uses the `gh` CLI for one optional lookup when it is installed. Nothing is installed at run time.
- **Tests:** Python 3 standard library only.
- **Composer:** `composer.json` requires `netresearch/composer-agent-skill-plugin`, which installs the skill into a PHP project. The constraint is `*`, and no `composer.lock` is committed, so the latest release is resolved at install time.
- **Development tools:** the pre-commit hooks are pinned by `rev:` in `.pre-commit-config.yaml`. Renovate ([`renovate.json`](renovate.json), `config:recommended` with the pre-commit manager enabled) proposes updates for them.
- **CI:** the workflows call reusable workflows of `netresearch/.github`, `netresearch/skill-repo-skill` and `netresearch/typo3-ci-workflows`, which pin the actions they use by commit SHA.
- **Templates:** the tools configured by the files under `skills/typo3-conformance/assets/` (PHPStan, Rector, PHP-CS-Fixer, ESLint, Stylelint, TypoScript lint, composer-unused) are dependencies of the extension that copies them, not of this repository.
## Governance and policies
This repository follows the Netresearch organisation policies:
- [Governance](https://github.com/netresearch/.github/blob/main/GOVERNANCE.md): ownership, roles, and how decisions are made and disputes resolved.
- [Roadmap](https://github.com/netresearch/.github/blob/main/ROADMAP.md): planned and explicitly excluded work for the coming year.
- [Handling of dependency and code analysis findings](https://github.com/netresearch/.github/blob/main/SECURITY.md#handling-of-dependency-and-code-analysis-findings): thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
- [Secret management](https://github.com/netresearch/.github/blob/main/SECURITY.md#secret-management): how CI and release credentials are stored, accessed and rotated.
- [Access roster](https://github.com/netresearch/.github/blob/main/docs/access-roster.md): who holds administrative access to this repository and the organisation.
The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in [docs/SECURITY-ASSURANCE.md](docs/SECURITY-ASSURANCE.md).
Checks that run on pull requests in this repository:
- Every pull request: Skill Validation (`lint.yml`: skill structure, manifest and version sync, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck, Ruff, checkpoint schema), Eval Validation (`eval-validate.yml`) and Skill Tests (`tests.yml`: `tests/test_scripts.py`).
- Pull requests to `main`: `security.yml` with Betterleaks (secret scanning), zizmor (workflow static analysis), dependency review (fails on vulnerabilities of severity high or above), Composer Audit and Opengrep SAST (findings handled under the [organisation's static analysis rule](https://github.com/netresearch/.github/blob/main/SECURITY.md#static-analysis-sast)), and CodeQL (the GitHub Actions workflows and Python); Harness Verification (`harness-verify.yml`) and Template Drift (`check-template-drift.yml`).
- Every pull request: PR Quality Gates (`pr-quality.yml`, which approves pull requests whose author has write, maintain or admin permission and checks nothing else), and from the template workflows Labeler (`labeler.yml`) and the dependency auto-merge job (`auto-merge-deps.yml`, skipped unless a dependency bot opened the pull request).
- Configured outside the workflows: SonarCloud code analysis, the DCO sign-off check, Copilot code review (a repository ruleset), CodeRabbit review, and GitHub secret scanning with push protection.
## License
This project uses split licensing:
- **Code** (scripts, workflows, configs): [MIT](LICENSE-MIT)
- **Content** (skill definitions, documentation, references): [CC-BY-SA-4.0](LICENSE-CC-BY-SA-4.0)
See the individual license files for full terms.
## Support
**Issues and Questions:**
- GitHub Issues: [Report issues](https://github.com/netresearch/typo3-conformance-skill/issues)
- TYPO3 Slack: [#typo3-cms](https://typo3.slack.com/archives/typo3-cms)
## Credits
Created by Netresearch DTT GmbH for the TYPO3 community.
Based on:
- [TYPO3 Official Documentation Standards](https://docs.typo3.org/)
- [TYPO3 Extension Architecture](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/)
- [TYPO3 Coding Guidelines](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/CodingGuidelines/)
- [TYPO3 Best Practices Tea Extension](https://github.com/TYPO3BestPractices/tea)
## Acknowledgments
This skill is built upon the foundational work of the TYPO3 community. We gratefully acknowledge:
- **[TYPO3 Core Development Team](https://typo3.org/community/teams/typo3-development)** โ For establishing and maintaining the extension architecture standards, coding guidelines, dependency injection patterns, and PSR-14 event system that form the basis of this conformance checker.
- **[TYPO3 Best Practices Team](https://typo3.org/community/teams/best-practices)** โ For the exemplary [Tea Extension](https://github.com/TYPO3BestPractices/tea) that serves as the reference implementation, demonstrating production-grade quality tooling, testing infrastructure, and CI/CD patterns.
- **[TYPO3 Documentation Team](https://typo3.org/community/teams/documentation)** โ For the comprehensive official documentation that defines TYPO3 standards and makes conformance checking possible.
- **[TYPO3 Content Types Team](https://typo3.org/community/teams/content-types)** โ For their work on structured content and TCA standards that inform extension architecture best practices.
- **[TYPO3 Security Team](https://typo3.org/community/teams/security)** โ For establishing the security guidelines and patterns that inform our security-focused conformance checks.
---
**Maintained By:** Netresearch DTT GmbH
---
**Made with โค๏ธ for Open Source by [Netresearch](https://www.netresearch.de/)**