Coding Style Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev camelot/coding-style
   

   For global installation (optional):

   composer global require camelot/coding-style
   

2. Configure CodeSniffer (phpcs.xml.dist):

   <?xml version="1.0"?>
   <ruleset>
       <arg name="colors"/>
       <file>app</file>
       <file>src</file>
       <file>tests</file>
       <rule ref="vendor/camelot/codingstyle/Camelot"/>
   </ruleset>
   

   Commit this file to enforce consistency across the team.

3. Run a quick check:

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

First Use Case: Pre-Commit Hook

Integrate with Laravel’s workflow by adding a pre-commit hook to auto-check coding standards:

# Example using git hooks (add to `.git/hooks/pre-commit`)
#!/bin/sh
vendor/bin/phpcs --standard=Camelot --colors app/ || exit 1

Implementation Patterns

Workflow Integration

1. Daily Linting: Use phpcs in your IDE (e.g., PHPStorm) or CLI to catch issues early:

   vendor/bin/phpcs --standard=Camelot --report=full app/Http/Controllers/
   

2. Automated Fixes with Code Fixer: Configure .php_cs.dist in your Laravel project:

   <?php
   return Camelot\CsFixer\Config::create()
       ->addRules(Camelot\CsFixer\Rules::create()->risky()->php74())
       ->in('app', 'tests')
       ->setFinder(
           \PhpCsFixer\Finder::create()
               ->exclude('vendor')
               ->notPath('*.blade.php')
       );
   

   Run fixes:

   vendor/bin/php-cs-fixer fix
   

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

   - name: Run PHP_CodeSniffer
     run: vendor/bin/phpcs --standard=Camelot --warning-severity=9 app/
   

Laravel-Specific Tips

• Exclude Blade Files: Add to phpcs.xml.dist:

  <exclude-pattern>*.blade.php</exclude-pattern>
  

• Focus on Key Directories: Prioritize app/Http, app/Models, and app/Console in early checks.
• Custom Rules: Extend the Camelot standard by overriding rules in phpcs.xml:

  <rule ref="Camelot">
      <exclude name="Generic.Files.LineEndings" />
  </rule>
  

Gotchas and Tips

Common Pitfalls

1. Global vs. Local Config:

   • Global installs require installed_paths setup. Prefer project-specific installs for Laravel.
   • Fix: Use composer require --dev and commit phpcs.xml.dist.

2. Performance with Large Codebases:

   • Exclude vendor/ and non-PHP files (e.g., .env, composer.lock) to speed up checks.
   • Tip: Use --ignore=vendor flag or configure in phpcs.xml:

     <exclude-pattern>vendor/</exclude-pattern>
     

3. Blade Template Conflicts:

   • Camelot’s standard may flag Blade syntax (e.g., @foreach). Exclude Blade files or adjust rules:

     <exclude-pattern>*.blade.php</exclude-pattern>
     

4. Risky Rules:

   • Enable ->risky() in Code Fixer cautiously—some rules (e.g., no_unused_imports) may break functionality.
   • Debug: Test risky rules on a backup branch first.

Debugging Tips

• Verbose Output: Use --report=diff to see exact changes needed:

  vendor/bin/php-cs-fixer fix --dry-run --diff
  

• Rule-Specific Checks: Isolate issues by targeting a single rule:

  vendor/bin/phpcs --standard=Camelot --rules=Camelot.Files.LineEndings app/
  

• IDE Integration: Configure PHPStorm to use the Camelot standard:
  • Settings > PHP > Code Sniffer: Set standard to Camelot and path to vendor/camelot/codingstyle.

Extension Points

1. Custom Rulesets: Extend the Camelot standard by creating a child ruleset in phpcs.xml:

   <rule ref="Camelot">
       <arg name="line_ending" value="LF"/>
       <arg name="encoding" value="UTF-8"/>
   </rule>
   

2. PHP-CS-Fixer Custom Rules: Add project-specific rules to .php_cs.dist:

   ->addRules([
       '@PSR12' => true, // Merge with PSR-12 if needed
       'no_unused_imports' => true,
       'concat_space' => ['spacing' => 'one'],
   ])
   

3. JavaScript (Future-Proofing): Monitor the repo for JS linting updates. For now, use ESLint with a Laravel-compatible config (e.g., laravel-mix).