Coder Laravel Package

Getting Started

Minimal Setup for Laravel Integration

While drupal/coder is primarily designed for Drupal projects, Laravel developers can leverage its PHP_CodeSniffer integration for enforcing Drupal-like coding standards in shared PHP logic (e.g., API clients, legacy integrations, or custom PHP modules). Here’s how to start:

1. Install via Composer

   composer require --dev drupal/coder
   

2. Run a One-Time Check Target a specific directory (e.g., app/Modules or app/Shared):

   ./vendor/bin/phpcs --standard=Drupal --extensions=php app/Modules
   

   • Use --report=full for detailed output.
   • Add --warning-severity=3 to treat warnings as errors.

3. First Use Case: Pre-Commit Hook Integrate with Laravel’s pre-commit (via laravel-pint or custom scripts) to block non-compliant code:

   ./vendor/bin/phpcs --standard=Drupal --extensions=php app/Modules || exit 1
   

Implementation Patterns

1. Standardized Code Reviews

• Pattern: Use Drupal (coding standards) + DrupalPractice (best practices) in parallel.

  ./vendor/bin/phpcs --standard=Drupal,DrupalPractice app/Modules
  

• Workflow:
  1. Run during feature branches to catch issues early.
  2. Fix violations with --fix (where supported):

     ./vendor/bin/phpcs --standard=Drupal --extensions=php --fix app/Modules
     

2. IDE Integration

• PhpStorm/VSCode: Configure PHP_CodeSniffer as an external tool:
  • PhpStorm: Settings > Languages & Frameworks > PHP > Code Sniffer.
  • VSCode: Install the PHP Intelephense extension and set:

    "intelephense.codeSnifferEnabled": true,
    "intelephense.codeSnifferPath": "./vendor/bin/phpcs",
    "intelephense.codeSnifferStandard": "Drupal,DrupalPractice"
    

• Real-time feedback: Highlight violations as you type.

3. CI/CD Pipeline

• GitHub Actions Example:

  - name: Run Coder
    run: ./vendor/bin/phpcs --standard=Drupal,DrupalPractice --warning-severity=3 --extensions=php app/Modules
  

• Fail builds on violations (treat warnings as errors for critical paths).

4. Custom Rulesets

• Extend phpcs.xml.dist to override defaults or disable rules temporarily:

  <ruleset>
    <rule ref="Drupal">
      <exclude name="Drupal.Commenting.Deprecated"/> <!-- Skip deprecated comments -->
    </rule>
    <rule ref="DrupalPractice">
      <severity name="DrupalPractice.Functions.ValidFunctionName" value="warning"/>
    </rule>
  </ruleset>
  

• Laravel-Specific: Disable rules conflicting with Laravel conventions (e.g., Drupal.NamingConventions.ValidFunctionName for snake_case vs. Laravel’s camelCase).

Gotchas and Tips

Pitfalls

1. False Positives in Laravel Context

   • Issue: Rules like Drupal.NamingConventions.ValidVariableName expect snake_case but Laravel uses camelCase.
   • Fix: Exclude or override in phpcs.xml.dist:

     <rule ref="Drupal.NamingConventions">
       <exclude name="ValidVariableName"/>
     </rule>
     

2. Performance with Large Codebases

   • Issue: Slow execution on monolithic apps.
   • Fix:
     • Limit scope: Target only app/Modules or app/Shared.
     • Use --parallel (PHP 7.4+) for multi-core processing:

       ./vendor/bin/phpcs --parallel=4 --standard=Drupal app/Modules
       

3. --fix Limitations

   • Issue: Not all rules support auto-fixing (e.g., DrupalPractice).
   • Tip: Manually review output and apply fixes incrementally.

4. YAML/Markdown Files

   • Issue: phpcs may scan non-PHP files (e.g., .md, .yml) if --extensions is misconfigured.
   • Fix: Explicitly list PHP extensions:

     --extensions=php,module,inc
     

Debugging Tips

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

  ./vendor/bin/phpcs --standard=Drupal --verbose app/Modules
  

• Rule Documentation: Check Drupal’s Coder docs for rule explanations.
• Isolate Violations: Test subsets of files:

  ./vendor/bin/phpcs --standard=Drupal app/Modules/MyModule.php
  

Extension Points

1. Custom Sniffs

   • Extend drupal/coder by creating custom PHPCS sniffs (PHP classes) and referencing them in phpcs.xml.dist:

     <rule ref="Custom.MySniff"/>
     

   • Example: Enforce Laravel-specific PSR-12 rules alongside Drupal standards.

2. Combine with Other Tools

   • PHPStan: Use alongside phpstan.neon for static analysis:

     ./vendor/bin/phpstan analyse --level=5 && ./vendor/bin/phpcs --standard=Drupal app/
     

   • Pint: Auto-format code before running Coder:

     ./vendor/bin/pint && ./vendor/bin/phpcs --standard=Drupal app/
     

3. Git Hooks

   • Pre-commit: Block violations before commits:

     # .git/hooks/pre-commit
     #!/bin/sh
     ./vendor/bin/phpcs --standard=Drupal --extensions=php app/Modules || exit 1
     

   • Post-merge: Run on branch updates to avoid merge conflicts:

     git merge origin/main && ./vendor/bin/phpcs --standard=Drupal app/
     

Laravel-Specific Quirks

• Service Container Conflicts: Avoid naming classes/services with Drupal conventions (e.g., hook_* prefixes).
• Facade/Helper Methods: Disable DrupalPractice.Functions.ValidFunctionName if using Laravel’s Str:: or Helper classes.
• Database Layer: Exclude app/Models if using Eloquent (conflicts with Drupal.Database rules).