Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require --dev brandembassy/coding-standard
   

   Add to your project’s composer.json under require-dev if not auto-detected.

2. Integrate with PHP-CS-Fixer Create/update php-cs-fixer.dist.php:

   <?php
   return (new PhpCsFixer\Config())
       ->setRules(include __DIR__.'/vendor/brandembassy/coding-standard/ruleset.php')
       ->setFinder(
           PhpCsFixer\Finder::create()
               ->in(__DIR__)
               ->exclude('vendor')
       );
   

3. First Use Case: Local Fixes Run in your project root:

   vendor/bin/php-cs-fixer fix
   

   Verify changes with:

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

4. CI Integration Add to .github/workflows/lint.yml (example):

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

Implementation Patterns

Workflows

1. Team Onboarding

   • Share the package via composer.json (or private repo).
   • Document the rule exceptions (if any) in CONTRIBUTING.md.

2. Laravel-Specific Tweaks

   • Extend the ruleset for Laravel conventions (e.g., use App\ imports):

     // php-cs-fixer.dist.php
     ->setRules(array_merge(
         include __DIR__.'/vendor/brandembassy/coding-standard/ruleset.php',
         ['ordered_imports' => ['sort_algorithm' => 'alpha']]
     ))
     

3. Static Analysis (PHPStan/Psalm)

   • Pair with brandembassy/coding-standard’s phpstan.neon (if provided):

     vendor/bin/phpstan analyse --level=max src/
     

4. Pre-Commit Hooks Use php-cs-fixer via husky or pre-commit:

   # .pre-commit-config.yaml
   - repo: local
     hooks:
       - id: php-cs-fixer
         name: PHP-CS-Fixer
         entry: vendor/bin/php-cs-fixer fix
         language: system
         types: [php]
   

Integration Tips

• Custom Rulesets: Override specific rules in php-cs-fixer.dist.php:

  ->setRules([
      '@brandembassy' => true,
      'array_syntax' => ['syntax' => 'short'],
  ])
  

• Parallel CI Jobs: Split linting by directory for faster feedback:

  jobs:
    lint-frontend:
      run: vendor/bin/php-cs-fixer fix app/Http/Controllers/
    lint-backend:
      run: vendor/bin/php-cs-fixer fix app/Models/
  

• VSCode Integration: Add to .vscode/settings.json:

  {
    "php-cs-fixer.executablePath": "vendor/bin/php-cs-fixer",
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "bmewburn.vscode-intelephense"
  }
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Symptom: php-cs-fixer fails with Rule "X" is not defined.
   • Fix: Ensure @brandembassy is loaded first in your ruleset. Example:

     ->setRules([
         '@brandembassy' => true,
         'no_unused_imports' => true, // Override specific rules
     ])
     

2. PHP 8.4 Compatibility

   • Symptom: Errors related to Rector proposals or PHP 8.4 features in your codebase.
   • Fix: Update your php-cs-fixer and rector dependencies to ensure compatibility:

     composer require --dev php-cs-fixer:^3.15 rector/rector:^0.16
     

   • Ensure your project’s PHP version is set to 8.4 in php-cs-fixer.dist.php:

     ->setRiskyAllowed(true) // If needed for PHP 8.4 features
     

3. Performance in Large Projects

   • Symptom: CI hangs on php-cs-fixer fix.
   • Fix: Cache results or parallelize:

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

   • Alternative: Use --dry-run in CI for speed, then run full fix in a separate job.

4. Ignoring Files

   • Symptom: Accidentally fixing vendor/ or node_modules/.
   • Fix: Explicitly exclude paths in the Finder:

     ->setFinder(
         PhpCsFixer\Finder::create()
             ->in(__DIR__)
             ->exclude(['vendor', 'node_modules', 'storage'])
     )
     

5. Rule Version Drift

   • Symptom: New brandembassy/coding-standard releases break existing code.
   • Fix: Pin the version in composer.json or test upgrades in a branch:

     composer require brandembassy/coding-standard:^14.8
     

Debugging

• Dry-Run with Verbosity:

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

  Outputs diffs and skipped files.

• Rule-Specific Debugging:

  vendor/bin/php-cs-fixer fix --rules=@brandembassy --dry-run
  

• PHP 8.4 Debugging:

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

Extension Points

1. Custom Rules Extend the ruleset by creating a local ruleset.php:

   // custom-ruleset.php
   return [
       '@brandembassy' => true,
       'no_superfluous_phpdoc_tags' => ['remove_inheritdoc' => false],
   ];
   

   Then reference it in php-cs-fixer.dist.php:

   ->setRules(include __DIR__.'/custom-ruleset.php')
   

2. CI-Specific Configs Use environment variables to toggle strictness:

   // php-cs-fixer.dist.php
   $rules = include __DIR__.'/vendor/brandembassy/coding-standard/ruleset.php';
   if (getenv('CI')) {
       $rules['risky_nullable_type_declaration'] = true;
   }
   return (new PhpCsFixer\Config())->setRules($rules);
   

3. Visual Studio Code Snippets Combine with php-cs-fixer to enforce snippets:

   // .vscode/settings.json
   {
     "editor.formatOnSave": true,
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true,
       "source.fixAll.php-cs-fixer": true
     }
   }
   

Pro Tips

• Laravel Artisan Command: Create a custom command for quick fixes:

  // app/Console/Commands/FixCode.php
  namespace App\Console\Commands;
  use Illuminate\Console\Command;
  class FixCode extends Command {
      protected $signature = 'code:fix';
      public function handle() {
          $this->call('php-cs-fixer', ['--dry-run' => null]);
      }
  }
  

  Register in app/Console/Kernel.php:

  protected $commands = [
      Commands\FixCode::class,
  ];
  

• GitHub Actions Caching:

  - name: Cache PHP-CS-Fixer
    uses: actions/cache@v3
    with:
      path: ~/.cache/php-cs-fixer
      key: ${{ runner.os }}-php-cs-fixer-${{ hashFiles('**/composer.lock') }}
  

• PHP 8.4 Migration Check: Use the updated brandembassy/coding-standard to validate PHP 8.4 compatibility:

  vendor/bin/php-cs-fixer fix --rules=@brandembassy --allow-risky=yes