Coding Standards Laravel Package

Getting Started

1. Install via Composer in your TYPO3 extension or project:

   composer require --dev typo3/coding-standards
   

   Note: This package now requires PHP 8.1+ and PHPUnit 10+ due to updates in v0.8.0.

2. Run a quick check using the bundled ruleset:

   vendor/bin/phpcs --standard=vendor/typo3/coding-standards/ruleset.xml path/to/Classes
   

   New in v0.8.0: The ruleset now includes stricter alignment with TYPO3 Core v12+ standards and updated PHP-CS-Fixer rules.

3. First real use case: Enforce coding standards across a TYPO3 extension by integrating phpcs into your workflow. Leverage the new PHP 8.3 support and Symfony 7 compatibility for modern projects.

Implementation Patterns

• Local pre-commit hook: Integrate phpcs with tools like pre-commit or husky to auto-check staged PHP files. Use the updated .editorconfig (now synced with TYPO3 Core) for IDE consistency.

  # Example husky pre-commit hook
  - run: vendor/bin/phpcs --standard=vendor/typo3/coding-standards/ruleset.xml --report=full Classes/
  

• CI pipeline: Update your CI to use the new PHP-CS-Fixer and PHPUnit 10+ support. Example GitHub Actions job:

  - name: Run coding standards check
    run: |
      vendor/bin/phpcs --standard=vendor/typo3/coding-standards/ruleset.xml \
        --report-full=phpcs-report.txt \
        --error-severity=5 \
        --warning-severity=5 \
        Classes/ Configuration/
  

  Note: Drop Symfony 5 support if present (deprecated in v0.8.0).

• IDE integration: Configure PHP_CodeSniffer in PhpStorm/VS Code to use the updated ruleset. The .editorconfig now includes stricter formatting rules (e.g., PHP 8.3 alignment).

• Extend and customize: Create a custom phpcs.xml.dist extending the new ruleset. Example:

  <?xml version="1.0"?>
  <ruleset name="MyProject">
    <rule ref="vendor/typo3/coding-standards/ruleset.xml"/>
    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint"/>
    <!-- Add new rules after the TYPO3 base ruleset -->
  </ruleset>
  

  New in v0.8.0: The ruleset now includes stricter return type checks and Symfony 7 component support.

• PHP-CS-Fixer integration: Use the bundled phpcbf for auto-fixes, but audit changes manually for TYPO3-specific rules (e.g., ExtensionName). The default config is now reformatted for consistency.

Gotchas and Tips

• PHP version requirement: v0.8.0 drops PHP 8.0 support and requires PHP 8.1+. Update your project or CI environments.

  php -v  # Must be ≥8.1
  

• Symfony version: Remove Symfony 5 support if present. The package now requires Symfony 6/7 (added in PR #119). Update dependencies if needed:

  composer require symfony/*:^6.0|^7.0
  

• PHPCS/PHPCBF version: Ensure compatibility with the new ruleset by updating:

  composer require --dev php-cs-fixer:^3.10
  

• Excluding files: Use <exclude-pattern> in phpcs.xml or CLI flags (--ignore). New in v0.8.0: The ruleset now skips system/settings.php by default (PR #117).

• Custom sniffs precedence: Place custom sniffs after the TYPO3 ruleset in your phpcs.xml to avoid conflicts. Example:

  <rule ref="vendor/typo3/coding-standards/ruleset.xml"/>
  <rule ref="Custom/Sniffs/MySniff"/>
  

• CI optimizations: Cache ~/.composer/cache and vendor/ in GitHub Actions for faster runs. The updated CI workflow (PR #127) includes PHP 8.3 support.

• Autofix safely: Use phpcbf for simple fixes, but manually review TYPO3-specific rules (e.g., ExtensionNamingUtility). The new ruleset includes stricter checks for TYPO3 Core v12+.

• EditorConfig: The .editorconfig is now synced with TYPO3 Core (PR #105/#107). Ensure your IDE respects it for consistent formatting.

• Debugging: If PHPCS fails unexpectedly, check for:

  • PHP version mismatches (must be ≥8.1).
  • Outdated PHPCS/PHPCBF versions.
  • Conflicts with custom sniffs (reorder rules in phpcs.xml).