Ezplatform Code Style Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev ezsystems/ezplatform-code-style
   

   Ensure PHP_CodeSniffer (squizlabs/php_codesniffer) is installed globally or via Composer:

   composer require --dev squizlabs/php_codesniffer
   

2. First Run Run the default Laravel-specific ruleset:

   vendor/bin/phpcs --standard=vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml app/
   

3. First Use Case Fix common Laravel-specific issues (e.g., missing @return annotations, incorrect route naming, or Eloquent query style) by running:

   vendor/bin/phpcbf --standard=vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml app/
   

Implementation Patterns

Workflows

1. CI/CD Integration Add to .github/workflows/lint.yml:

   - name: Run PHP_CodeSniffer
     run: vendor/bin/phpcs --standard=vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml --warning-severity=3 app/
   

2. Pre-Commit Hook Use phpcs via husky or pre-commit:

   echo 'vendor/bin/phpcs --standard=vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml app/' >> .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

3. Custom Ruleset Extend the default ruleset in phpcs.xml:

   <config name="standard" value="EzSystems/laravel-ruleset.xml"/>
   <config name="extensions" value="php,blade"/>
   

Integration Tips

• Blade Templates: Enable Blade linting by adding --extensions=blade to commands.
• IDE Support: Configure PHPStorm to use the ruleset via Settings > PHP > Quality Tools > PHP_CodeSniffer.
• Team Onboarding: Document the ruleset in CONTRIBUTING.md for new developers.

Gotchas and Tips

Pitfalls

1. Outdated Rules The package hasn’t been updated since 2021. Verify rules align with Laravel 10+ conventions (e.g., route naming, Facade usage). Workaround: Override rules in a custom .phpcs.xml file.

2. Blade-Specific Issues Blade-specific rules may not cover all edge cases (e.g., dynamic @include paths). Tip: Use phpcs --extensions=blade and manually review complex templates.

3. Performance Running phpcs on large codebases can be slow. Cache results in CI:

   vendor/bin/phpcs --cache=~/.phpcs-cache app/
   

Debugging

• False Positives: Disable specific rules temporarily:

  vendor/bin/phpcs --ignore=Generic.Files.LineEndings.Incorrect app/
  

• Rule Explanations: Use --report=full for detailed error messages.

Extension Points

1. Custom Rules Add new rules by extending EzSystems\CodeSniffer\Standards\Laravel\Ruleset:

   class MyCustomRule extends \PHP_CodeSniffer\Standards\AbstractStandard
   {
       public function register() { /* ... */ }
   }
   

   Register in vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml.

2. Sniff Configuration Override sniff settings in phpcs.xml:

   <rule ref="EzSystems.Laravel.Files.ClassFileName">
       <properties>
           <property name="prefix" value="App\"/>
       </properties>
   </rule>
   

3. Integration with laravel-shift/php-code-style Combine with other tools for broader coverage:

   vendor/bin/phpcs --standard=vendor/ezsystems/ezplatform-code-style/CodeSniffer/EzSystems/laravel-ruleset.xml --standard=vendor/laravel-shift/php-code-style/phpcs-ruleset.xml app/