Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel-aligned: Presets and rules are designed for modern PHP (8.4+) and Laravel ecosystems, reducing friction for teams already using PHP-CS-Fixer, ECS, or Rector.
  • Opinionated but extensible: Predefined presets (Standard, PHPDoc, PHPUnit) enforce consistency without requiring manual rule configuration, while custom fixers allow for architecture-specific adjustments (e.g., naming conventions).
  • PHPDoc and Rector integration: Automates docblock formatting (80-column prose wrapping) and enables PHP 8.5 pipe-operator migrations, critical for Laravel’s evolving syntax support.
  • Legacy cleanup: Default removal of @author/@version tags aligns with Laravel’s shift toward modern documentation practices (e.g., PHPDoc focus).
  • Toolchain synergy: Complements Laravel’s testing stack (PHPUnit, Pest) and static analysis tools (PHPStan, Psalm) by enforcing surface-level consistency.

• Gaps:

  • Laravel-specific file types unsupported: No native handling for Blade templates, .env files, or migration files, requiring manual exclusions or custom rules.
  • PHP 8.4+ dependency: May conflict with legacy Laravel projects (e.g., LTS branches like 8.x) or teams using older PHP versions.
  • Limited Laravel-specific presets: Lacks out-of-the-box rules for Laravel patterns (e.g., Facade naming, Eloquent relationships, Artisan commands).
  • Monorepo challenges: Opinionated presets may not align with divergent standards across repositories, risking configuration drift.

Integration Feasibility

• Low-risk for greenfield projects: Drop-in replacement for php-cs-fixer with minimal configuration, ideal for new Laravel projects or teams adopting modern PHP.
• Moderate-risk for existing codebases: Requires pre-migration analysis to identify conflicts (e.g., legacy docblocks, custom naming conventions).
• CI/CD compatibility: Seamlessly integrates with GitHub Actions, GitLab CI, or Laravel Forge via composer scripts or custom workflows.
• Toolchain conflicts:
  • Potential overlap with Laravel Pint (if adopted), requiring rule synchronization.
  • May introduce false positives in Blade templates or non-PHP files if not properly excluded.

Technical Risk

• Breaking changes:
  • Default removal of @author/@version tags may require migration scripts or team buy-in for legacy codebases.
  • PHPDoc formatting (80-column wrappers) could cause merge conflicts in PRs if not previewed with --dry-run.
• Performance overhead:
  • Custom fixers or complex presets may slow down CI pipelines; parallel execution or selective rule application can mitigate this.
• Maintainer dependency:
  • Single maintainer (faustbrian) introduces single-point-of-failure risk; fork or contribution plan may be needed for critical updates.
• Rule conflicts:
  • Custom Laravel-specific rules (e.g., Facade naming) might clash with team preferences or existing php-cs-fixer configurations.

Key Questions

1. Adoption Strategy:
   • Should this replace all php-cs-fixer instances, or only new projects? How will legacy codebases migrate?
   • Will the team fork the package to add Laravel-specific rules (e.g., Eloquent method naming)?
2. Customization Needs:
   • Are the presets too opinionated? Can they be extended via custom rules or .php-cs-fixer.dist.php overrides?
   • Should Laravel-specific exclusions (e.g., Blade files, .env) be documented in the team’s configuration?
3. CI/CD Impact:
   • How will false positives (e.g., in Blade templates) be handled? Will exclusions be needed?
   • Should the package be opt-in per repository (e.g., via composer.json flags) to avoid monorepo conflicts?
4. Long-Term Maintenance:
   • Is the MIT license acceptable, or should a fork be created for Laravel-specific enhancements?
   • How will breaking changes (e.g., PHP 8.5+ requirements) be communicated and mitigated?

Integration Approach

Stack Fit

• Laravel-native: Fully compatible with Laravel’s composer-based workflows, requiring only composer require and minimal configuration.
• Toolchain compatibility:
  • Replaces or extends php-cs-fixer in phpcs.xml.dist or .php-cs-fixer.dist.php.
  • Coexists with Laravel Pint: Can share rules or be used selectively (e.g., Pint for Blade, cline/coding-standard for PHP).
  • Integrates with IDEs: Works with PHPStorm, VSCode (PHP Intelephense), and Laravel IDE Helper for real-time feedback.
  • Synergizes with static analysis: Complements PHPStan, Psalm, and Pest by enforcing surface-level consistency.
• CI/CD readiness:
  • Plugs into GitHub Actions, GitLab CI, or Laravel Forge via composer scripts or custom workflows.
  • Supports pre-commit hooks (e.g., Husky) for local enforcement.

Migration Path

1. Phase 1: Assessment and Pilot

   • Audit existing php-cs-fixer rules: Compare current configuration with cline/coding-standard presets using diff or git diff.
   • Pilot in a non-critical module: Test presets (Standard, PHPDoc, PHPUnit) and custom fixers in a sandbox environment.
   • Document conflicts: Identify legacy code (e.g., @author tags, custom naming) that may require migration scripts.

2. Phase 2: Configuration Alignment

   • Replace php-cs-fixer in composer.json:

     "require-dev": {
         "cline/coding-standard": "^3.4",
         "php-cs-fixer/diff": "^3.0" // For dry-run comparisons
     }
     

   • Update phpcs.xml.dist or .php-cs-fixer.dist.php:

     <?php
     return (new PhpCsFixer\Config())
         ->setRules([
             '@cline-standard' => true,
             'ordered_imports' => true, // Example custom rule
         ])
         ->setFinder(
             PhpCsFixer\Finder::create()
                 ->in(__DIR__.'/src')
                 ->exclude('vendor')
                 ->notPath(['tests/', 'migrations/']) // Exclude non-PHP files
         );
     

   • Add Laravel-specific exclusions:

     ->exclude(['resources/views/', '.env', 'artisan'])
     

3. Phase 3: CI/CD Integration

   • GitHub Actions Example:

     name: PHP-CS-Fixer
     on: [push, pull_request]
     jobs:
       fix:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: shivammathur/setup-php@v2
             with:
               php-version: '8.4'
           - run: composer install --dev
           - run: vendor/bin/php-cs-fixer fix --dry-run --diff --rules=@cline-standard
     

   • Pre-commit Hook (Optional):

     composer require --dev dealerdirect/phpcodesniffer-composer-installer
     composer require --dev php-cs-fixer
     

     Add to .php-cs-fixer.dist.php:

     ->setUsingCache(false) // For pre-commit hooks
     

4. Phase 4: Gradual Rollout

   • Enforce in CI first: Run as a check-only job before merging.
   • Opt-in per repository: Use composer.json flags or repository labels to control adoption.
   • Monitor false positives: Adjust exclusions or rules based on CI feedback.

Compatibility

• PHP 8.4+ requirement: Ensure all Laravel projects meet this threshold; use runtime checks or CI gates for older versions.
• Laravel-specific files: Exclude Blade templates, .env, and migrations by default; document custom rules for these file types.
• Toolchain conflicts:
  • Laravel Pint: Use Pint for Blade/JS and cline/coding-standard for PHP, or synchronize rules via shared config.
  • Custom fixers: Override or extend presets in .php-cs-fixer.dist.php for team-specific needs.

Sequencing

1. Start with PHPDoc preset: Low-risk, high-impact for documentation consistency.
2. Add Standard preset: Enforce naming conventions and basic rules.
3. Introduce custom fixers: Gradually adopt architecture-specific rules (e.g., Facade naming).
4. Enable Rector preset: For PHP 8.5+ migrations, pilot in a single module first.
5. Phase out legacy rules: Deprecate @author/@version tags via migration scripts.

Operational Impact