Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev slevomat/coding-standard
   

   Add to your project's phpcs.xml (or create one):

   <config defaultStandard="SlevomatCodingStandard">
       <arg name="standard" value="SlevomatCodingStandard"/>
   </config>
   

2. First Run:

   vendor/bin/phpcs --standard=SlevomatCodingStandard app/
   

First Use Case

Run the coding standard on your Laravel project's core files (e.g., app/ directory) to catch:

• Functional issues: Dead code, unsafe patterns (e.g., null safe operator bans).
• Cleaning issues: Unused properties, redundant comments.
• Formatting: Inconsistent spacing, array syntax, or attribute ordering.

Use --diff flag for pre-commit hooks:

vendor/bin/phpcs --standard=SlevomatCodingStandard --diff app/

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks: Use phpcs in a Git hook to enforce standards before commits:

   vendor/bin/phpcs --standard=SlevomatCodingStandard --warning-severity=3 --errors-on-incomplete=1 app/
   

   Exit with non-zero on errors to block commits.

2. CI/CD Pipeline: Add to Laravel's CI (e.g., GitHub Actions):

   - name: Run Slevomat Coding Standard
     run: vendor/bin/phpcs --standard=SlevomatCodingStandard --warning-severity=3 --errors-on-incomplete=1 app/
   

3. Auto-Fix: Enable auto-fixing for supported sniffs (marked with 🔧 in the list):

   vendor/bin/phpcbf --standard=SlevomatCodingStandard --diff app/
   

Laravel-Specific Patterns

• Service Container Sniffs: Use SlevomatCodingStandard.Classes.ClassLength to enforce reasonable class sizes for Laravel services (e.g., < 200 lines).
• Route/Controller Sniffs: Apply SlevomatCodingStandard.ControlStructures.EarlyExit to Laravel controllers for cleaner error handling.
• Migration Sniffs: Use SlevomatCodingStandard.Arrays.AlphabeticallySortedByKeys for up()/down() method arrays in migrations.

Custom Rulesets

Extend the standard in phpcs.xml:

<rule ref="SlevomatCodingStandard">
    <exclude name="SlevomatCodingStandard.Arrays.DisallowPartiallyKeyed"/>
    <exclude name="SlevomatCodingStandard.Classes.ClassLength"/>
    <arg name="severity" value="5"/>
</rule>

Gotchas and Tips

Pitfalls

1. Performance:

   • Large codebases (e.g., Laravel + plugins) may slow down phpcs. Exclude vendor directories:

     <file>./app</file>
     <file>./config</file>
     <exclude-pattern>./vendor/</exclude-pattern>
     

   • Cache results with --cache flag for repeated runs.

2. False Positives:

   • Attributes: Some sniffs (e.g., SlevomatCodingStandard.Attributes.DisallowMultipleAttributesPerLine) may conflict with Laravel's attribute usage (e.g., #[Route]). Suppress locally:

     // phpcs:ignore SlevomatCodingStandard.Attributes.DisallowMultipleAttributesPerLine
     #[Route('/test'), Name('test')]
     

   • Magic Methods: Sniffs like SlevomatCodingStandard.Classes.ForbiddenPublicProperty may flag Laravel's magic properties (e.g., $app). Exclude them in phpcs.xml:

     <exclude name="SlevomatCodingStandard.Classes.ForbiddenPublicProperty">
         <property>app</property>
     </exclude>
     

3. Auto-Fix Limitations:

   • Not all sniffs support auto-fixing (e.g., SlevomatCodingStandard.Classes.ClassLength). Test phpcbf in a branch first:

     git checkout -b fix-coding-standard
     vendor/bin/phpcbf --standard=SlevomatCodingStandard app/
     git diff
     

Debugging

• Verbose Output: Use --verbose to debug sniff failures:

  vendor/bin/phpcs --standard=SlevomatCodingStandard --verbose app/Models/User.php
  

• Sniff-Specific Docs: Reference the official docs for edge cases (e.g., SlevomatCodingStandard.ControlStructures.DisallowNullSafeObjectOperator vs. Laravel 8.50+ features).

Extension Points

1. Custom Sniffs: Extend the standard by creating a custom phpcs.xml file:

   <rule ref="SlevomatCodingStandard">
       <include name="YourVendor\YourCustomSniff"/>
   </rule>
   

2. Laravel-Specific Sniffs: Contribute sniffs to the package (e.g., for Blade templates or Facade usage) via GitHub Issues.

Pro Tips

• Pair with PHPStan: Combine with PHPStan for static analysis:

  vendor/bin/phpstan analyse --level=7
  vendor/bin/phpcs --standard=SlevomatCodingStandard app/
  

• Onboarding: Add a phpcs check to your composer.json scripts:

  "scripts": {
      "cs-check": "phpcs --standard=SlevomatCodingStandard --warning-severity=3 app/"
  }
  

  Run with:

  composer cs-check