Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev zing/coding-standard
   

   Add to composer.json under require-dev:

   "zing/coding-standard": "^7.0"
   

2. First Use Case: Run the coding standard checks via:

   vendor/bin/ecs check src tests
   

   Fix issues automatically with:

   vendor/bin/ecs fix src tests
   

3. Key Files:

   • vendor/zing/coding-standard/ecs.php (default ruleset)
   • .php-cs-fixer.dist.php (if customizing PHP-CS-Fixer)
   • rector.php (if using Rector)

Implementation Patterns

Daily Workflow

1. Pre-Commit Hooks: Integrate with pre-commit (e.g., via husky or pre-commit framework):

   # .pre-commit-config.yaml
   - repo: local
     hooks:
       - id: ecs
         name: ECS Check
         entry: vendor/bin/ecs check
         language: system
         pass_filenames: false
   

2. CI/CD Integration: Add to GitHub Actions (.github/workflows/ecs.yml):

   jobs:
     ecs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/ecs check src tests
   

3. Custom Rulesets: Extend the default ruleset in ecs.php:

   <?php
   return static function (\PhpCsFixer\Config $phpCsFixer): void {
       $phpCsFixer
           ->importRuleset(__DIR__.'/vendor/zing/coding-standard/ecs.php')
           ->setRules([
               '@PSR12' => true,
               'no_unused_imports' => true,
               'ordered_imports' => ['sort_algorithm' => 'alpha'],
           ]);
   };
   

4. Rector Integration: Run Rector alongside ECS for refactoring:

   vendor/bin/rector process src --dry-run --config vendor/zing/coding-standard/rector.php
   

5. Team Onboarding: Document the ruleset in CONTRIBUTING.md:

   ## Coding Standards
   Run `composer cs-check` to validate your changes.
   

Gotchas and Tips

Pitfalls

1. Performance:

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

     $phpCsFixer->setPath(__DIR__.'/src')
                 ->setIgnore(['**/vendor/**', '**/node_modules/**']);
     

   • Use --parallel for large codebases:

     vendor/bin/ecs check --parallel=4
     

2. Rule Conflicts:

   • Disable conflicting rules explicitly:

     $phpCsFixer->setRules([
         'no_unused_imports' => false, // Disable if causing issues
     ]);
     

   • Check the PHP-CS-Fixer rules for overlaps.

3. Rector Gotchas:

   • Dry-run first (--dry-run) to avoid unexpected changes.
   • Skip specific rules in rector.php:

     return static function (RectorConfig $config): void {
         $config->ruleWithConfiguration(
             SetList::INSTANCEOF,
             ['strict' => false]
         );
     };
     

4. Configuration Caching:

   • Clear cached rulesets if rules behave unexpectedly:

     composer clear-cache
     

Tips

1. Partial Fixes: Use --diff to see changes before applying:

   vendor/bin/ecs fix --diff
   

2. Custom Sniffs: Extend with custom PHP_CodeSniffer rules:

   $phpCsFixer->registerCustomSniff(
       __DIR__.'/CustomSniffs/ClassLengthSniff.php',
       ['ClassLengthSniff']
   );
   

3. Version Pinning: Lock versions in composer.json to avoid surprises:

   "zing/coding-standard": "7.26.0",
   "friendsofphp/php-cs-fixer": "3.87.2",
   "rector/rector": "^0.19"
   

4. Debugging:

   • Run with --verbose for detailed output:

     vendor/bin/ecs check --verbose
     

   • Use --format=json for machine-readable output in CI:

     vendor/bin/ecs check --format=json > ecs-report.json
     

5. Team Alignment:

   • Add a CODING_STANDARD.md to explain why specific rules exist (e.g., "We enforce strict_types=1 for type safety").
   • Use ecs sniff to validate rules without fixing:

     vendor/bin/ecs sniff src