Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev spaze/coding-standard
   

2. Configure PHPCS by creating or updating .phpcs.xml in your project root:

   <?xml version="1.0"?>
   <ruleset>
       <config name="installed_paths" value="./vendor/spaze/coding-standard"/>
       <rule ref="SlevomatCodingStandard"/>
   </ruleset>
   

3. Run PHPCS to test:

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

First Use Case

Enforce consistent code style in a Laravel feature branch:

• Add the package to a new branch.
• Configure .phpcs.xml to include only critical rules (e.g., trailing commas, docblock formatting).
• Run PHPCS in CI (e.g., GitHub Actions) to block violations before merging.

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Add a PHPCS step to your pipeline (e.g., GitHub Actions):

     - name: Run PHPCS
       run: vendor/bin/phpcs --standard=SlevomatCodingStandard --warning-severity=3 --error-severity=5 app/
     

   • Configure severity levels (--warning-severity, --error-severity) to fail builds on critical violations.

2. IDE Integration:

   • Use PHPStorm’s built-in PHPCS support to get real-time feedback:
     • Go to Settings > Languages & Frameworks > PHP > Code Sniffer.
     • Set the standard to SlevomatCodingStandard and point to the installed ruleset.

3. Incremental Adoption:

   • Start with a subset of rules (e.g., Arrays.TrailingComma, Commenting.EmptyComment) to avoid overwhelming the team.
   • Gradually enable stricter rules (e.g., Classes.BackedEnumTypeSpacing, Functions.RequireTrailingCommaInDeclaration).

Laravel-Specific Patterns

1. Excluding Vendor Code:
   • Add exclusions to .phpcs.xml:

     <arg name="exclude" value="vendor,storage,bootstrap/cache"/>
     

2. Custom Rulesets for Teams:
   • Extend the default ruleset in .phpcs.xml:

     <rule ref="SlevomatCodingStandard">
         <exclude name="SlevomatCodingStandard.Arrays.TrailingArrayComma"/>
         <include name="SlevomatCodingStandard.Functions.RequireTrailingCommaInCall"/>
     </rule>
     

3. Integration with Laravel Mix/Pint:
   • Use PHPCS after laravel-pint in CI to catch formatting issues:

     - run: npm run production
     - run: vendor/bin/pint
     - run: vendor/bin/phpcs --standard=SlevomatCodingStandard app/
     

Debugging Workflows

1. Fixing False Positives:

   • Use --report=full to get detailed violation reports:

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

   • Temporarily exclude problematic files/rules while debugging.

2. Rule-Specific Debugging:

   • Test individual rules with --ruleset:

     vendor/bin/phpcs --standard=SlevomatCodingStandard --ruleset=SlevomatCodingStandard.Arrays.TrailingArrayComma app/
     

Gotchas and Tips

Pitfalls

1. PHPCS 4.0 Migration:

   • Issue: The package requires PHPCS 4.0+, which may break existing setups using older versions.
   • Fix: Update PHPCS:

     composer require --dev squizlabs/php_codesniffer:^4.0
     

   • Note: Some error codes changed in PHPCS 4.0 (see upgrade guide).

2. Rule Conflicts with PSR-12:

   • Issue: Some rules (e.g., SpacingAfterBlock) override PSR-12 defaults, causing unexpected violations.
   • Fix: Review the Slevomat rules documentation to understand deviations from PSR-12.

3. Performance in Large Codebases:

   • Issue: PHPCS can be slow on large projects (e.g., Laravel monorepos).
   • Fix:
     • Use --parallel for multi-core processing:

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

     • Cache results in CI (e.g., GitHub Actions’ actions/cache).

4. IDE Misconfiguration:

   • Issue: IDEs (e.g., PHPStorm) may not pick up the new ruleset automatically.
   • Fix: Restart the IDE or manually refresh the PHPCS configuration.

Debugging Tips

1. Isolate Violations:
   • Run PHPCS on a single file to debug:

     vendor/bin/phpcs --standard=SlevomatCodingStandard app/Http/Controllers/ExampleController.php
     

2. Check Rule Documentation:
   • Use the Slevomat rules docs to understand why a violation occurred (e.g., UselessParentheses).
3. Temporarily Disable Rules:
   • Exclude a rule in .phpcs.xml to bypass it while fixing other issues:

     <rule ref="SlevomatCodingStandard">
         <exclude name="SlevomatCodingStandard.PHP.UselessParentheses"/>
     </rule>
     

Extension Points

1. Custom Rules:
   • Extend the ruleset by adding your own PHPCS sniffs and referencing them in .phpcs.xml:

     <rule ref="SlevomatCodingStandard"/>
     <rule ref="Custom/Sniff/Example"/>
     

2. Dynamic Rulesets:
   • Use environment variables or CI flags to toggle rules:

     <config name="severity" value="%env.CI_SEVERITY%"/>
     

3. Integration with PHPStan:
   • Combine with phpstan/extension-installer to enforce both static analysis and coding standards:

     composer require --dev phpstan/extension-installer
     

   • Configure phpstan.neon to use the same ruleset:

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

Configuration Quirks

1. installed_paths Pitfall:
   • Issue: Older versions of the package set installed_paths in the ruleset file, which can cause conflicts.
   • Fix: Ensure .phpcs.xml explicitly sets the path:

     <config name="installed_paths" value="./vendor/spaze/coding-standard"/>
     

2. PHP 8+ Specific Rules:
   • Issue: Rules like Classes.BackedEnumTypeSpacing may not apply to PHP <8.1 code.
   • Fix: Exclude them for older PHP versions:

     <rule ref="SlevomatCodingStandard">
         <exclude name="SlevomatCodingStandard.Classes.BackedEnumTypeSpacing"/>
     </rule>
     

3. Heredoc/Nowdoc Rules:
   • Note: The package allows tabs in heredoc/nowdoc (since v1.7.2), which may conflict with other tools (e.g., laravel-pint). Align configurations to avoid inconsistencies.

Pro Tips

1. Leverage PHPCS Fixers:
   • Use --fix to automatically correct simple violations (e.g., trailing commas):

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

2. Git Hooks for Local Enforcement:
   • Add a pre-commit hook to run PHPCS locally:

     # .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/phpcs --standard=SlevomatCodingStandard --warning-severity=3 --error-severity=5
     

3. Document Exceptions:
   • Maintain a .phpcs-exceptions.md file to document why certain rules are disabled for specific files/classes. Example:

     ## Exceptions
     - `SlevomatCodingStandard.Arrays.TrailingArrayComma`: Disabled for `app/OldLegacyCode.php` (third-party library).