Php Cs Fixer Phpdoc Force Fqcn Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the package to your project via Composer:

   composer require --dev adamwojs/php-cs-fixer-phpdoc-force-fqcn
   

2. Register the Rule: Add the rule to your .php-cs-fixer.dist.php config:

   <?php
   return PhpCsFixer\Config::create()
       ->registerCustomRule(
           Adamwojs\PhpCsFixer\Rules\ForceFqcnInDocBlock::class
       )
       ->setRules([
           '@PHP-CS-Fixer:risky' => true,
           'adamwojs_force_fqcn_in_docblock' => true,
       ]);
   

3. First Use Case: Run the fixer on a file with partial FQCNs in docblocks (e.g., @param array $data instead of @param \ArrayObject $data):

   ./vendor/bin/php-cs-fixer fix src/Your/Class.php
   

   The rule will auto-correct docblocks to use fully qualified class names (e.g., \ArrayObject).

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Add the rule to your CI checks (e.g., GitHub Actions, GitLab CI) to enforce consistency:

     - name: Run PHP-CS-Fixer
       run: ./vendor/bin/php-cs-fixer fix --dry-run --diff --rules=adamwojs_force_fqcn_in_docblock
     

   • Use --dry-run to preview changes before applying.

2. Pre-Commit Hook: Use tools like PHP-CS-Fixer’s pre-commit hook to auto-fix docblocks before commits:

   composer require --dev php-cs-fixer/php-cs-fixer
   vendor/bin/php-cs-fixer fix --allow-risky=yes
   

3. Team Onboarding:

   • Document the rule in your team’s coding standards (e.g., README or wiki).
   • Example: "All docblocks must use FQCNs for types (e.g., \Laravel\Foo\Bar instead of Bar)."

4. Partial Application:

   • Exclude specific files/directories if needed (e.g., legacy code):

     ->setRules([
         'adamwojs_force_fqcn_in_docblock' => true,
     ])
     ->setFinder(
         PhpCsFixer\Finder::create()
             ->exclude('legacy')
     ),
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • The rule scans docblocks for type hints, which can slow down large codebases. Test in CI first.
   • Mitigation: Run in parallel if using PHP-CS-Fixer’s --parallel flag.

2. False Positives:

   • The rule may misinterpret generic placeholders (e.g., @param mixed $data). Review changes manually for edge cases.
   • Example: @template TKey of array-key should not be modified.

3. Namespace Conflicts:

   • If two classes share the same short name (e.g., User in \App\User and \Vendor\User), the rule may pick the wrong FQCN.
   • Solution: Manually specify the correct FQCN in docblocks or use IDE hints (e.g., PHPStorm’s "Optimize Imports").

4. Dynamic Classes:

   • Avoid using the rule on docblocks referencing dynamically generated classes (e.g., @param string $className where $className is a variable).

Debugging

• Dry Run: Use --dry-run --diff to see changes before applying:

  ./vendor/bin/php-cs-fixer fix --dry-run --diff
  

• Verbose Mode: Enable debug output for troubleshooting:

  ./vendor/bin/php-cs-fixer fix -v
  

Configuration Quirks

1. Custom FQCN Mapping: Override default FQCN resolution by extending the rule:

   use Adamwojs\PhpCsFixer\Rules\ForceFqcnInDocBlock;
   
   class CustomForceFqcnRule extends ForceFqcnInDocBlock {
       protected function getFqcn(string $shortClassName): ?string {
           // Custom logic (e.g., alias mapping)
           return match ($shortClassName) {
               'User' => '\\App\\Models\\CustomUser',
               default => parent::getFqcn($shortClassName),
           };
       }
   }
   

   Register it in .php-cs-fixer.dist.php:

   ->registerCustomRule(CustomForceFqcnRule::class)
   

2. Excluding Rules: Disable the rule for specific docblock types (e.g., @var):

   ->setRules([
       'adamwojs_force_fqcn_in_docblock' => [
           'types' => ['param', 'return', 'throws'], // Exclude 'var'
       ],
   ]),
   

Extension Points

1. Laravel-Specific Use Cases:

   • Service Providers: Enforce FQCNs in docblocks for injected bindings (e.g., @param \Illuminate\Contracts\Auth\Factory $auth).
   • Artisan Commands: Standardize docblocks for command signatures:

     /**
      * @param \Illuminate\Console\Command $command
      * @return void
      */
     

2. Testing:

   • Use the rule in PHPUnit tests to validate docblock consistency:

     $this->assertStringContainsString('\Laravel\Foo\Bar', $docblock);
     

   • Pair with roave/security-advisories to ensure FQCNs align with dependency versions.

3. IDE Support:

   • Configure your IDE (e.g., PHPStorm) to auto-format docblocks with FQCNs using the CS Fixer plugin.