Coding Standard Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the package in your Laravel project:

   composer require cline/coding-standard --dev
   

2. Run the fixer on your project files:

   vendor/bin/php-cs-fixer fix --rules=@cline-standard --path-mode=intersection --diff
   

   • --diff shows changes before applying them (dry run).
   • --path-mode=intersection ensures only files matching your project’s structure are processed.

3. Integrate with CI/CD (e.g., GitHub Actions):

   - name: Run Coding Standard
     run: vendor/bin/php-cs-fixer fix --rules=@cline-standard --allow-risky=yes --diff
   

First Use Case: Enforcing PHPDoc Standards

Use the PHPDoc preset to auto-format docblocks with 80-column wrapping:

vendor/bin/php-cs-fixer fix --rules=@cline-phpdoc --path=app/Http/Controllers

Implementation Patterns

Workflows

1. Pre-commit Hooks Use php-cs-fixer via a Git hook to block non-compliant code:

   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   

   Configure .php-cs-fixer.dist.php to extend the package’s presets:

   return (new PhpCsFixer\Config())
       ->setRules([
           '@cline-standard' => true,
           '@cline-phpdoc'  => true,
       ])
       ->setFinder(
           PhpCsFixer\Finder::create()
               ->in(__DIR__.'/app')
               ->exclude('vendor')
       );
   

2. CI/CD Enforcement Add a step to fail builds on violations:

   - name: Check Coding Standards
     run: vendor/bin/php-cs-fixer fix --dry-run --rules=@cline-standard --allow-risky=yes
   

3. Legacy Code Migration Use --dry-run to preview changes before applying:

   vendor/bin/php-cs-fixer fix --dry-run --rules=@cline-standard --path=legacy-module
   

Integration Tips

• Laravel-Specific Files: Exclude Blade templates and .env files:

  ->setFinder(
      PhpCsFixer\Finder::create()
          ->in(__DIR__.'/app')
          ->exclude(['resources/views', '.env'])
  )
  

• Custom Fixers: Extend the package’s rules by creating a custom config:

  ->setRules([
      '@cline-standard' => true,
      'no_unused_imports' => true, // Add Laravel-specific rules
  ])
  

• PHPDoc for Eloquent Models: Enforce consistent docblock formatting:

  vendor/bin/php-cs-fixer fix --rules=@cline-phpdoc --path=app/Models
  

Gotchas and Tips

Pitfalls

1. PHPDoc Wrapping Conflicts

   • The 80-column docblock wrapper may cause merge conflicts in PRs. Mitigate by:
     • Using --diff to preview changes.
     • Configuring IDEs (e.g., PHPStorm) to auto-format docblocks.

2. Legacy Tag Removal

   • The preset removes @author and @version tags by default. To opt back in:

     ->setRules([
         '@cline-standard' => true,
         'header_comment' => ['header' => '...'], // Re-enable if needed
     ])
     

3. Performance Overhead

   • Custom fixers may slow down CI. Optimize with:

     vendor/bin/php-cs-fixer fix --parallel --rules=@cline-standard
     

4. Blade Template Exclusions

   • Blade files (.blade.php) are not processed by default. Explicitly include them if needed:

     ->setFinder(
         PhpCsFixer\Finder::create()
             ->in(__DIR__.'/resources/views')
             ->name('*.blade.php')
     )
     

Debugging

• False Positives: Use --verbose to debug rule application:

  vendor/bin/php-cs-fixer fix --verbose --rules=@cline-standard
  

• Rule Conflicts: Temporarily disable presets to isolate issues:

  vendor/bin/php-cs-fixer fix --rules=@PSR12 --path=app/Services
  

Extension Points

1. Custom Presets Create a custom-preset.php to override defaults:

   return [
       '@cline-standard' => true,
       'no_unused_imports' => true,
       'ordered_imports' => ['sort_algorithm' => 'alpha'],
   ];
   

2. Rector for PHP 8.5 Migrations Use the bundled Rector preset to migrate to pipe operators:

   vendor/bin/rector process src --dry-run --config=vendor/cline/coding-standard/rector.php
   

3. Git Hooks Add a pre-commit hook to auto-fix issues:

   echo '#!/bin/sh' >> .git/hooks/pre-commit
   echo 'vendor/bin/php-cs-fixer fix --rules=@cline-standard --allow-risky=yes' >> .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit