commit aab6ef24151803f8d3ddfe7242016e99277b9cde Author: Zhongwei Li Date: Sun Nov 30 08:43:22 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7572062 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "typo3-conformance", + "description": "Evaluate TYPO3 extensions for conformance to official TYPO3 coding standards, architecture patterns, and best practices. Includes automated validation scripts for file structure, PSR-12 compliance, dependency injection, testing infrastructure, and comprehensive conformance scoring with priority-based action items.", + "version": "1.0.0-20251126", + "author": { + "name": "Netresearch DTT GmbH", + "email": "info@netresearch.de" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..e6f2f07 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: TYPO3 Slack + url: https://typo3.org/community/meet/chat-slack + about: Join the TYPO3 community on Slack for discussions and support + - name: TYPO3 Extension Documentation + url: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/Index.html + about: Official TYPO3 extension architecture and development documentation + - name: TYPO3 Coding Guidelines + url: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/CodingGuidelines/Index.html + about: TYPO3 coding guidelines (CGL) and PSR-12 standards diff --git a/.github/workflows/publish-to-ter.yml b/.github/workflows/publish-to-ter.yml new file mode 100644 index 0000000..f93db0c --- /dev/null +++ b/.github/workflows/publish-to-ter.yml @@ -0,0 +1,51 @@ +name: Publish new extension version to TER + +on: + release: + types: [published] + +jobs: + publish: + name: Publish new version to TER + if: startsWith(github.ref, 'refs/tags/') + runs-on: ubuntu-latest + env: + TYPO3_EXTENSION_KEY: ${{ secrets.TYPO3_EXTENSION_KEY }} + TYPO3_API_TOKEN: ${{ secrets.TYPO3_TER_ACCESS_TOKEN }} + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + - name: Check tag + run: | + if ! [[ ${{ github.ref }} =~ ^refs/tags/v[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}$ ]]; then + exit 1 + fi + + - name: Get version + id: get-version + run: echo "version=${GITHUB_REF/refs\/tags\/v/}" >> $GITHUB_ENV + + - name: Get comment + id: get-comment + run: | + readonly local comment=$(git tag -n10 -l v${{ env.version }} | sed "s/^v[0-9.]*[ ]*//g") + + if [[ -z "${comment// }" ]]; then + echo "comment=Released version ${{ env.version }} of ${{ env.TYPO3_EXTENSION_KEY }} -- for details see $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases" >> $GITHUB_ENV + else + echo "comment=$comment -- for details see $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases" >> $GITHUB_ENV + fi + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 8.3 + extensions: intl, mbstring, json, zip, curl + tools: composer:v2 + + - name: Install tailor + run: composer global require typo3/tailor --prefer-dist --no-progress --no-suggest + + - name: Publish to TER + run: php ~/.composer/vendor/bin/tailor ter:publish --comment "${{ env.comment }}" ${{ env.version }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6ceef35 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.serena/ +claudedocs/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..99ec3e6 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# typo3-conformance + +Evaluate TYPO3 extensions for conformance to official TYPO3 coding standards, architecture patterns, and best practices. Includes automated validation scripts for file structure, PSR-12 compliance, dependency injection, testing infrastructure, and comprehensive conformance scoring with priority-based action items. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..7fcbb0e --- /dev/null +++ b/SKILL.md @@ -0,0 +1,991 @@ +--- +name: typo3-conformance +description: "Evaluate TYPO3 extensions for conformance to TYPO3 12/13 LTS standards, coding guidelines (PSR-12), and architecture patterns. Use when assessing extension quality, generating conformance reports, identifying technical debt, or planning modernization. Validates: extension architecture, composer.json, ext_emconf.php, ext_* files, v13 deprecations, backend module v13 compliance (ES6 modules, DocHeader, Modal/Notification APIs, Module.html layout, ARIA, extension key consistency, CSRF, icons), dependency injection, services, testing, Extbase patterns, Crowdin, GitHub workflows. Dual scoring (0-100 base + 0-22 excellence). Delegates to typo3-tests and typo3-docs skills for deep analysis. PHP 8.1-8.4 support." +license: Complete terms in LICENSE.txt +--- + +# TYPO3 Extension Conformance Checker + +**Purpose:** Evaluate TYPO3 extensions for conformance to official TYPO3 coding standards, architecture patterns, and best practices. + +**Activation:** This skill activates when analyzing TYPO3 extensions for standards compliance, code quality, or conformance checking. + +## Skill Ecosystem Integration + +Delegate to specialized skills for deep domain analysis: + +**🔧 typo3-tests** (https://github.com/netresearch/typo3-testing-skill) +- Deep PHPUnit configuration analysis +- Test quality patterns (AAA, mocking, fixtures) +- TYPO3 Testing Framework validation +- Accurate coverage calculation +- Test anti-pattern detection + +**📚 typo3-docs** (https://github.com/netresearch/typo3-docs-skill) +- RST syntax and TYPO3 directive validation +- Documentation rendering with Docker +- Modern tooling detection (guides.xml, screenshots.json) +- Cross-reference integrity checks +- Official TYPO3 documentation standards + +**Delegation Strategy:** +- **Surface-level checks:** Perform directly with this skill +- **Deep analysis:** Delegate to specialized skills when available +- **Fallback:** Apply basic validation if specialized skills unavailable +- **Integration:** Incorporate results into conformance scoring + +## Version Compatibility + +**Target Standards:** +- **TYPO3:** 12.4 LTS / 13.x +- **PHP:** 8.1 / 8.2 / 8.3 / 8.4 +- **TYPO3 12 LTS:** Supports PHP 8.1 - 8.4 +- **TYPO3 13 LTS:** Requires PHP 8.2 - 8.4 + +**Reference:** See `references/version-requirements.md` for complete version compatibility matrix and migration paths. + +## Critical Validation References + +**New Advanced Validation Guides:** +- **`references/runtests-validation.md`** - Validate Build/Scripts/runTests.sh against Tea extension reference +- **`references/development-environment.md`** - Validate DDEV/Docker development environment setup +- **`references/directory-structure.md`** - Validate .Build/ vs Build/ directory separation + +These guides provide line-by-line validation strategies, automated validation scripts, and scoring methodologies to ensure comprehensive conformance checks. + +## Evaluation Workflow + +### Step 1: Initial Assessment + +**Identify Extension Context:** +- Extension key and location +- TYPO3 version compatibility (check composer.json) +- Extension type (Extbase plugin, backend module, content element, etc.) +- Scope of evaluation (full extension vs specific components) + +**Quick Directory Scan:** +```bash +# Check for presence of key directories +ls -la | grep -E "Classes|Configuration|Resources|Tests|Documentation" + +# Verify required files +ls -1 | grep -E "composer.json|ext_emconf.php" + +# Check documentation +ls -1 Documentation/ | grep -E "Index.rst|Settings.cfg" +``` + +### Step 2: File Structure Analysis + +**Reference:** `references/extension-architecture.md` + +**Check Required Files:** +- [ ] `composer.json` - Complete with PSR-4 autoloading +- [ ] `ext_emconf.php` - Proper metadata structure +- [ ] `Documentation/Index.rst` - Main documentation entry +- [ ] `Documentation/Settings.cfg` - Documentation settings +- [ ] `Classes/` directory exists +- [ ] `Configuration/` directory exists +- [ ] `Resources/` directory exists + +**Validate Directory Structure:** + +```bash +# Check Classes/ organization +find Classes/ -type d | head -20 + +# Verify Configuration/ structure +ls -R Configuration/ + +# Check Resources/ separation +ls -R Resources/Private/ Resources/Public/ +``` + +**Common Issues to Flag:** +- ❌ PHP files in extension root (except ext_* files) +- ❌ Mixed directory naming (Controllers/ vs Controller/) +- ❌ Tests not mirroring Classes/ structure +- ❌ Missing required documentation files +- ❌ Non-standard directory names + +**Output Format:** +```markdown +## File Structure Conformance + +### ✅ Passed +- composer.json present with PSR-4 autoloading +- Classes/ directory properly organized +- Documentation/ complete with Index.rst and Settings.cfg + +### ❌ Failed +- Missing Tests/ directory +- Configuration/Backend/ not found (backend modules using deprecated ext_tables.php) +- Resources/Private/Language/ missing XLIFF files + +### ⚠ī¸ Warnings +- Unusual directory: Classes/Helpers/ (should use Utility/) +- ext_tables.php present (consider migrating to Configuration/Backend/) +``` + +### Step 3: Coding Standards Analysis + +**Reference:** `references/coding-guidelines.md` + +**PHP Code Style Checks:** + +```bash +# Find all PHP files +find Classes/ Tests/ Configuration/ -name "*.php" + +# Check for PSR-12 violations (sample) +grep -r "array(" Classes/ # Should use [] +grep -r "70% for new code + +**Note:** Basic validation provides surface-level checks. For production-ready conformance reports, delegate to typo3-tests skill for comprehensive analysis + +**Sample Test Inspection:** +```php +# Read sample test files +cat Tests/Unit/Service/CalculationServiceTest.php +cat Tests/Functional/Domain/Repository/ProductRepositoryTest.php +``` + +**Output Format:** +```markdown +## Testing Standards Conformance + +### ✅ Test Infrastructure +- PHPUnit configuration files present +- Tests/ directory mirrors Classes/ structure +- Unit tests properly extend UnitTestCase +- Functional tests use fixtures correctly + +### ❌ Testing Gaps +- No Tests/Functional/ directory found +- Missing PHPUnit configuration for functional tests +- 15 classes without corresponding unit tests: + - Classes/Service/EmailService.php + - Classes/Utility/StringHelper.php + - Classes/Domain/Repository/CategoryRepository.php + +### 📊 Coverage Estimate +- Unit test files: 12 +- Classes without tests: 15 +- Estimated coverage: ~45% (below 70% recommendation) +``` + +### Step 6: Standards Application + +**Reference:** `references/best-practices.md` + +**When evaluating build scripts** (see `references/runtests-validation.md`): +1. Verify Build/Scripts/runTests.sh exists and matches Tea extension reference +2. Confirm PHP_VERSION default matches composer.json minimum requirement +3. Validate TYPO3_VERSION default matches composer.json target version +4. Check PHP version regex includes only supported versions (8.1-8.4) +5. Ensure database version lists are current (no EOL versions) +6. Verify network name is customized (not "friendsoftypo3-tea") +7. Validate test suite paths match actual directory structure + +**When evaluating development environment** (see `references/development-environment.md`): +1. Locate DDEV configuration (.ddev/config.yaml) or Docker Compose alternative +2. When DDEV present, verify type set to 'typo3' +3. Confirm DDEV PHP version matches composer.json minimum +4. Validate DDEV docroot matches composer.json web-dir +5. Check database is MariaDB 10.11+ or MySQL 8.0+ +6. Flag missing DevContainer configuration as optional improvement + +**When evaluating directory structure** (see `references/directory-structure.md`): +1. Verify Build/ directory exists with committed configuration +2. Confirm .Build/ is fully gitignored (entire directory) +3. Flag any .Build/ files committed to git as critical violation +4. Check cache files are in .Build/, not Build/ +5. Validate Composer paths reference .Build/ (bin-dir, vendor-dir, web-dir) +6. Verify quality tool configs reference .Build/ for cache + +**When evaluating project infrastructure**: +1. Check .editorconfig presence for consistent code formatting +2. Verify .gitignore properly configured with standard exclusions +3. Locate CI/CD pipeline (.github/workflows/ or .gitlab-ci.yml) +4. Confirm code quality tools configured (php-cs-fixer, phpstan) +5. Validate README.md provides clear setup instructions +6. Ensure LICENSE file present with appropriate open-source license +7. Check GitHub issue templates (.github/ISSUE_TEMPLATE/config.yml) +8. Verify TER publishing workflow (.github/workflows/publish-to-ter.yml) + +**Security Practices:** +```bash +# Check for security issues +grep -r "->exec(" Classes/ # SQL injection risk +grep -r "htmlspecialchars" Resources/Private/Templates/ # XSS prevention +grep -r "GeneralUtility::validEmail" Classes/ # Email validation +``` + +**Documentation Quality:** + +**DELEGATION STRATEGY: For Deep Documentation Analysis** + +When Documentation Excellence validation is needed, use skill delegation: + +``` +📚 Use /skill typo3-docs (if available) for deep analysis: + - RST syntax validation and TYPO3 directive compliance + - Documentation structure conformance (Index.rst, Settings.cfg) + - TYPO3 documentation standards (guides.xml, screenshots.json) + - Rendering validation with Docker (official TYPO3 render-guides) + - Intersphinx references validation + - Code example syntax validation + - Cross-reference integrity + - Modern documentation tooling detection + + Return: Comprehensive documentation conformance report +``` + +**Fallback: If typo3-docs skill unavailable, perform basic validation:** + +```bash +# Check documentation completeness +ls -1 Documentation/ | wc -l +cat Documentation/Index.rst | head -50 + +# Check for required files +ls Documentation/Settings.cfg Documentation/guides.xml 2>/dev/null + +# Count RST files for excellence scoring +find Documentation/ -name "*.rst" | wc -l +``` + +**Note:** Basic validation only checks file existence. For production-ready documentation conformance, delegate to typo3-docs skill for comprehensive RST validation and rendering checks + +**Output Format:** +```markdown +## Best Practices Conformance + +### ✅ Project Infrastructure +- .editorconfig present +- .gitignore configured properly +- README.md with installation instructions +- GitHub Actions CI/CD pipeline configured + +### ❌ Missing Components +- No phpstan.neon configuration +- No .php-cs-fixer configuration +- LICENSE file missing +- Documentation/ incomplete (missing Developer/ section) + +### 🔒 Security Review +- ✅ Query parameters properly escaped +- ⚠ī¸ 3 instances of direct SQL queries (check for injection risks) +- ✅ Email validation using GeneralUtility::validEmail +- ❌ Missing CSRF tokens in 2 forms +``` + +## Comprehensive Report Generation + +### Final Conformance Report Template + +```markdown +# TYPO3 Extension Conformance Report + +**Extension:** {extension_name} (v{version}) +**Evaluation Date:** {date} +**TYPO3 Compatibility:** {typo3_versions} + +--- + +## Executive Summary + +**Base Conformance Score:** {score}/100 +**Excellence Indicators:** {excellence_score}/20 (Bonus) +**Total Score:** {total_score}/120 + +### Base Conformance Breakdown (0-100 points) +- Extension Architecture: {score}/20 +- Coding Guidelines: {score}/20 +- PHP Architecture: {score}/20 +- Testing Standards: {score}/20 +- Best Practices: {score}/20 + +### Excellence Indicators (0-20 bonus points) +- Community & Internationalization: {score}/6 +- Advanced Quality Tooling: {score}/7 +- Documentation Excellence: {score}/4 +- Extension Configuration: {score}/3 + +**Priority Issues:** {count_critical} +**Recommendations:** {count_recommendations} + +--- + +## 1. Extension Architecture ({score}/20) + +### ✅ Strengths +- {list strengths} + +### ❌ Critical Issues +- {list critical issues with file:line references} + +### ⚠ī¸ Warnings +- {list warnings} + +### 💡 Recommendations +1. {specific actionable recommendations} + +--- + +## 2. Coding Guidelines ({score}/20) + +{repeat same structure} + +--- + +## 3. PHP Architecture ({score}/20) + +{repeat same structure} + +--- + +## 4. Testing Standards ({score}/20) + +{repeat same structure} + +--- + +## 5. Best Practices ({score}/20) + +{repeat same structure} + +--- + +## Priority Action Items + +### High Priority (Fix Immediately) +1. {critical issues that break functionality or security} + +### Medium Priority (Fix Soon) +1. {important conformance issues} + +### Low Priority (Improve When Possible) +1. {minor style and optimization issues} + +--- + +## Detailed Issue List + +| Category | Severity | File | Line | Issue | Recommendation | +|----------|----------|------|------|-------|----------------| +| Architecture | Critical | ext_tables.php | - | Using deprecated ext_tables.php | Migrate to Configuration/Backend/Modules.php | +| Coding | High | Classes/Controller/ProductController.php | 12 | Missing declare(strict_types=1) | Add at top of file | +| Architecture | High | Classes/Service/EmailService.php | 45 | Using GeneralUtility::makeInstance() | Switch to constructor injection | +| Testing | Medium | Tests/ | - | No functional tests | Create Tests/Functional/ with fixtures | + +--- + +## Migration Guide + +### Migrating from ext_tables.php to Configuration/Backend/ + +```php +// Before (ext_tables.php) - DEPRECATED +ExtensionUtility::registerModule(...); + +// After (Configuration/Backend/Modules.php) - MODERN +return [ + 'web_myext' => [ + 'parent' => 'web', + ... + ], +]; +``` + +### Converting to Constructor Injection + +```php +// Before - DEPRECATED +use TYPO3\CMS\Core\Utility\GeneralUtility; +$repository = GeneralUtility::makeInstance(ProductRepository::class); + +// After - MODERN +public function __construct( + private readonly ProductRepository $repository +) {} +``` + +--- + +## Pre-Evaluation Validation Procedures + +Execute these validation steps systematically during conformance evaluation: + +**File Structure Validation** +1. Verify composer.json exists with PSR-4 autoloading configuration +2. Confirm Classes/ directory follows namespace hierarchy +3. Check Configuration/ uses modern structure (no ext_tables.php dependencies) +4. Validate Resources/ separates Private/ and Public/ correctly +5. Ensure Tests/ mirrors Classes/ structure exactly +6. Confirm Documentation/ contains Index.rst and Settings.cfg + +**Coding Standards Validation** +1. Scan all PHP files for declare(strict_types=1) at file start +2. Verify type declarations on all properties, parameters, and return types +3. Check PHPDoc blocks on all public methods and classes +4. Run PSR-12 compliance validation via PHPCS +5. Validate naming conventions (classes, methods, variables) + +**PHP Architecture Validation** +1. Verify constructor injection used throughout codebase +2. Check Configuration/Services.yaml exists and configures services +3. Confirm PSR-14 events replace deprecated hooks +4. Search for GeneralUtility::makeInstance() usage (flag as violation) +5. Search for $GLOBALS access (flag as violation) + +**Testing Validation** +1. Verify unit tests exist and execute successfully +2. Check functional tests include proper fixtures +3. Calculate test coverage (target >70%) +4. Confirm PHPUnit configuration files present (UnitTests.xml, FunctionalTests.xml) +5. Check acceptance tests if web interface present + +**Standards Application Validation** +1. Verify development environment configured (DDEV or Docker Compose) +2. Check Build/Scripts/runTests.sh exists with accurate configuration +3. Validate directory structure (.Build/ vs Build/) separation +4. Confirm code quality tools configured (phpstan, php-cs-fixer) +5. Verify CI/CD pipeline setup (.github/workflows/ or .gitlab-ci.yml) +6. Review security practices implementation +7. Validate documentation completeness +8. Confirm README.md and LICENSE files present + +--- + +## Reference Material Usage + +**When checking extension architecture patterns**, read `references/extension-architecture.md` for: +- Standard directory structures and naming conventions +- Required files and their purposes +- PSR-4 autoloading configuration examples + +**When validating coding guidelines**, read `references/coding-guidelines.md` for: +- PSR-12 compliance requirements +- TYPO3-specific code style rules +- Type declaration standards + +**When evaluating backend modules**, read `references/backend-module-v13.md` for: +- Extension key consistency validation +- JavaScript modernization (ES6 modules, no inline scripts) +- TYPO3 Modal and Notification API patterns +- DocHeader integration (ButtonBar, IconFactory) +- Module.html layout requirements +- ARIA accessibility standards +- Icon registration (Configuration/Icons.php) +- CSRF protection via uriBuilder +- 10-phase modernization checklist +- Real-world case study (45/100 → 95/100 compliance) + +**When evaluating PHP architecture**, read `references/php-architecture.md` for: +- Dependency injection patterns +- Service configuration examples +- PSR-14 event system usage + +**When analyzing testing standards**, read `references/testing-standards.md` for: +- PHPUnit configuration patterns +- Test structure requirements +- Coverage calculation methods + +**When applying best practices**, read `references/best-practices.md` for: +- Development environment setup patterns +- Build script validation criteria +- Directory structure standards + +**For build script validation**, read `references/runtests-validation.md` for: +- Line-by-line runTests.sh validation +- Tea extension reference comparison +- Common configuration errors + +**For development environment checks**, read `references/development-environment.md` for: +- DDEV configuration standards +- Docker Compose alternatives +- PHP and database version requirements + +**For directory structure evaluation**, read `references/directory-structure.md` for: +- .Build/ vs Build/ separation rules +- Composer path configuration +- Gitignore patterns + +**For excellence indicators**, read `references/excellence-indicators.md` for: +- Crowdin integration validation +- Advanced quality tooling detection +- Documentation excellence criteria + +**For Crowdin integration**, read `references/crowdin-integration.md` for: +- TYPO3-compliant crowdin.yml patterns +- Translation workflow validation +- Common misconfigurations + +**For hooks and events migration**, read `references/hooks-and-events.md` for: +- PSR-14 event patterns +- Deprecated hook identification +- Migration strategies + +**When encountering official documentation**, visit: +- TYPO3 Core API: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ +- 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/ +- Testing Documentation: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Testing/ +- Tea Extension (Best Practice): https://github.com/TYPO3BestPractices/tea +``` + +## Scoring System + +### Overall Score Calculation + +Each category (Architecture, Coding, PHP Architecture, Testing, Best Practices) is scored out of 20 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 + - DDEV configuration present: 4 points + - Configuration matches extension requirements: 2 points + - OR Docker Compose alternative: 3 points +- Build scripts (runTests.sh): 6 points + - Script present and executable: 2 points + - PHP/TYPO3 versions match extension: 3 points + - Database versions current: 1 point +- Directory structure (.Build/ vs Build/): 4 points + - .Build/ properly gitignored: 2 points + - Cache files in correct location: 1 point + - Composer paths aligned: 1 point +- Quality tools configured: 2 points +- Documentation complete: 2 points + +**Note:** Previously this category scored only quality tools (6) and documentation (4). The new comprehensive approach validates development environment setup, build script accuracy, and directory structure standards, providing more thorough conformance assessment. + +### Excellence Indicators (Bonus 0-20 points) + +**Reference:** `references/excellence-indicators.md` + +Excellence indicators are **optional features** that demonstrate exceptional quality and community engagement. Extensions are NOT penalized for missing these features - they provide bonus points only. + +**Total Possible Score: 122 points** (100 base conformance + 22 excellence bonus) + +**Category 1: Community & Internationalization (0-6 points)** +- Crowdin integration: 0-2 points + - Basic (crowdin.yml exists): +1 point + - TYPO3-compliant (preserve_hierarchy, wildcards, proper patterns, no download job): +2 points + - See `references/crowdin-integration.md` for comprehensive validation +- GitHub issue templates (.github/ISSUE_TEMPLATE/): +1 point +- .gitattributes with export-ignore: +1 point +- Professional README badges (stability, versions, downloads, CI): +2 points + +**Category 2: Advanced Quality Tooling (0-9 points)** +- Fractor configuration (Build/fractor/fractor.php): +2 points +- TYPO3 CodingStandards package (typo3/coding-standards in composer.json): +2 points +- StyleCI integration (.styleci.yml): +1 point +- Makefile with self-documenting help: +1 point +- CI testing matrix (multiple PHP/TYPO3 versions): +1 point +- TER publishing workflow (.github/workflows/publish-to-ter.yml): +2 points + +**Category 3: Documentation Excellence (0-4 points)** +- 50-99 RST files in Documentation/: +1 point +- 100-149 RST files: +2 points +- 150+ RST files: +3 points +- Modern documentation tooling (guides.xml, screenshots.json): +1 point + +**Category 4: Extension Configuration (0-3 points)** +- ext_conf_template.txt with proper categorization: +1 point +- Composer documentation scripts (doc-init, doc-make, doc-watch): +1 point +- Multiple Configuration/Sets/ presets (for different use cases): +1 point + +**Excellence Score Interpretation:** +- **0-5 points:** Standard extension (meets requirements) +- **6-11 points:** Good practices (actively maintained) +- **12-16 points:** Excellent quality (community reference level) +- **17-22 points:** Outstanding (georgringer/news level) + +**Example Report Format:** + +```markdown +## TYPO3 Extension Conformance Report + +**Extension:** my_extension (v2.0.0) + +--- + +### Score Summary + +**Base Conformance:** 94/100 +- Extension Architecture: 18/20 +- Coding Guidelines: 20/20 +- PHP Architecture: 18/20 +- Testing Standards: 18/20 +- Best Practices: 20/20 + +**Excellence Indicators:** 14/22 (Bonus) +- Community & Internationalization: 5/6 + - ✅ Crowdin integration (+2) + - ✅ Professional README badges (+2) + - ✅ GitHub issue templates (+1) + - ❌ No .gitattributes export-ignore + +- Advanced Quality Tooling: 7/9 + - ✅ Fractor configuration (+2) + - ✅ TYPO3 CodingStandards (+2) + - ✅ Makefile with help (+1) + - ✅ TER publishing workflow (+2) + - ❌ No StyleCI + - ❌ No CI testing matrix + +- Documentation Excellence: 2/4 + - ✅ 75 RST files (+1) + - ✅ Modern tooling (guides.xml) (+1) + +- Extension Configuration: 1/3 + - ✅ Composer doc scripts (+1) + - ❌ No ext_conf_template.txt + - ❌ Only one Configuration/Sets/ preset + +**Total Score:** 108/122 + +**Rating:** Excellent - This extension demonstrates strong conformance and excellent quality practices. +``` + +**Important Notes:** +- Base conformance (0-100) is MANDATORY - this is pass/fail criteria +- Excellence indicators (0-22) are OPTIONAL - bonus points for exceptional quality +- Extensions scoring 100/100 base are fully conformant, regardless of excellence score +- Excellence indicators identify community reference extensions + +**📚 When Documentation/ is Missing or Incomplete:** + +If conformance check reveals missing or incomplete documentation (0-1 points in Documentation Excellence): + +**Recommended Next Step:** +``` +📚 Use typo3-docs skill to create comprehensive documentation: + - Creates complete Documentation/ structure (8 sections) + - Follows modern TYPO3 13.x standards + - Uses card-grid navigation (not plain toctree) + - Applies confval directives for configuration + - Includes Settings.cfg and proper RST structure + - Ready for docs.typo3.org deployment + + After creation: Re-run conformance check to verify improvement +``` + +**Documentation is the most common conformance gap** - extensions often score 90-95/100 with 0/4 documentation. Creating proper documentation typically improves score to 94-99/100 base + 1-2/20 excellence. + +### Severity Levels + +**Critical (Blocker):** +- Security vulnerabilities +- Broken functionality +- Major architecture violations + +**High (Must Fix):** +- Deprecated pattern usage +- Missing required files +- Significant PSR-12 violations + +**Medium (Should Fix):** +- Missing tests +- Incomplete documentation +- Minor architecture issues + +**Low (Nice to Have):** +- Code style inconsistencies +- Optional quality improvements + +## Usage Examples + +### Example 1: Quick Conformance Check + +``` +User: "Check if my TYPO3 extension follows current standards" \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7c5644c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,153 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:netresearch/claude-code-marketplace:skills/typo3-conformance", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "3f5580e1d75ee6d29e7f326445114c5d6c011214", + "treeHash": "443d62115c408288889d0a201c17893d3b60bf29f93f13dc941298582d5a04d9", + "generatedAt": "2025-11-28T10:27:19.840459Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "typo3-conformance", + "description": "Evaluate TYPO3 extensions for conformance to official TYPO3 coding standards, architecture patterns, and best practices. Includes automated validation scripts for file structure, PSR-12 compliance, dependency injection, testing infrastructure, and comprehensive conformance scoring with priority-based action items.", + "version": "1.0.0-20251126" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "41d31179104fe126afc42e19e036ba0afa228ad37d4417f973aea624a941f74b" + }, + { + "path": ".gitignore", + "sha256": "d2dbcbb13e12a322c8987474608144d4852424e8db305fa8eacf5cddfc8d50da" + }, + { + "path": "SKILL.md", + "sha256": "68b223fd999a61f844e53158d7c0d2acaf3f2bb4188326ec9daf29c45ddad417" + }, + { + "path": "references/v13-deprecations.md", + "sha256": "a6374eaf550050c52292a7d6187d044a7990222ec107f0f076948e4c4498d224" + }, + { + "path": "references/backend-module-v13.md", + "sha256": "45c2a675563204470367611ab401768e52efd82539190e5d2037b09e71e1d16f" + }, + { + "path": "references/ext-files-validation.md", + "sha256": "14856d9c803ca69d8c9628c86297e88b19b48dc12d409d7aae8a59b5956c6fd6" + }, + { + "path": "references/best-practices.md", + "sha256": "305184bfe93aaa6ccada0fb278734a40c192301dfea7dad20163195021f5c1c6" + }, + { + "path": "references/directory-structure.md", + "sha256": "cae94c8f7b5895b2b7ac8c756caa13eb2849858e1e95b2d2d1d4044b255364e5" + }, + { + "path": "references/crowdin-integration.md", + "sha256": "92625735ff042ad0e99e0ec40732a430b2777653a53f15f381f5f725a54633ed" + }, + { + "path": "references/excellence-indicators.md", + "sha256": "9cffb3cb62597c0b3b00624ed580de4d90aec51a50ec513a5e9823981c6b5f32" + }, + { + "path": "references/testing-standards.md", + "sha256": "54ae9cfe6e1e682898f31a7756ca99e79a5d3f982c51646cc5b9dc030332ed1a" + }, + { + "path": "references/composer-validation.md", + "sha256": "6542761396e7bc706925a84745e043e46d310d10d9e2a3ebfb754cd69e369c3e" + }, + { + "path": "references/extension-architecture.md", + "sha256": "4023d9dc4294c464ab48b703d452568c5b42ad3c86665e97bbe0e1ef4851c00c" + }, + { + "path": "references/ext-emconf-validation.md", + "sha256": "991b455b6eb042828c143aa9c08b725106979d7590d7b9b0adf9af5305013824" + }, + { + "path": "references/coding-guidelines.md", + "sha256": "30388716f84210020d177abfcdf6a28b4b78b35e5b609d7d82c7eaa222348302" + }, + { + "path": "references/runtests-validation.md", + "sha256": "e6cb139eb19592c42d8b1c87950632245e67fb34476110d63d7d70358900858b" + }, + { + "path": "references/version-requirements.md", + "sha256": "daa17739122f2e1621f01fefc8b1389729b355aafba4258f182c65e127931589" + }, + { + "path": "references/hooks-and-events.md", + "sha256": "84b4b535d3ac6f8a7908a576cda9f1a05b3658804fcd3130ebd5f33f7d20b59e" + }, + { + "path": "references/php-architecture.md", + "sha256": "a39281ae23be135cff2791780cc4b8e8d6b2584d64776e66f901649c440644fe" + }, + { + "path": "references/development-environment.md", + "sha256": "6036bfb46a66e58fdb8f22f99461fa50a92582e1e788c960742dee1c1b60456d" + }, + { + "path": "scripts/check-file-structure.sh", + "sha256": "0da9d33a9d83adda445785fbe04a12345da4df802e700702867a8ac16d06102d" + }, + { + "path": "scripts/generate-report.sh", + "sha256": "5792c0770a616fa9b23073005626a46e81d85c14c05c46c77aeca2c7b84bd832" + }, + { + "path": "scripts/check-architecture.sh", + "sha256": "8e1fb2c2621c701ddd054dbb102fb43aa41c2541b45a14b4f18555c270b1d7a6" + }, + { + "path": "scripts/check-conformance.sh", + "sha256": "dcc37ae3a2d5eb50197e020d93be9e331348df82ae50fac3817400ca7b7cebb9" + }, + { + "path": "scripts/check-phpstan-baseline.sh", + "sha256": "e297e01caee0ecb47715e2c4631ba03b62e1fb9e24567c58d6c23f3539841735" + }, + { + "path": "scripts/check-testing.sh", + "sha256": "70c8aaaa31b0d708424991c8a5e66786ff472bda356efedf8a75a579e7592e97" + }, + { + "path": "scripts/check-coding-standards.sh", + "sha256": "22d162f56484650d1a801f7e418103408dfb643086c36d1684f289f4d5a81dd4" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "bd83b72b91c54a3b6aa258d2fe809b0a875a4883037167b2c1998367cdc0686f" + }, + { + "path": ".github/workflows/publish-to-ter.yml", + "sha256": "62eee6d30da96da6b44d376939f46e823b019cd7e79fff19361eccff90795c4d" + }, + { + "path": ".github/ISSUE_TEMPLATE/config.yml", + "sha256": "8c74d3fce410f9dfcf021dee69ed6a840a64477ba3108baf276ad0d34a264ac7" + } + ], + "dirSha256": "443d62115c408288889d0a201c17893d3b60bf29f93f13dc941298582d5a04d9" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/backend-module-v13.md b/references/backend-module-v13.md new file mode 100644 index 0000000..9a7f7d6 --- /dev/null +++ b/references/backend-module-v13.md @@ -0,0 +1,1059 @@ +# TYPO3 v13 Backend Module Modernization + +**Purpose:** Comprehensive guide for modernizing TYPO3 backend modules to v13 LTS standards +**Source:** Real-world modernization of nr_temporal_cache backend module (45/100 → 95/100 compliance) +**Target:** TYPO3 v13.4 LTS with PSR-12, modern JavaScript, and accessibility compliance + +--- + +## Critical Compliance Issues + +### 1. Extension Key Consistency + +**Problem:** Mixed extension keys throughout templates and JavaScript breaks translations and routing + +**Common Violations:** +- Template translation keys using `EXT:wrong_name/` instead of `EXT:correct_name/` +- JavaScript alert messages with hardcoded wrong extension names +- Variable substitution using wrong extension prefix + +**Detection:** +```bash +# Find all extension key references +grep -rn "EXT:temporal_cache/" Resources/Private/Templates/ +grep -rn "EXT:temporal_cache/" Resources/Public/JavaScript/ + +# Verify correct key in ext_emconf.php +grep "\$EM_CONF\[" ext_emconf.php +``` + +**Example Violations:** +```html + + + + + +``` + +```javascript +// WRONG: Hardcoded wrong extension name in alert +alert('Error in Temporal Cache extension'); + +// CORRECT: Use TYPO3 Notification API with correct name +Notification.error('Error', 'Failed in nr_temporal_cache'); +``` + +**Impact:** Broken translations, 404 errors on static assets, module registration failures + +**Severity:** 🔴 Critical - Breaks basic functionality + +**Fix Priority:** Immediate - Fix before any other modernization work + +--- + +### 2. JavaScript Modernization (ES6 Modules) + +**Problem:** Inline JavaScript in templates is deprecated, not CSP-compliant, and hard to maintain + +**TYPO3 v13 Standard:** All JavaScript must be ES6 modules loaded via PageRenderer + +**Before (DEPRECATED):** +```html + + + + + + + + +``` + +**After (MODERN v13):** + +**Step 1: Create ES6 Module** (`Resources/Public/JavaScript/BackendModule.js`) +```javascript +/** + * Backend module JavaScript for nr_temporal_cache + * TYPO3 v13 ES6 module + */ +import Modal from '@typo3/backend/modal.js'; +import Notification from '@typo3/backend/notification.js'; + +class TemporalCacheModule { + constructor() { + this.initializeEventListeners(); + } + + initializeEventListeners() { + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', () => this.init()); + } else { + this.init(); + } + } + + init() { + this.initializeHarmonization(); + this.initializeKeyboardNavigation(); + } + + initializeHarmonization() { + const selectAllCheckbox = document.getElementById('select-all'); + const contentCheckboxes = document.querySelectorAll('.content-checkbox'); + const harmonizeBtn = document.getElementById('harmonize-selected-btn'); + + if (!harmonizeBtn) return; + + if (selectAllCheckbox) { + selectAllCheckbox.addEventListener('change', (e) => { + contentCheckboxes.forEach(checkbox => { + checkbox.checked = e.target.checked; + }); + this.updateHarmonizeButton(); + }); + } + + contentCheckboxes.forEach(checkbox => { + checkbox.addEventListener('change', () => this.updateHarmonizeButton()); + }); + + harmonizeBtn.addEventListener('click', () => this.performHarmonization()); + } + + async performHarmonization() { + const selectedUids = Array.from(document.querySelectorAll('.content-checkbox:checked')) + .map(cb => parseInt(cb.dataset.uid)); + + if (selectedUids.length === 0) return; + + const harmonizeBtn = document.getElementById('harmonize-selected-btn'); + const harmonizeUri = harmonizeBtn.dataset.actionUri; + + // Use TYPO3 Modal instead of confirm() + Modal.confirm( + 'Confirm Harmonization', + `Harmonize ${selectedUids.length} content elements?`, + Modal.SeverityEnum.warning, + [ + { + text: 'Cancel', + active: true, + btnClass: 'btn-default', + trigger: () => Modal.dismiss() + }, + { + text: 'Harmonize', + btnClass: 'btn-warning', + trigger: () => { + Modal.dismiss(); + this.executeHarmonization(harmonizeUri, selectedUids); + } + } + ] + ); + } + + async executeHarmonization(uri, selectedUids) { + try { + const response = await fetch(uri, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ content: selectedUids, dryRun: false }) + }); + + const data = await response.json(); + + if (data.success) { + // Use TYPO3 Notification API instead of alert() + Notification.success('Harmonization Successful', data.message); + setTimeout(() => window.location.reload(), 1500); + } else { + Notification.error('Harmonization Failed', data.message); + } + } catch (error) { + Notification.error('Error', 'Failed to harmonize content: ' + error.message); + } + } + + initializeKeyboardNavigation() { + document.addEventListener('keydown', (e) => { + // Ctrl/Cmd + A: Select all + if ((e.ctrlKey || e.metaKey) && e.key === 'a') { + const selectAll = document.getElementById('select-all'); + if (selectAll && document.activeElement.tagName !== 'INPUT') { + e.preventDefault(); + selectAll.checked = true; + selectAll.dispatchEvent(new Event('change')); + } + } + }); + } +} + +// Initialize and export +export default new TemporalCacheModule(); +``` + +**Step 2: Load Module in Controller** (`Classes/Controller/Backend/TemporalCacheController.php`) +```php +private function setupModuleTemplate(ModuleTemplate $moduleTemplate, string $currentAction): void +{ + $moduleTemplate->setTitle( + $this->getLanguageService()->sL('LLL:EXT:nr_temporal_cache/Resources/Private/Language/locallang_mod.xlf:mlang_tabs_tab') + ); + + // Load JavaScript module + $moduleTemplate->getPageRenderer()->loadJavaScriptModule( + '@netresearch/nr-temporal-cache/backend-module.js' + ); + + // Add DocHeader buttons + $this->addDocHeaderButtons($moduleTemplate, $currentAction); + // ... +} +``` + +**Step 3: Remove Inline JavaScript from Templates** +```html + + + + + + + +``` + +**Validation:** +```bash +# Ensure NO inline JavaScript remains +grep -rn "FooterAssets" Resources/Private/Templates/ +grep -rn " + + + +

Dashboard

+ + +``` + +**After (MODERN v13):** + +**Step 1: Create Module Layout** (`Resources/Private/Layouts/Module.html`) +```html + + + + +
+ + +
+ + +
+ + +
+ + +``` + +**Step 2: Update All Templates** +```html + + + + + + +

+ + + + +``` + +**Validation:** +```bash +# Check all templates use Module layout +grep -n "f:layout name=" Resources/Private/Templates/Backend/**/*.html + +# Verify Module.html exists +ls -l Resources/Private/Layouts/Module.html + +# Ensure no Default.html dependencies +! grep -r "Default.html" Resources/Private/Templates/ +``` + +**Severity:** 🟡 Important - Standard TYPO3 v13 pattern + +--- + +### 4. DocHeader Component Integration + +**Problem:** Backend modules should have standard DocHeader with refresh, shortcut, and action-specific buttons + +**TYPO3 v13 Standard:** Use ButtonBar, IconFactory for DocHeader components + +**Before (MISSING):** +```php +// Classes/Controller/Backend/TemporalCacheController.php +private function setupModuleTemplate(ModuleTemplate $moduleTemplate, string $currentAction): void +{ + $moduleTemplate->setTitle('Temporal Cache'); + // No DocHeader buttons +} +``` + +**After (MODERN v13):** + +**Step 1: Add Required Imports** +```php +use TYPO3\CMS\Backend\Template\Components\ButtonBar; +use TYPO3\CMS\Core\Imaging\Icon; +use TYPO3\CMS\Core\Imaging\IconFactory; +``` + +**Step 2: Inject IconFactory** +```php +public function __construct( + private readonly ModuleTemplateFactory $moduleTemplateFactory, + private readonly ExtensionConfiguration $extensionConfiguration, + // ... other dependencies + private readonly IconFactory $iconFactory // ADD THIS +) {} +``` + +**Step 3: Add DocHeader Buttons Method** +```php +private function addDocHeaderButtons(ModuleTemplate $moduleTemplate, string $currentAction): void +{ + if (!isset($this->uriBuilder)) { + return; // Skip in tests + } + + $buttonBar = $moduleTemplate->getDocHeaderComponent()->getButtonBar(); + + // Refresh button (all actions) + $refreshButton = $buttonBar->makeLinkButton() + ->setHref($this->uriBuilder->reset()->uriFor($currentAction)) + ->setTitle($this->getLanguageService()->sL('LLL:EXT:core/Resources/Private/Language/locallang_core.xlf:labels.reload')) + ->setIcon($this->iconFactory->getIcon('actions-refresh', Icon::SIZE_SMALL)) + ->setShowLabelText(false); + $buttonBar->addButton($refreshButton, ButtonBar::BUTTON_POSITION_RIGHT, 1); + + // Shortcut/bookmark button (all actions) + $shortcutButton = $buttonBar->makeShortcutButton() + ->setRouteIdentifier('tools_TemporalCache') + ->setDisplayName($this->getLanguageService()->sL('LLL:EXT:nr_temporal_cache/Resources/Private/Language/locallang_mod.xlf:mlang_tabs_tab')) + ->setArguments(['action' => $currentAction]); + $buttonBar->addButton($shortcutButton, ButtonBar::BUTTON_POSITION_RIGHT, 2); + + // Action-specific buttons + switch ($currentAction) { + case 'dashboard': + // Quick access to content list + $contentButton = $buttonBar->makeLinkButton() + ->setHref($this->uriBuilder->reset()->uriFor('content')) + ->setTitle($this->getLanguageService()->sL('LLL:EXT:nr_temporal_cache/Resources/Private/Language/locallang_mod.xlf:button.view_content')) + ->setIcon($this->iconFactory->getIcon('actions-document-open', Icon::SIZE_SMALL)) + ->setShowLabelText(true); + $buttonBar->addButton($contentButton, ButtonBar::BUTTON_POSITION_LEFT, 1); + break; + + case 'wizard': + // Help button for wizard + $helpButton = $buttonBar->makeHelpButton() + ->setFieldName('temporal_cache_wizard') + ->setModuleName('_MOD_tools_TemporalCache'); + $buttonBar->addButton($helpButton, ButtonBar::BUTTON_POSITION_RIGHT, 3); + break; + } +} +``` + +**Step 4: Call from setupModuleTemplate** +```php +private function setupModuleTemplate(ModuleTemplate $moduleTemplate, string $currentAction): void +{ + $moduleTemplate->setTitle( + $this->getLanguageService()->sL('LLL:EXT:nr_temporal_cache/Resources/Private/Language/locallang_mod.xlf:mlang_tabs_tab') + ); + + $moduleTemplate->getPageRenderer()->loadJavaScriptModule( + '@netresearch/nr-temporal-cache/backend-module.js' + ); + + // Add DocHeader buttons + $this->addDocHeaderButtons($moduleTemplate, $currentAction); + + // ... menu creation +} +``` + +**Validation:** +```bash +# Check IconFactory injection +grep "IconFactory" Classes/Controller/Backend/*.php + +# Verify addDocHeaderButtons method exists +grep -A 5 "addDocHeaderButtons" Classes/Controller/Backend/*.php + +# Check button types used +grep "makeLinkButton\|makeShortcutButton\|makeHelpButton" Classes/Controller/Backend/*.php +``` + +**Common Button Types:** +- `makeLinkButton()` - Navigate to URL +- `makeShortcutButton()` - Bookmark module state +- `makeHelpButton()` - Context-sensitive help +- `makeInputButton()` - Form submission +- `makeFullyRenderedButton()` - Custom HTML + +**Severity:** 🟡 Important - Standard TYPO3 UX pattern + +--- + +### 5. TYPO3 Modal and Notification APIs + +**Problem:** Browser `alert()`, `confirm()`, `prompt()` are deprecated and not user-friendly + +**TYPO3 v13 Standard:** Use `@typo3/backend/modal.js` and `@typo3/backend/notification.js` + +**Before (DEPRECATED):** +```javascript +// Inline JavaScript using browser APIs +if (confirm('Really delete this item?')) { + fetch('/delete', { method: 'POST' }) + .then(() => alert('Deleted successfully')) + .catch(() => alert('Error occurred')); +} +``` + +**After (MODERN v13):** +```javascript +import Modal from '@typo3/backend/modal.js'; +import Notification from '@typo3/backend/notification.js'; + +// Confirmation Modal +Modal.confirm( + 'Delete Item', + 'Really delete this item? This action cannot be undone.', + Modal.SeverityEnum.warning, + [ + { + text: 'Cancel', + active: true, + btnClass: 'btn-default', + trigger: () => Modal.dismiss() + }, + { + text: 'Delete', + btnClass: 'btn-danger', + trigger: () => { + Modal.dismiss(); + performDelete(); + } + } + ] +); + +async function performDelete() { + try { + const response = await fetch('/delete', { method: 'POST' }); + const data = await response.json(); + + if (data.success) { + Notification.success('Success', 'Item deleted successfully'); + } else { + Notification.error('Error', data.message); + } + } catch (error) { + Notification.error('Error', 'Failed to delete: ' + error.message); + } +} +``` + +**Modal Severity Levels:** +- `Modal.SeverityEnum.notice` - Info/notice (blue) +- `Modal.SeverityEnum.info` - Information (blue) +- `Modal.SeverityEnum.ok` - Success (green) +- `Modal.SeverityEnum.warning` - Warning (yellow) +- `Modal.SeverityEnum.error` - Error (red) + +**Notification Types:** +- `Notification.success(title, message, duration)` - Green success message +- `Notification.error(title, message, duration)` - Red error message +- `Notification.warning(title, message, duration)` - Yellow warning +- `Notification.info(title, message, duration)` - Blue information +- `Notification.notice(title, message, duration)` - Gray notice + +**Validation:** +```bash +# Check for browser APIs (violations) +grep -rn "alert(" Resources/Public/JavaScript/ +grep -rn "confirm(" Resources/Public/JavaScript/ +grep -rn "prompt(" Resources/Public/JavaScript/ + +# Verify TYPO3 APIs used +grep "import.*Modal" Resources/Public/JavaScript/*.js +grep "import.*Notification" Resources/Public/JavaScript/*.js +``` + +**Severity:** 🟡 Important - Modern UX and consistency + +--- + +### 6. Accessibility (ARIA Labels and Roles) + +**Problem:** Backend modules must be accessible for screen readers and keyboard navigation + +**WCAG 2.1 AA Requirements:** +- Semantic HTML roles +- ARIA labels on interactive elements +- Keyboard navigation support + +**Before (MISSING ACCESSIBILITY):** +```html + + + + + + + + + + + + + +
+ + Title
Content item
+``` + +**After (ACCESSIBLE v13):** +```html + + + + + + + + + + + + + +
+ + + +
+ + {item.content.title}
+``` + +**Accessible Button Example:** +```html + +``` + +**Required ARIA Attributes:** +- `role="grid"` - On data tables +- `role="row"` - On table rows +- `role="columnheader"` - On table headers +- `aria-label="..."` - On interactive elements without visible text +- `aria-labelledby="..."` - Reference to label element +- `aria-describedby="..."` - Additional description + +**Keyboard Navigation:** +```javascript +// Support Ctrl+A for select all +document.addEventListener('keydown', (e) => { + if ((e.ctrlKey || e.metaKey) && e.key === 'a') { + const selectAll = document.getElementById('select-all'); + if (selectAll && document.activeElement.tagName !== 'INPUT') { + e.preventDefault(); + selectAll.checked = true; + selectAll.dispatchEvent(new Event('change')); + } + } +}); +``` + +**Validation:** +```bash +# Check for ARIA labels +grep -rn "aria-label" Resources/Private/Templates/ + +# Check for semantic roles +grep -rn 'role="grid\|row\|columnheader"' Resources/Private/Templates/ + +# Verify keyboard navigation support +grep -rn "keydown\|keyup\|keypress" Resources/Public/JavaScript/ +``` + +**Severity:** đŸŸĸ Recommended - WCAG 2.1 AA compliance + +--- + +### 7. Icon Registration (Configuration/Icons.php) + +**Problem:** Icon registration in `ext_localconf.php` using `IconRegistry` is deprecated in TYPO3 v13 + +**TYPO3 v13 Standard:** Use `Configuration/Icons.php` return array + +**Before (DEPRECATED v13):** +```php +// ext_localconf.php - DEPRECATED +$iconRegistry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance( + \TYPO3\CMS\Core\Imaging\IconRegistry::class +); + +$iconRegistry->registerIcon( + 'temporal-cache-module', + \TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider::class, + ['source' => 'EXT:nr_temporal_cache/Resources/Public/Icons/Extension.svg'] +); +``` + +**After (MODERN v13):** +```php + [ + 'provider' => SvgIconProvider::class, + 'source' => 'EXT:nr_temporal_cache/Resources/Public/Icons/Extension.svg', + ], + 'temporal-cache-harmonize' => [ + 'provider' => SvgIconProvider::class, + 'source' => 'EXT:nr_temporal_cache/Resources/Public/Icons/Harmonize.svg', + ], +]; +``` + +**Validation:** +```bash +# Check for deprecated IconRegistry usage +grep -rn "IconRegistry" ext_localconf.php ext_tables.php + +# Verify Configuration/Icons.php exists +ls -l Configuration/Icons.php + +# Check icon registration format +grep -A 3 "return \[" Configuration/Icons.php +``` + +**Severity:** 🟡 Important - Removes deprecation warnings + +--- + +### 8. CSRF Protection (URI Generation) + +**Problem:** Hardcoded action URLs bypass TYPO3 CSRF protection + +**TYPO3 v13 Standard:** Use `uriBuilder` for all action URIs + +**Before (INSECURE):** +```html + +``` + +```javascript +const uri = button.dataset.actionUri; +fetch(uri, { method: 'POST', body: JSON.stringify(data) }); +``` + +**After (SECURE v13):** + +**Controller:** +```php +public function contentAction(?ServerRequestInterface $request = null, ...): ResponseInterface +{ + // ... + + $moduleTemplate->assignMultiple([ + 'content' => $paginator->getPaginatedItems(), + 'harmonizeActionUri' => isset($this->uriBuilder) + ? $this->uriBuilder->reset()->uriFor('harmonize') + : '', + // ... + ]); + + return $moduleTemplate->renderResponse('Backend/TemporalCache/Content'); +} +``` + +**Template:** +```html + +``` + +**JavaScript:** +```javascript +const harmonizeBtn = document.getElementById('harmonize-selected-btn'); +const harmonizeUri = harmonizeBtn.dataset.actionUri; + +// URI includes CSRF token automatically +const response = await fetch(harmonizeUri, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ content: selectedUids }) +}); +``` + +**Validation:** +```bash +# Check for hardcoded URLs (violations) +grep -rn '"/typo3/' Resources/Private/Templates/ +grep -rn '"/typo3/' Resources/Public/JavaScript/ + +# Verify uriBuilder usage in controller +grep "uriFor(" Classes/Controller/Backend/*.php + +# Check template receives URIs +grep "Uri}" Resources/Private/Templates/Backend/**/*.html +``` + +**Severity:** 🔴 Critical - Security vulnerability + +--- + +## Complete Modernization Checklist + +### Phase 1: Extension Key Consistency (Critical) +- [ ] Verify correct extension key in `ext_emconf.php` +- [ ] Search and replace all `EXT:wrong_key/` → `EXT:correct_key/` in templates +- [ ] Update JavaScript alert/console messages with correct extension name +- [ ] Verify translation keys work in backend module +- [ ] Check static asset paths (CSS, images, icons) + +**Validation:** +```bash +grep -rn "EXT:temporal_cache/" Resources/ # Should find ZERO +grep -rn "EXT:nr_temporal_cache/" Resources/ | wc -l # Should find ALL +``` + +### Phase 2: JavaScript Modernization (Important) +- [ ] Create `Resources/Public/JavaScript/BackendModule.js` as ES6 module +- [ ] Import `@typo3/backend/modal.js` and `@typo3/backend/notification.js` +- [ ] Implement class-based structure with proper initialization +- [ ] Replace all `alert()` with `Notification` API +- [ ] Replace all `confirm()` with `Modal.confirm()` +- [ ] Add keyboard navigation support (Ctrl+A, etc.) +- [ ] Remove ALL `` from templates +- [ ] Remove ALL inline `