Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bitbag/coding-standard --dev
   

2. Configure ECS (ecs.php):

   <?php
   declare(strict_types=1);
   use Symplify\EasyCodingStandard\Config\ECSConfig;
   
   return static function (ECSConfig $config): void {
       $config->import('vendor/bitbag/coding-standard/ecs.php');
       $config->paths(['src', 'tests']);
   };
   

3. Configure PHPStan (phpstan.neon):

   includes:
       - vendor/bitbag/coding-standard/phpstan.neon
   

4. Run Checks:

   ./vendor/bin/ecs check src
   ./vendor/bin/phpstan analyse src
   

First Use Case

Run a pre-commit hook to enforce standards before merging:

./vendor/bin/ecs check src --fix
git add .
git commit -m "Enforce coding standards"

Implementation Patterns

Daily Workflow

1. Automate Checks:

   • Add to composer.json:

     "scripts": {
         "cs-check": "ecs check src --fix",
         "cs-fix": "ecs check src --fix --diff",
         "phpstan": "phpstan analyse src"
     }
     

   • Run via:

     composer cs-check
     

2. CI/CD Integration:

   • Fail builds on violations (e.g., GitHub Actions):

     - name: Run ECS
       run: ./vendor/bin/ecs check src --no-cache
     - name: Run PHPStan
       run: ./vendor/bin/phpstan analyse src --level=8
     

3. Customize Rules:

   • Extend ECS config:

     $services = $config->services();
     $services->set(\Your\Custom\Fixer::class);
     

   • Override PHPStan levels per path:

     parameters:
         level: max
         paths:
             - { path: src, level: 8 }
             - { path: tests, level: 5 }
     

4. Team Onboarding:

   • Document the standard in CONTRIBUTING.md:

     ## Coding Standards
     - Run `composer cs-fix` before PRs.
     - PHPStan level 8 for `src/`, level 5 for `tests/`.
     

Gotchas and Tips

Common Pitfalls

1. ECS Fixes Fail Silently:

   • Use --debug to diagnose:

     ./vendor/bin/ecs check src --fix --debug
     

   • Example error: Undefined constant "T_TYPE_CLOSE_PARENTHESIS" → Update ECS/Symfony versions.

2. PHPStan False Positives:

   • Suppress rules in code:

     // @phpstan-ignore-next-line
     $result = $this->someUnsafeMethod();
     

   • Or exclude files in phpstan.neon:

     excludeFiles:
         - 'tests/Integration/UnstableTest.php'
     

3. BitBag Header Injection:

   • Disable via env:

     putenv('ALLOW_BITBAG_OS_HEADER=0')
     

   • Or exclude files in ecs.php:

     $config->paths(['src', 'tests'])->exclude(['vendor/', 'config/']);
     

Pro Tips

1. Incremental Fixing:

   • Use --diff to see only changed files:

     ./vendor/bin/ecs check src --fix --diff
     

2. PHPStan Parallel Analysis:

   • Speed up tests with:

     ./vendor/bin/phpstan analyse tests --parallel
     

3. Custom Rule Validation:

   • Test new rules locally:

     $config->ruleWithConfiguration(
         \SlevomatCodingStandard\Sniffs\TypeHints\TypeHintSniff::class,
         ['type_hint_types' => ['array', 'iterable']]
     );
     

4. IDE Integration:

   • Configure PHPStan in PHPStorm:
     • Settings > PHP > Quality Tools > PHPStan
     • Set Configuration File to phpstan.neon.

5. Performance:

   • Cache results for faster runs:

     ./vendor/bin/ecs check src --cache
     

6. Legacy Code:

   • Gradually enforce standards:

     $config->paths(['src'])->skip(['legacy/']);
     

```markdown
### Debugging Checklist
1. **ECS Issues**:
   - [ ] Run with `--debug` flag.
   - [ ] Check Symfony/ECS version compatibility.
   - [ ] Verify `paths()` include/exclude logic.

2. **PHPStan Issues**:
   - [ ] Test with `--level=max` to isolate errors.
   - [ ] Check for `@phpstan-ignore` misuse.
   - [ ] Validate `phpstan.neon` includes/excludes.

3. **Environment**:
   - [ ] Ensure `ALLOW_BITBAG_OS_HEADER` is set correctly.
   - [ ] Confirm PHP version matches package requirements (^8.1).