Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev binsoul/coding-standard
   

   Register the package in composer.json under extra.coding-standard (if needed) or integrate via PHP-CS-Fixer config.

2. First Use Case Run a basic check on a single file:

   vendor/bin/php-cs-fixer fix app/Models/User.php
   

   • Verify the package’s default rules align with your team’s standards (e.g., PSR-12).
   • Check if the package extends or overrides PHP-CS-Fixer rules (if applicable).

3. Configuration Locate or create a .php-cs-fixer.dist.php file in your project root. Example:

   <?php
   return (new PhpCsFixer\Config())
       ->setRules([
           '@PSR12' => true,
           // Override specific rules if needed
           'array_syntax' => ['syntax' => 'short'],
       ]);
   

   • The package may provide a preset; check its docs for defaults.

Implementation Patterns

Daily Workflows

1. Pre-Commit Hooks Integrate with Laravel’s Git hooks (e.g., pre-commit) to auto-fix issues:

   composer require --dev laravel-pint
   vendor/bin/pint --test  # Run checks before commit
   

   • Use php-cs-fixer directly or wrap it in a custom script.

2. CI/CD Integration Add a step in GitHub Actions/Laravel Forge to enforce standards:

   - name: Run Coding Standard Checks
     run: vendor/bin/php-cs-fixer fix --dry-run --diff
   

   • Fail builds on violations or auto-fix on merge.

3. Team Onboarding

   • Document the coding standard in CONTRIBUTING.md.
   • Provide a Makefile target for quick fixes:

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

Laravel-Specific Patterns

• Artisan Commands Extend the package to create a custom Artisan command for team-wide fixes:

  // app/Console/Commands/FixCodingStandard.php
  public function handle()
  {
      $fixer = new PhpCsFixer\FixerFactory();
      $finder = new PhpCsFixer\Finder();
      $finder->in(__DIR__.'/../../app');
  
      $fixer->fix($finder->getFiles());
  }
  

  Register the command in app/Console/Kernel.php.

• IDE Integration Configure your IDE (PHPStorm/VSCode) to use the package’s rules for real-time feedback:

  • PHPStorm: Settings > Languages & Frameworks > PHP > Quality Tools > PHP-CS-Fixer.
  • VSCode: Install the "PHP CS Fixer" extension and point to the package’s config.

Gotchas and Tips

Common Pitfalls

1. Rule Conflicts

   • If the package overrides PHP-CS-Fixer defaults, explicitly list rules in .php-cs-fixer.dist.php to avoid surprises.
   • Example: Disable no_unused_imports if the package enforces it too aggressively:

     'no_unused_imports' => false,
     

2. Performance

   • Exclude large files/directories (e.g., vendor/, storage/) to speed up checks:

     $finder->exclude(['vendor', 'storage']);
     

   • Use --parallel for large codebases:

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

3. False Positives

   • Custom rules may flag Laravel-specific patterns (e.g., Route::group nesting). Whitelist them:

     'generic_class_names' => ['generics' => ['Collection']],
     

Debugging Tips

• Dry Run Always test changes with --dry-run first:

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

• Diff Output Compare changes before applying:

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

• Verbose Mode Enable debug logs for complex issues:

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

Extension Points

1. Custom Rules Extend the package by creating a custom rule (if it supports it). Example:

   // app/Rules/CustomRule.php
   use PhpCsFixer\Fixer\FixerInterface;
   class CustomRule implements FixerInterface { ... }
   

   Register it in the config:

   $finder->addCustomRule(new CustomRule());
   

2. Preset Sharing Share your preset with the team via a config/coding-standard.php file:

   return [
       'rules' => [
           '@PSR12' => true,
           'concat_space' => ['spacing' => 'one'],
       ],
   ];
   

   Load it dynamically in .php-cs-fixer.dist.php.

3. Laravel Mix/Webpack If the package supports frontend standards (e.g., ESLint), integrate it into webpack.mix.js:

   mix.postCss('resources/css/app.css', 'public/css', [
       require('postcss-php-cs-fixer')(), // Hypothetical example
   ]);