Symfony2 Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev instaclick/symfony2-coding-standard
   

   Ensure php-cs-fixer is also installed (required dependency):

   composer require --dev friendsofphp/php-cs-fixer
   

2. Configure php-cs-fixer Create/update .php-cs-fixer.dist.php in your project root:

   <?php
   return (new PhpCsFixer\Config())
       ->setRules([
           '@Symfony' => true,
           '@Symfony:risky' => true, // Optional: Enable stricter rules
           'array_syntax' => ['syntax' => 'short'],
           'concat_space' => ['spacing' => 'one'],
       ])
       ->setFinder(
           PhpCsFixer\Finder::create()
               ->in(__DIR__)
               ->exclude('vendor')
               ->exclude('node_modules')
       );
   

3. First Use Case: Run Linter Execute the fixer on your codebase:

   vendor/bin/php-cs-fixer fix
   

   Integrate into your CI pipeline (e.g., GitHub Actions) to enforce consistency.

Implementation Patterns

Workflows

1. Pre-Commit Hook Use php-cs-fixer as a pre-commit hook to catch formatting issues early:

   composer require --dev laravel-pint
   vendor/bin/pint --test  # Dry run
   vendor/bin/pint         # Auto-fix
   

   Add to .git/hooks/pre-commit:

   #!/bin/sh
   vendor/bin/php-cs-fixer fix --dry-run || exit 1
   

2. CI/CD Integration Fail builds on violations:

   # .github/workflows/lint.yml
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/php-cs-fixer fix --dry-run --diff
   

3. Team Onboarding

   • Document the standard in CONTRIBUTING.md.
   • Use php-cs-fixer fix --allow-risky=yes for new contributors to auto-format their PRs.

Laravel-Specific Tips

• Exclude Vendor Files: The Symfony standard may conflict with Laravel’s conventions (e.g., use App vs. use aliases). Override rules in .php-cs-fixer.dist.php:

  ->setRules([
      'no_unused_imports' => false, // Laravel often uses unused `use` for IDE hints
  ])
  

• Artisan Integration: Create a custom command for quick fixes:

  // app/Console/Commands/FixCodingStandard.php
  namespace App\Console\Commands;
  use Illuminate\Console\Command;
  class FixCodingStandard extends Command {
      protected $signature = 'code:fix';
      public function handle() {
          $this->call('vendor:publish', ['--tag' => 'php-cs-fixer']);
          $this->info('Running Symfony coding standard...');
          shell_exec('vendor/bin/php-cs-fixer fix');
      }
  }
  

  Register in app/Console/Kernel.php and run with:

  php artisan code:fix
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Symfony’s @Symfony rules may enforce PSR-12 (e.g., return_type_declaration), which Laravel’s pint (PHP-CS-Fixer wrapper) may override. Solution: Align configurations or disable conflicting rules.
   • Example: Disable no_unused_imports if your team relies on IDE-specific use statements.

2. Performance

   • Large codebases (e.g., 10K+ files) may slow down php-cs-fixer. Solution:
     • Use --parallel flag (PHP-CS-Fixer 3.0+):

       vendor/bin/php-cs-fixer fix --parallel
       

     • Cache results with --cache-file=.php-cs-fixer.cache.

3. False Positives

   • Symfony’s no_superfluous_phpdoc_tags may flag Laravel-specific annotations (e.g., @mixin). Solution: Whitelist files or override the rule:

     ->setRules([
         'no_superfluous_phpdoc_tags' => [
             'remove_inheritdoc' => false,
             'allow_mixed' => true,
         ],
     ])
     

Debugging

• Dry Run: Always test changes first:

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

• Verbose Output: Debug rule application:

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

• Rule Isolation: Test individual rules:

  vendor/bin/php-cs-fixer fix --rules=@Symfony --stop-on-violation
  

Extension Points

1. Custom Rules Extend the Symfony standard by adding project-specific rules:

   ->setRules([
       '@Symfony' => true,
       'custom_rule' => true, // Hypothetical; requires PHP-CS-Fixer custom rule
   ])
   

   See PHP-CS-Fixer Custom Rules.

2. Integration with Laravel Tools

   • Laravel Pint: If using laravel/pint, merge configs:

     composer require laravel/pint --dev
     vendor/bin/pint --config=.php-cs-fixer.dist.php
     

   • PHPStan: Combine with static analysis:

     vendor/bin/phpstan analyse --level=max
     vendor/bin/php-cs-fixer fix
     

3. Visual Studio Code Add to .vscode/settings.json for real-time feedback:

   {
       "php-cs-fixer.executablePath": "vendor/bin/php-cs-fixer",
       "php-cs-fixer.rules": "@Symfony",
       "editor.formatOnSave": true
   }
   

Pro Tips

• Partial Fixes: Target specific files/directories:

  vendor/bin/php-cs-fixer fix app/Http/Controllers/
  

• Version Pinning: Lock PHP-CS-Fixer version in composer.json to avoid rule changes:

  "require-dev": {
      "friendsofphp/php-cs-fixer": "^3.0"
  }
  

• Documentation: Generate a report for team alignment:

  vendor/bin/php-cs-fixer fix --dry-run --format=diff > CODESTYLE_REPORT.md