Php Styler Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • AST-based transformation: Leverages PHP-Parser’s tokenization to enforce consistent formatting rules, making it ideal for Laravel’s PHP-heavy codebase (e.g., controllers, services, migrations).
  • Configurable formats: Supports vendor-specific styles (e.g., SymfonyFormat, DoctrineFormat), aligning with Laravel’s ecosystem. Custom DeclarationFormat is well-suited for Laravel’s class-heavy architecture.
  • Diff-friendly output: Minimizes noise in PRs, critical for collaborative Laravel projects.
  • Parallel processing: Scales efficiently for large codebases (e.g., Laravel’s app/ directory with ~100+ files).
  • Logic preservation: Guarantees functional equivalence post-formatting, reducing regression risk.

• Weaknesses:

  • Aggressive reformatting: Overwrites all existing formatting (e.g., align-as-you-go, custom spacing), which may conflict with Laravel’s existing style guides (e.g., Laravel’s internal style).
  • No incremental mode: Requires full reformat on config changes (unlike PHP-CS-Fixer’s --rules).
  • Limited comment handling: Preserves block comments but may disrupt docblock alignment (e.g., PHPDoc @param tags in Laravel’s annotations).

Integration Feasibility

• Laravel Stack Compatibility:

  • PHP 8.1+: Aligns with Laravel’s minimum PHP version (8.1+).
  • Composer Dev Dependency: Non-intrusive (installed via composer require --dev).
  • CI/CD Integration: Supports GitHub Actions, GitLab CI, or Laravel Forge via check/apply commands.
  • Toolchain Synergy:
    • PHP-CS-Fixer: Can coexist but may require config alignment (e.g., brace positioning).
    • Pint: Direct competitor; adoption would require team consensus.
    • Laravel Mix/Webpack: No direct conflict, but may need .gitignore for generated files (e.g., vendor/).

• Key Dependencies:

  • PHP-Parser: Already used in Laravel’s internal tools (e.g., php artisan make:controller).
  • AutoShell: Lightweight CLI wrapper; no additional setup needed.

Technical Risk

• High:

  • Team Adoption: Resistance to "destructive" formatting (e.g., losing manual alignment). Requires buy-in from senior devs.
  • Config Drift: Custom php-styler.php may diverge from Laravel’s evolving style (e.g., new PHPDoc rules).
  • Performance: Parallel processing (--workers) may overload CI/CD for monorepos (e.g., Laravel + Forge).
  • Edge Cases:
    • Heredoc/Nowdoc: Unsplit long strings may violate line-length rules.
    • Dynamic Code: Tools like Laravel’s Blade templates or eval() may break parsing.
    • Legacy Code: Older PHP (pre-8.1) or non-standard syntax (e.g., use function) may fail.

• Mitigation:

  • Preview Mode: Use preview command to review changes before apply.
  • Git Blame: Leverage .git-blame-ignore-revs to avoid false positives.
  • Incremental Rollout: Start with check in CI, then enforce via apply in a feature branch.

Key Questions

1. Style Alignment:
   • Does Laravel’s existing style (e.g., styleci.yml) conflict with PHP-Styler’s defaults? If so, which format (SymfonyFormat, DoctrineFormat, or custom) should we adopt?
2. Toolchain Conflict:
   • Should we replace PHP-CS-Fixer/Pint entirely, or use PHP-Styler for formatting and PHP-CS-Fixer for fixes?
3. CI/CD Strategy:
   • Should apply run in CI (risky) or only locally (enforced via pre-commit hooks)?
4. Exclusion Rules:
   • Which directories/files should be excluded (e.g., vendor/, node_modules/, generated config files)?
5. Performance:
   • How will parallel processing (--workers) impact CI/CD runtime for large repos (e.g., Laravel + Forge)?
6. Maintenance:
   • Who will own the php-styler.php config and update it as Laravel’s style evolves?

Integration Approach

Stack Fit

• Laravel Ecosystem:

  • Core: Ideal for app/, config/, database/, and routes/ files.
  • Packages: Compatible with Laravel’s package boilerplate (e.g., src/, tests/).
  • Artisan Commands: Can wrap php-styler in a custom Artisan command (e.g., php artisan style:apply).
  • Forge/Envoyer: Supports deployment hooks for automated formatting.

• Toolchain Placement:

  • Dev Dependency: Installed via composer require --dev pmjones/php-styler.
  • Script Alias: Add to composer.json scripts:

    "scripts": {
      "style:check": "php vendor/bin/php-styler check",
      "style:apply": "php vendor/bin/php-styler apply",
      "style:preview": "php vendor/bin/php-styler preview"
    }
    

  • Pre-commit Hook: Integrate with Laravel’s existing hooks (e.g., via husky or pre-commit).

Migration Path

1. Assessment Phase:

   • Run composer require --dev pmjones/php-styler in a test environment.
   • Generate a baseline config:

     ./vendor/bin/php-styler init
     

   • Compare output with preview against a sample file (e.g., app/Http/Controllers/Controller.php).

2. Pilot Phase:

   • Apply to a non-critical directory (e.g., app/Console/Commands/).
   • Validate functionality (e.g., php artisan migrate, php artisan tinker).
   • Review diffs for false positives (e.g., misaligned PHPDoc tags).

3. Full Rollout:

   • Update php-styler.php to match Laravel’s style (e.g., DeclarationFormat with lineLen: 120).
   • Add to CI/CD (e.g., GitHub Actions):

     - name: Check PHP Style
       run: composer style:check
     

   • Enforce via pre-commit hook or branch protection rules.

4. Post-Rollout:

   • Monitor CI/CD failures for edge cases.
   • Update config as Laravel’s style evolves (e.g., new PHPDoc rules).

Compatibility

• Laravel-Specific Considerations:

  • Blade Templates: Exclude .blade.php files (use a custom Files implementation or .php-styler.php exclusions).
  • Environment Files: Exclude .env (use Files::exclude()).
  • Generated Code: Exclude bootstrap/cache/ and storage/framework/views/ (add to .gitignore).
  • PHPDoc Alignment: Use @php-styler-expansive for complex docblocks (e.g., @param array<int, string> $data).

• Format Selection:

  • Option 1: Custom DeclarationFormat (recommended for Laravel’s class-heavy code).
  • Option 2: SymfonyFormat (closer to Laravel’s style but may need overrides).
  • Option 3: DoctrineFormat (strict but opinionated).

Sequencing

1. Initial Setup:

   • Install and configure in a feature branch.
   • Test with preview on critical files (e.g., app/Http/Kernel.php).

2. Incremental Adoption:

   • Start with check in CI (fail builds if files are unstyled).
   • Gradually enforce apply in PR templates or branch rules.

3. Long-Term:

   • Automate config updates (e.g., via a Laravel package).
   • Deprecate older formatters (e.g., PHP-CS-Fixer for formatting-only tasks).

Operational Impact

Maintenance

• Config Management:

  • Owner: Assign a TPM or senior dev to maintain php-styler.php.
  • Versioning: Pin to a specific minor version (e.g., 0.x@dev) to avoid breaking changes.
  • Updates: Test new releases in a staging environment before upgrading.

• Dependency Updates:

  • Monitor PHP-Styler’s changelog for breaking changes (e.g., removed Styler::fromConfig() in 0.22.0).
  • Update alongside Laravel’s PHP version (e.g., drop PHP 8.