Coding Standards Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev neuecommerce/coding-standards
   

   Register the package in composer.json under extra:

   "extra": {
       "laravel": {
           "coding-standards": {
               "rules": [
                   "@PSR12",
                   "@PHPUnit",
                   "Neue\\CodingStandards\\Rules\\*"
               ]
           }
       }
   }
   

2. First Use Case Run a one-time check on your project:

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

   Or integrate with PHPStan for static analysis:

   vendor/bin/phpstan analyse --level=max --memory-limit=2G
   

3. Where to Look First

   • Ruleset Definition: Check config/coding-standards.php (if auto-generated) or php-cs-fixer.dist.php for custom rules.
   • Custom Rules: Explore Neue\CodingStandards\Rules\* in the package source for Laravel-specific checks (e.g., Eloquent, Blade, Facades).

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks Use husky or pre-commit to auto-fix issues:

   composer require --dev php-cs-fixer
   vendor/bin/php-cs-fixer fix --rules=@NeueCodingStandards
   

   Example .huskyrc.js:

   const { execSync } = require('child_process');
   execSync('vendor/bin/php-cs-fixer fix --rules=@NeueCodingStandards', { stdio: 'inherit' });
   

2. CI/CD Pipeline Add to GitHub Actions (.github/workflows/coding-standards.yml):

   - name: Run Coding Standards
     run: |
       composer install --prefer-dist
       vendor/bin/php-cs-fixer fix --rules=@NeueCodingStandards --dry-run
       vendor/bin/phpstan analyse --level=max
   

3. IDE Integration

   • PHPStorm: Enable php-cs-fixer via Settings > Tools > PHP > PHP Code Sniffer.
   • VSCode: Use the PHP CS Fixer extension with the @NeueCodingStandards preset.

4. Custom Rule Extension Extend the package’s rules by creating a custom rule class:

   namespace App\Rules;
   
   use Neue\CodingStandards\AbstractRule;
   use PhpCsFixer\Tokenizer\Tokens;
   
   class CustomLaravelRule extends AbstractRule {
       public function applyFix(\PhpCsFixer\Tokenizer\Token $token, \PhpCsFixer\Fixer\FixerDefinitionInterface $fixer): void {
           // Custom logic (e.g., enforce `Str::of()` over `strtolower()`).
       }
   }
   

   Register it in php-cs-fixer.dist.php:

   return [
       'rules' => [
           '@NeueCodingStandards',
           'App\Rules\CustomLaravelRule',
       ],
   ];
   

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Issue: @NeueCodingStandards may override PSR-12 defaults (e.g., strict line breaks).
   • Fix: Explicitly define rules in php-cs-fixer.dist.php to avoid surprises:

     return [
         'rules' => [
             '@PSR12',
             '@NeueCodingStandards',
             'line_ending' => '\n', // Force LF
         ],
     ];
     

2. Performance with Large Projects

   • Issue: PHPStan’s --level=max can be slow for monorepos.
   • Fix: Use --memory-limit=4G and parallelize:

     vendor/bin/parallel-phpstan analyse --level=max --memory-limit=4G
     

3. Blade Template Rules

   • Issue: The package may not cover Blade-specific rules (e.g., @foreach syntax).
   • Fix: Combine with laravel-shift/blade-style-guide:

     composer require --dev laravel-shift/blade-style-guide
     

4. False Positives in Custom Rules

   • Issue: Overly strict custom rules may flag legitimate code.
   • Fix: Use AbstractRule::isTokenAcceptable() to whitelist exceptions:

     public function isTokenAcceptable(Tokens $tokens, $position): bool {
         return $tokens[$position]->getContent() !== 'legacy_method';
     }
     

Debugging Tips

1. Dry Run First Always use --dry-run before committing fixes:

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

2. Rule-Specific Debugging Isolate rule issues by testing individually:

   vendor/bin/php-cs-fixer fix --rules=Neue\CodingStandards\Rules\ClassAlignment
   

3. CI Feedback Fail builds on violations (not just warnings) in .github/workflows:

   - name: Enforce Coding Standards
     run: vendor/bin/php-cs-fixer fix --rules=@NeueCodingStandards --allow-risky=yes || exit 1
   

Extension Points

1. Add Laravel-Specific Rules Contribute to the package by extending Neue\CodingStandards\Rules\LaravelRuleset:

   // Example: Enforce `Route::prefix()` over `Route::group()` for API routes.
   class ApiRoutePrefixRule extends AbstractRule { ... }
   

2. Integrate with PestPHP Use pestphp/pest-plugin-snapshots to test rule outputs:

   use function Pest\Laravel\assert;
   
   it('enforces snake_case for model names')->snapshot();
   

3. Custom Presets Save project-specific presets in config/coding-standards.php:

   return [
       'presets' => [
           'laravel' => [
               '@NeueCodingStandards',
               'no_unused_imports',
               'ordered_imports',
           ],
       ],
   ];