Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package to your Laravel project:

   composer require --dev zetacomponents/coding-standard phpcs/phpcs
   

   Ensure phpcs is installed globally or via Composer’s phpcodesniffer-composer-installer:

   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   

2. Configure PHPCS Create or update phpcs.xml in your project root to use the Zeta Components ruleset:

   <?xml version="1.0"?>
   <ruleset name="Zeta Components Laravel">
       <config name="install_path" value="vendor/zetacomponents/coding-standard"/>
       <config name="standard" value="ZetaComponents"/>
       <file>app/</file>
       <exclude-pattern>*/tests/*</exclude-pattern>
   </ruleset>
   

3. First Use Case Run PHPCS on a Laravel file (e.g., a controller) to validate adherence:

   vendor/bin/phpcs app/Http/Controllers/ExampleController.php
   

   Address violations or suppress them if justified (e.g., legacy code).

Implementation Patterns

Usage Patterns

1. CI/CD Integration Add PHPCS checks to your CI pipeline (e.g., GitHub Actions):

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

   Fail the build on errors (--error-severity=5).

2. Pre-Commit Hooks Use husky or pre-commit to run PHPCS before commits:

   composer require --dev husky
   npm install
   npx husky add .husky/pre-commit "vendor/bin/phpcs --standard=ZetaComponents --colors --warning-severity=3"
   

3. Laravel Artisan Command Create a custom Artisan command to enforce standards:

   php artisan make:command CheckCodingStandard
   

   Implement the command to run PHPCS with Zeta rules:

   public function handle()
   {
       $exitCode = Artisan::call('phpcs', [
           '--standard=ZetaComponents',
           '--colors',
           'app/',
       ]);
       if ($exitCode !== 0) {
           $this->error('Coding standard violations found!');
           exit(1);
       }
   }
   

   Register the command in app/Console/Kernel.php and add it to app/Console.php:

   protected $commands = [
       Commands\CheckCodingStandard::class,
   ];
   

4. IDE Integration Configure PHPStorm or VSCode to use PHPCS for real-time feedback:

   • PHPStorm: Go to Settings > PHP > Code Sniffer and set the standard to ZetaComponents.
   • VSCode: Install the "PHP CS Fixer" extension and configure it to use the Zeta ruleset.

Integration Tips

• Hybrid Rulesets Combine Zeta Components rules with PSR-12 or Laravel-specific rules:

  <ruleset>
      <rule ref="ZetaComponents"/>
      <rule ref="PSR12"/>
      <rule ref="Laravel">
          <exclude name="Classes.ClassDeclaration.MustNotBeAbstract"/>
      </rule>
  </ruleset>
  

• Custom Exceptions Suppress specific rules for legacy code or edge cases:

  <rule ref="ZetaComponents">
      <exclude name="Files.LineEndings.MustNotBeWindowsStyle"/>
  </rule>
  

• Auto-Fix with PHP-CS-Fixer Use php-cs-fixer to auto-fix issues where possible, then validate with PHPCS:

  vendor/bin/php-cs-fixer fix --rules=@ZetaComponents --dry-run
  vendor/bin/phpcs --standard=ZetaComponents app/
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts with Laravel Zeta Components may enforce rules that conflict with Laravel’s conventions (e.g., CamelCase methods vs. Laravel’s snake_case).

   • Solution: Override conflicting rules in a custom ruleset.xml or suppress them:

     <rule ref="ZetaComponents.NamingMethods.CamelCase">
         <severity>0</severity>
     </rule>
     

2. Performance Issues PHPCS can be slow on large codebases. Optimize by:

   • Excluding directories (e.g., tests, storage) in phpcs.xml.
   • Running PHPCS in parallel (if supported by your CI tool).

3. Legacy PHP Support Some Zeta rules may enforce PHP 5.x compatibility, which could conflict with modern Laravel features (e.g., typed properties, arrow functions).

   • Solution: Disable PHP 5.x-specific rules or document exceptions.

4. False Positives/Negatives Zeta’s rules may flag modern Laravel patterns as violations (e.g., short array syntax []).

   • Solution: Test rules against a sample of your codebase and adjust severity or suppress rules as needed.

5. Maintenance Burden The package is unmaintained (0 stars, no dependents). Fork and maintain it if critical rules are missing or broken.

Debugging

• Verbose Output Run PHPCS with verbose output to diagnose issues:

  vendor/bin/phpcs --standard=ZetaComponents --verbose app/
  

• Rule-Specific Debugging Isolate rule violations by running PHPCS with a single rule:

  vendor/bin/phpcs --standard=ZetaComponents --rules-list
  vendor/bin/phpcs --standard=ZetaComponents --rules=ZetaComponents.NamingClasses.CamelCase app/
  

Tips

1. Start Incrementally Begin by running PHPCS in CI with warnings only (--warning-severity=3), then gradually enforce errors.

2. Document Exceptions Clearly document why certain rules are suppressed or overridden in your team’s coding guidelines.

3. Combine with Other Tools Use PHPCS for Zeta-specific rules and php-cs-fixer or pint for general formatting:

   vendor/bin/php-cs-fixer fix --rules=@PSR12 --allow-risky=yes
   vendor/bin/phpcs --standard=ZetaComponents app/
   

4. Leverage IDE Features Configure your IDE to auto-fix PHPCS violations where possible (e.g., indentation, spacing).

5. Monitor Rule Effectiveness Periodically review PHPCS violations to ensure the rules remain relevant and useful for your team.