Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require croct/coding-standard --dev
   

2. Run a quick check on your project root:

   ./vendor/bin/phpcs .
   

   • This executes PHP_CodeSniffer with Croct’s predefined ruleset.

3. Integrate with CI/CD (e.g., GitHub Actions) by adding the command to your workflow:

   - name: Run PHP CodeSniffer
     run: ./vendor/bin/phpcs --standard=./vendor/croct/coding-standard/croct .
   

First Use Case

• Pre-commit hook: Use phpcs to auto-fix or block non-compliant code before commits. Example with husky:

  ./vendor/bin/phpcs --standard=./vendor/croct/coding-standard/croct --report=emacs .
  

Implementation Patterns

Workflows

1. Daily Development

   • Run phpcs on demand or via IDE integration (e.g., PHPStorm’s CodeSniffer plugin).
   • Use --diff to check only changed files:

     ./vendor/bin/phpcs --standard=croct --diff app/Http/Controllers/
     

2. Team Enforcement

   • Pre-commit: Add to composer.json scripts:

     "scripts": {
       "cs-check": "phpcs --standard=croct --report=full ."
     }
     

   • CI Gate: Fail builds on violations (e.g., GitHub Actions):

     - name: Enforce Coding Standard
       run: ./vendor/bin/phpcs --standard=croct --warning-severity=3 || exit 1
     

3. Custom Rulesets

   • Extend Croct’s ruleset by copying the croct standard file (located at ./vendor/croct/coding-standard/croct) to your project’s root and modifying it:

     cp ./vendor/croct/coding-standard/croct ./croct-custom
     

   • Update phpcs command to use your custom file:

     ./vendor/bin/phpcs --standard=croct-custom .
     

Integration Tips

• Laravel IDE Helper: Pair with barryvdh/laravel-ide-helper to ensure IDE autocompletion aligns with coding standards.
• PHPStan: Combine with phpstan/extension-installer for static analysis:

  ./vendor/bin/phpstan analyse --level=max --memory-limit=1G
  

• Git Hooks: Use pre-commit to auto-fix minor issues (e.g., indentation):

  ./vendor/bin/phpcbf --standard=croct --diff .
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Croct’s standard may override Laravel’s default PSR-12 rules (e.g., strict line lengths or method ordering).
   • Fix: Review ./vendor/croct/coding-standard/croct for custom rules (e.g., Croct.Sniffs.*) and override them in your custom ruleset.

2. Performance

   • Large projects may slow down phpcs. Use --parallel (PHP 7.4+) for speed:

     ./vendor/bin/phpcs --standard=croct --parallel=8 .
     

3. False Positives

   • Croct’s rules may flag Laravel-specific patterns (e.g., __construct injection) as errors.
   • Workaround: Disable specific rules in your custom ruleset:

     [PHP]
     ; Disable rule for constructor injection
     Croct.Sniffs.Classes.DisallowConstructorInjection = 0
     

Debugging

• Verbose Output: Use --verbose to debug rule application:

  ./vendor/bin/phpcs --standard=croct --verbose app/Models/
  

• Rule Documentation: Check PHP_CodeSniffer’s docs for rule IDs (e.g., Croct.Sniffs.Files.LineLength).

Extension Points

1. Custom Rules

   • Add new rules by extending PHP_CodeSniffer:

     // app/CodeSniffer/Croct/ExtendedSniff.php
     class ExtendedSniff extends \PHP_CodeSniffer\Standards\AbstractSniff {}
     

   • Register them in your custom ruleset file.

2. Sniff Configuration

   • Override default sniff settings (e.g., line length) in your ruleset:

     [PHP]
     line_length = 120
     

3. Autofix

   • Use phpcbf (PHP Code Beauty Fix) for auto-correction:

     ./vendor/bin/phpcbf --standard=croct --diff .
     

   • Note: Not all rules are fixable; test changes in a branch first.

Pro Tips

• Sniff Prioritization: Use --warning-severity to control CI failures:

  ./vendor/bin/phpcs --standard=croct --warning-severity=5  # Only errors fail
  

• IDE Integration: Configure PHPStorm to use Croct’s standard:
  • Settings > Languages & Frameworks > PHP > Code Sniffer:
    • Path to PHPCS: ./vendor/bin/phpcs
    • Standard: ./vendor/croct/coding-standard/croct
• Documentation: Add a CODE_STANDARD.md to your repo explaining Croct’s rules and overrides.