Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Update to the latest version via Composer in your Laravel project:

   composer require --dev e-lodgy/coding-standard:^1.1.6
   

2. First Use Case Integrate with PHP_CodeSniffer to enforce E-Lodgy’s updated coding standards:

   ./vendor/bin/phpcs --standard=vendor/e-lodgy/coding-standard/src/E-Lodgy src/
   

3. Where to Look First

   • Ruleset File: vendor/e-lodgy/coding-standard/ruleset.xml (updated with PHPStan integration).
   • PHPStan Integration: New in v1.1.6, check phpstan.neon configuration (if provided) for static analysis rules.
   • Customization: Override the ruleset in your project’s phpcs.xml or .phpcs.xml:

     <config name="standard" value="E-Lodgy"/>
     

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Run in pre-commit hooks or CI (e.g., GitHub Actions), now with PHPStan support:

   # .github/workflows/phpcs.yml
   - name: Run PHP_CodeSniffer
     run: ./vendor/bin/phpcs --standard=E-Lodgy --warning-severity=0 src/
   - name: Run PHPStan
     run: ./vendor/bin/phpstan analyse --level=max src/
   

2. IDE Integration Configure PHPStorm or VSCode to auto-fix issues using the updated E-Lodgy standard:

   • PHPStorm: Add vendor/e-lodgy/coding-standard to Settings > Editor > Inspections > PHP > Code Sniffer.
   • VSCode: Use PHP Intelephense with phpcs and integrate PHPStan via the PHPStan extension.

3. Team Onboarding

   • Document the updated standard in CONTRIBUTING.md:

     Before submitting PRs, run:
     ./vendor/bin/phpcbf --standard=E-Lodgy src/
     ./vendor/bin/phpstan analyse --level=max src/
     

   • Use phpcbf (fixer) for auto-correction and PHPStan for static analysis.

4. Laravel-Specific Rules Leverage Laravel-specific sniffs (e.g., route naming, Blade consistency) and now also PHPStan rules for:

   • Type safety in Eloquent queries.
   • Deprecation warnings in Laravel dependencies.

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • PHPStan integration may introduce new static analysis rules conflicting with PHP_CodeSniffer. Solution: Merge rulesets or exclude conflicting rules in your project’s phpcs.xml:

     <rule ref="E-Lodgy">
         <exclude name="Generic.Files.LineEndings"/>
     </rule>
     

   • For PHPStan, configure phpstan.neon to exclude paths or adjust levels:

     includes:
         - vendor/e-lodgy/coding-standard/phpstan/
     excludePaths:
         - src/legacy/
     

2. Performance

   • Large codebases may slow down both phpcs and phpstan. Tip: Run incrementally:

     ./vendor/bin/phpcs --standard=E-Lodgy src/App/Http/Controllers/
     ./vendor/bin/phpstan analyse --level=max src/App/Http/Controllers/ --memory-limit=1G
     

3. False Positives

   • Legacy code may trigger warnings in PHPStan. Tip: Use <exclude> in phpstan.neon:

     excludePaths:
         - src/legacy/
     

4. Trailing Comma Fix

   • v1.1.6 now enforces trailing commas in arrays/objects. Tip: Use phpcbf to auto-fix:

     ./vendor/bin/phpcbf --standard=E-Lodgy --rules-exclude=Generic.Files.LineEndings src/
     

Debugging

• Verbose Output: Use --report=full for phpcs and --debug for phpstan:

  ./vendor/bin/phpcs --standard=E-Lodgy --report=full src/
  ./vendor/bin/phpstan analyse --debug src/
  

• Rule-Specific Help: Check PHP_CodeSniffer’s Sniff Documentation and PHPStan’s Error Levels.

Extension Points

1. Custom Rules Extend the standard by adding your own sniffs to phpcs.xml or PHPStan rules to phpstan.neon:

   <rule ref="E-Lodgy">
       <config name="customRules" value="vendor/your-package/sniffs"/>
   </rule>
   

   includes:
       - vendor/e-lodgy/coding-standard/phpstan/
       - vendor/your-package/phpstan/
   

2. Overriding Rules Modify the ruleset locally by copying vendor/e-lodgy/coding-standard/ruleset.xml and phpstan.neon to your project.

3. Integration with Laravel Tools

   • Laravel Pint: Use E-Lodgy’s standard as a basis for pint.json (complementary to phpcs/phpstan):

     {
       "preset": "laravel",
       "rules": {
         "array_syntax": "short",
         "trailing_comma_in_multiline": true
       }
     }
     

Tips

• Start Small: Begin with --warning-severity=3 for phpcs and --level=5 for phpstan to avoid overwhelming the team.
• Autofix: Use phpcbf for non-controversial fixes (e.g., trailing commas, spacing).
• Version Pinning: Lock the package version in composer.json to avoid unexpected rule changes:

  "require-dev": {
    "e-lodgy/coding-standard": "^1.1.6"
  }
  

• PHPStan Configuration: If phpstan.neon is not provided, create one in your project root and extend the E-Lodgy rules:

  includes:
      - vendor/e-lodgy/coding-standard/phpstan/