Php Cs Fixer Phpdoc Force Fqcn Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package enforces Fully Qualified Class Names (FQCN) in DocBlocks, aligning with PSR-12 and PSR-5 standards. This is critical for:
  • Autocompletion & IDE Support (e.g., PHPStorm, VSCode).
  • Static Analysis Tools (e.g., Psalm, PHPStan) to resolve type hints accurately.
  • Refactoring Safety by avoiding ambiguous class references.
• Laravel-Specific Use Case:
  • Dependency Injection (DI) Containers: FQCNs improve clarity in service bindings (e.g., Illuminate\Contracts\Auth\Authenticatable vs. ambiguous User).
  • Testing Frameworks: Mocking interfaces/classes requires FQCNs for precise type resolution.
  • API Contracts: OpenAPI/Swagger annotations benefit from FQCNs to avoid runtime ambiguity.

Integration Feasibility

• Low-Coupling Design: The package is a php-cs-fixer rule, meaning it integrates via:
  • Pre-commit Hooks (e.g., GitHub Actions, Laravel Forge).
  • CI/CD Pipelines (e.g., GitHub Actions, GitLab CI) as a linter step.
  • Local Development via php-cs-fixer CLI or IDE plugins (e.g., PHP-CS-Fixer for VSCode).
• No Runtime Overhead: Purely a static analysis tool; no impact on application performance.

Technical Risk

Key Questions

1. Current DocBlock Standards:
   • Are FQCNs already enforced in the codebase? If not, what’s the current tolerance for ambiguity?
   • Are there legacy systems (e.g., dynamic class loading) where FQCNs are impractical?
2. Toolchain Maturity:
   • Is php-cs-fixer already used in the project? If not, what’s the migration path?
   • Are there other linters (e.g., PHPStan, Psalm) that could conflict with this rule?
3. Team Adoption:
   • How will developers handle false positives (e.g., third-party libraries)?
   • Is there buy-in for treating this as a blocking CI check (vs. warning)?
4. Performance Impact:
   • Will running this rule in CI add significant time to the pipeline? (Benchmark with a large PR.)

Integration Approach

Stack Fit

• PHP-CS-Fixer Integration:
  • Recommended Setup:

    # composer.json
    "require-dev": {
        "friendsofphp/php-cs-fixer": "^3.0",
        "adamwojs/php-cs-fixer-phpdoc-force-fqcn": "^1.0"
    }
    

  • Config Example (.php-cs-fixer.dist.php):

    return (new PhpCsFixer\Config())
        ->setRules([
            '@PHP-CS-Fixer:risky' => true,
            'phpdoc_align' => ['align' => 'vertical'],
            'phpdoc_no_empty_return' => true,
            'phpdoc_no_useless_inheritdoc' => true,
            'phpdoc_order' => true,
            'phpdoc_separation' => true,
            'phpdoc_single_line_var_spacing' => true,
            'phpdoc_types_order' => ['null_adjustment' => 'always_last', 'sort_alphabetically' => true],
            'phpdoc_var_without_type' => true,
            // Custom rule (add after v2.18+)
            'adamwojs_phpdoc_force_fqcn' => true,
        ]);
    

• Laravel-Specific Optimizations:
  • Exclude Vendor/Generated Files:

    ->setFinder(
        PhpCsFixer\Finder::create()
            ->in(__DIR__)
            ->exclude('vendor')
            ->exclude('bootstrap/cache')
            ->exclude('storage')
    )
    

  • Focus on Critical Paths:
    • Prioritize app/, config/, routes/, and tests/ directories.
    • Use --dry-run to estimate effort before full enforcement.

Migration Path

1. Phase 1: Audit & Baseline
   • Run php-cs-fixer fix --dry-run --diff to identify affected files.
   • Generate a changelog of required updates (e.g., User → App\Models\User).
2. Phase 2: Incremental Enforcement
   • Start with non-blocking warnings in CI (e.g., GitHub Actions annotation).
   • Example workflow:

     - name: PHP-CS-Fixer (FQCN)
       run: php-cs-fixer fix --rules=adamwojs_phpdoc_force_fqcn --dry-run --diff
     

3. Phase 3: Hard Block
   • After 2–4 weeks, transition to failing CI for violations.
   • Provide a one-time exception list for third-party libraries (documented in README.md).

Compatibility

• PHP Version: Compatible with PHP 7.4+ (Laravel 8+).
• Laravel-Specific Considerations:
  • Facade DocBlocks: May need manual review (e.g., Auth::class vs. Illuminate\Auth\AuthManager).
  • Dynamic Proxies: Generated by Laravel (e.g., Eloquent) may not need FQCNs in DocBlocks.
• Toolchain Conflicts:
  • PHPStan/Psalm: Ensure their autoload_files include the correct namespace mappings.
  • IDE Plugins: Configure PHPStorm/VSCode to recognize the custom rule.

Sequencing

1. Pre-requisite: Ensure php-cs-fixer is already integrated (or plan a parallel migration).
2. Order of Operations:
   • Step 1: Add the package to composer.json and update config.
   • Step 2: Run locally on a feature branch to test fixes.
   • Step 3: Merge into main with CI warnings enabled.
   • Step 4: Gradually enforce as a blocker (e.g., 10% of team first).
3. Rollback Plan:
   • If adoption fails, revert to a whitelist-based config or disable the rule temporarily.

Operational Impact

Maintenance

• Rule Updates:
  • Monitor for updates to the package (last release in 2021; fork if needed).
  • Fork Strategy: If inactive, maintain a private fork with Laravel-specific tweaks (e.g., handling Illuminate\Support\Facades\*).
• Configuration Drift:
  • Document exceptions (e.g., third-party libraries) in .php-cs-fixer.dist.php with comments.
  • Example:

    'adamwojs_phpdoc_force_fqcn' => [
        'ignore_annotations' => ['@mixin', '@template'],
        'ignore_paths' => ['vendor/'],
    ],
    

• Dependency Management:
  • Pin php-cs-fixer version to avoid breaking changes (e.g., ^3.0).

Support

• Developer Onboarding:
  • Add a setup guide to the project’s CONTRIBUTING.md:

    ## DocBlock FQCN Enforcement
    This project enforces FQCNs in DocBlocks for type safety. Run:
    ```bash
    composer require --dev adamwojs/php-cs-fixer-phpdoc-force-fqcn
    php-cs-fixer fix
    

  • Common Issues:
    • "Class not found" errors → Verify use statements or FQCN spelling.
    • IDE not auto-fixing → Configure PHP-CS-Fixer plugin.
• CI Troubleshooting:
  • Cache php-cs-fixer dependencies in CI to reduce flakiness:

    - uses: actions/cache@v3
      with:
        path: vendor/bin/php-cs-fixer
        key: ${{ runner.os }