Php Cs Fixer Custom Fixers Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced PHPDoc Support: The new PhpdocNoIncorrectVarAnnotationFixer addresses asymmetric-visibility property annotations in PHPDoc, a critical pain point in Laravel projects where visibility modifiers (e.g., protected/private properties with var) often violate PSR-12 standards. This aligns with Laravel’s emphasis on strict typing (e.g., PHP 8.1+ properties) and clean documentation.
• Complementary to Laravel’s Ecosystem:
  • Fixes false positives in tools like PHPStan or Psalm when analyzing Laravel’s Facade/Service Container code.
  • Reduces manual PHPDoc corrections in legacy Laravel codebases (e.g., pre-PHP 8.0 projects).
• Low-Cognitive Overhead: Fixes are automated but require minimal developer intervention, unlike manual PHPDoc updates.

Integration Feasibility

• Zero Breaking Changes: The new fixer is opt-in and does not alter existing behavior. Projects can enable it incrementally via PHP CS Fixer config.
• PHPDoc-Specific Scope: Unlike previous fixers (e.g., NoUnusedUsesFixer), this targets documentation consistency, reducing risk of unintended refactoring.
• Composer Compatibility: No version constraints beyond PHP CS Fixer ≥v3.0, ensuring seamless adoption.

Technical Risk

• False Positives in Legacy Code:
  • Laravel’s dynamic properties (e.g., $app->make()) or magic methods (e.g., __get()) may trigger unnecessary fixes.
  • Mitigation: Use --dry-run and exclude paths (e.g., vendor/, tests/) in config:

    'kubawerlos_phpdoc_no_incorrect_var_annotation' => [
        'exclude' => ['tests/Feature/', 'vendor/'],
    ]
    

• PHPDoc Parser Limitations:
  • Complex PHPDoc (e.g., @mixin, @template) may not be handled perfectly.
  • Workaround: Manually suppress fixes for edge cases using @phpstan-ignore-next-line.
• Performance:
  • PHPDoc parsing adds minimal overhead (~5–10% slower than baseline CS Fixer runs). Benchmark with:

    php-cs-fixer fix --profile --diff
    

Key Questions for TPM

1. Adoption Strategy:
   • Should this fixer be enabled by default in the team’s CS Fixer config, or opt-in per PR?
   • How to handle legacy Laravel code (e.g., pre-PHP 8.0) where PHPDoc annotations are inconsistent?
2. CI/CD Enforcement:
   • Should this fail builds (like NoUnusedUsesFixer) or log warnings?
   • Example GitHub Actions rule:

     - run: php-cs-fixer fix --rules=kubawerlos_phpdoc_no_incorrect_var_annotation --allow-risky=yes --diff
     

3. Backward Compatibility:
   • Will this fixer break existing PHPDoc in custom packages (e.g., laravel/breeze)?
   • Test against a subset of the codebase before full rollout.
4. Maintenance:
   • Who will update PHPDoc standards if the fixer evolves (e.g., supporting @var in PHP 8.2)?

Integration Approach

Stack Fit

• PHPDoc Toolchain Synergy:
  • PHPStan/Psalm: Reduces false positives in static analysis by aligning PHPDoc with actual code.
  • Editor Plugins: Works with PHPStorm’s "Reformat Code" (PHP CS Fixer) or VSCode’s php-cs-fixer extension.
  • Laravel-Specific: Fixes issues in Service Providers, Facades, and Event Listeners where PHPDoc often lags behind code changes.
• Complementary Tools:
  • Pair with phpstan/extension-installer to auto-fix PHPDoc issues in CI.
  • Use alongside rector/rector for broader PHP 8.x migrations.

Migration Path

1. Assessment Phase:
   • Run the fixer in dry mode to identify affected files:

     php-cs-fixer fix --dry-run --diff --rules=kubawerlos_phpdoc_no_incorrect_var_annotation
     

   • Audit PHPDoc-heavy files (e.g., app/Providers/AppServiceProvider.php).
2. Incremental Rollout:
   • Phase 1: Enable fixer in development environments only (via local .php-cs-fixer.dist.php).
   • Phase 2: Add to CI checks (e.g., GitHub Actions) with warnings.
   • Phase 3: Enforce in PR checks (fail builds on violations).
3. Configuration Example:

   return PhpCsFixer\Config::create()
       ->setRules([
           'kubawerlos_phpdoc_no_incorrect_var_annotation' => true,
           // Exclude legacy tests
           'exclude' => ['tests/Unit/OldTests/'],
       ]);
   

Compatibility

• PHP Version: Supports PHP 8.0+ (Laravel’s minimum for PHP 8.x features).
• CS Fixer Version: Works with PHP CS Fixer ≥v3.0 (no breaking changes).
• Framework Agnostic: Safe for non-Laravel PHP projects using PHPDoc.

Sequencing

1. Pre-requisite: Ensure PHP CS Fixer is installed and configured.
2. Testing:
   • Validate against Laravel’s core files (e.g., framework/src/Illuminate/Foundation/) for edge cases.
   • Test with custom packages (e.g., laravel/sanctum) to catch PHPDoc inconsistencies.
3. Documentation:
   • Update team docs with:
     • Common PHPDoc patterns fixed (e.g., /** @var protected string */ → /** @property string $property */).
     • How to exclude files or suppress fixes (e.g., @phpstan-ignore-next-line).
4. Monitoring:
   • Track false positives in CI logs and adjust config accordingly.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor for PHPDoc parser improvements in future releases (e.g., support for @mixin).
  • Pin the package version if stability is critical:

    "kubawerlos/php-cs-fixer-custom-fixers": "^3.37.2"
    

• Configuration Drift:
  • Centralize PHPDoc rules in a shared config package (e.g., laravel-config) to avoid forked setups.
  • Use --allow-risky=yes cautiously (this fixer is marked "risky" due to PHPDoc complexity).

Support

• Onboarding:
  • Add a FAQ section for common issues (e.g., "Why did my Facade PHPDoc break?").
  • Provide before/after examples:

    - /** @var protected string $name */
    + /** @property string $name */
    

• Troubleshooting:
  • Log known edge cases (e.g., fixers failing on Illuminate\Support\Traits\ForwardsCalls).
  • Direct users to the GitHub Issues for support.

Scaling

• Performance:
  • For large codebases, run the fixer per-module (e.g., app/, packages/) to reduce memory usage.
  • Cache results with:

    php-cs-fixer fix --cache-file=.php-cs-fixer.cache
    

• Parallelization:
  • Use --parallel in CI for faster execution:

    php-cs-fixer fix --parallel --rules=kubawerlos_phpdoc_no_incorrect_var_annotation
    

Failure Modes

Ramp-Up

• Training:
  • Host a workshop on PHPDoc best practices in Laravel, focusing on:
    • When to use @property vs. @var.
    • How the fixer aligns with PHP 8.1+ typed properties.
  • Share real-world examples from the code