Coding Standard Laravel Package

Getting Started

Minimal Setup

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

   composer require --dev broadway/coding-standard
   

   Ensure php-cs-fixer is installed globally or as a dev dependency:

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

2. First Use Case Run the coding standard against your project:

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

   • --rules=@Broadway applies the Broadway-specific ruleset.
   • --dry-run previews changes without modifying files.

3. Where to Look First

   • Ruleset Definition: Check vendor/broadway/coding-standard/Broadway.php for custom rules.
   • Configuration: Override defaults in .php-cs-fixer.dist.php (if needed).
   • CI Integration: Add to .github/workflows/php.yml or similar for automated checks.

Implementation Patterns

Workflows

1. Pre-Commit Hooks Use php-cs-fixer with a tool like php-cs-fixer + husky (Git) or pre-commit (Python) to auto-fix files before commits:

   # .pre-commit-config.yaml
   repos:
     - repo: https://github.com/php-cs-fixer/php-cs-fixer
       rev: v3.12.0
       hooks:
         - id: php-cs-fixer
           args: [--rules=@Broadway]
   

2. CI/CD Pipeline Fail builds if coding standards aren’t met:

   # .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 --rules=@Broadway --diff --allow-risky=yes
   

3. Laravel-Specific Integration

   • Artisan Command: Create a custom command to run checks:

     // app/Console/Commands/FixCodingStandard.php
     public function handle() {
         $this->call('php-cs-fixer:fix', [
             '--rules' => '@Broadway',
             '--path-mode' => 'intersection',
         ]);
     }
     

   • Service Provider: Register the command in AppServiceProvider@boot():

     if ($this->app->runningInConsole()) {
         $this->commands([FixCodingStandard::class]);
     }
     

4. Team Onboarding

   • Document the ruleset in CONTRIBUTING.md or README.md.
   • Provide a template .php-cs-fixer.dist.php for new projects:

     return (new PhpCsFixer\Config())
         ->setRules([
             '@Broadway' => true,
             'array_syntax' => ['syntax' => 'short'],
         ]);
     

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Broadway’s rules may conflict with other packages (e.g., laravel-shift/php-rector). Test combinations early:

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

   • Fix: Explicitly override conflicting rules in .php-cs-fixer.dist.php.

2. Performance

   • Large codebases may slow down php-cs-fixer. Use --path-mode=intersection to target specific directories:

     vendor/bin/php-cs-fixer fix --rules=@Broadway --path-mode=intersection --path="app/"
     

3. IDE Integration

   • Some IDEs (e.g., PHPStorm) may not auto-detect the Broadway ruleset. Manually configure:
     • PHPStorm: Add @Broadway to Settings > Languages & Frameworks > PHP > Code Sniffer > Custom.
     • VSCode: Use the PHP Intelephense extension with a custom config.

4. Deprecated Rules

   • Broadway’s last release (2022) may include outdated rules (e.g., lowercase_cast). Audit rules annually:

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

Debugging

1. Dry-Run Mismatches If changes appear in --dry-run but not in actual runs, check:

   • File permissions (chmod -R 755 storage/).
   • .gitignore exclusions (e.g., vendor/).

2. Custom Rule Failures For undefined rules, verify the ruleset is loaded:

   vendor/bin/php-cs-fixer fix --rules=@Broadway --show-config
   

   • Fix: Ensure the ruleset file exists in vendor/broadway/coding-standard/.

3. CI False Positives

   • Whitelist generated files (e.g., bootstrap/cache/) in .php-cs-fixer.dist.php:

     ->setFinder(
         PhpCsFixer\Finder::create()
             ->exclude('bootstrap/cache/')
     )
     

Extension Points

1. Custom Rules Extend the ruleset by creating a new config file (e.g., broadway-laravel.php):

   return (new PhpCsFixer\Config())
       ->setRules([
           '@Broadway' => true,
           'no_unused_imports' => true, // Add Laravel-specific rules
           'ordered_imports' => ['sort_algorithm' => 'alpha'],
       ]);
   

   Then reference it:

   vendor/bin/php-cs-fixer fix --rules=./broadway-laravel.php
   

2. Rector Integration Combine with rector for refactoring:

   vendor/bin/rector process --dry-run --config=rector.php
   vendor/bin/php-cs-fixer fix --rules=@Broadway
   

   Example rector.php:

   return static function (Rector\Config\RectorConfig $rectorConfig): void {
       $rectorConfig->paths([__DIR__ . '/src']);
       $rectorConfig->rules([
           new Rector\Php74\Rector\Class_\PrecedenceNewStaticPropertyRector(),
       ]);
   };
   

3. Parallel Processing Speed up runs with parallel:

   vendor/bin/parallel-lint .  # Lint first
   vendor/bin/php-cs-fixer fix --rules=@Broadway --parallel