Phpcs Psr 12 Neutron Hybrid Ruleset Laravel Package

Getting Started

Minimal Setup for Laravel Developers

1. Install the package in your Laravel project:

   composer require --dev szepeviktor/phpcs-psr-12-neutron-hybrid-ruleset
   

2. Run PHPCS on your Laravel codebase (exclude vendor/):

   ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --ignore=vendor/ app/
   

3. First Use Case: Integrate into your CI pipeline (e.g., GitHub Actions) to enforce standards on every push:

   # .github/workflows/phpcs.yml
   name: PHPCS
   on: [push, pull_request]
   jobs:
     phpcs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --error-severity=5 --warning-severity=0 app/
   

Key Starting Points

• Laravel-Specific Exclusions: Immediately exclude Neutron/WPCS rules that conflict with Laravel patterns (e.g., WordPress.DB.DirectDatabaseQuery).
• Focus Areas:
  • Start with PSR-12 formatting (low friction).
  • Gradually enable Neutron rules for WordPress interop (e.g., WordPress.Security).
  • Use Slevomat rules sparingly (e.g., TypeHint, Arrays) to avoid developer pushback.

Implementation Patterns

Workflows

1. Daily Development

• Pre-commit Hook: Use phpcs via a hook (e.g., husky) to catch issues before commits:

  # .husky/pre-commit
  #!/bin/sh
  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --warning-severity=3 app/
  

• IDE Integration: Configure your IDE (PHPStorm, VSCode) to use this ruleset for real-time feedback:

  // .php-cs-fixer.dist.php (optional for IDE integration)
  return (new PhpCsFixer\Config())
      ->setRules([
          '@PSR12NeutronRuleset' => true,
      ]);
  

2. CI/CD Pipeline

• GitHub Actions Example:

  - name: PHPCS (Laravel + WordPress Hybrid)
    run: |
      ./vendor/bin/phpcs \
        --standard=PSR12NeutronRuleset \
        --ignore=vendor/,tests/ \
        --exclude=WordPress.DB.DirectDatabaseQuery,WordPress.VIP \
        --error-severity=5 \
        app/
  

• Parallel Execution: For large codebases, split scans by directory:

  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset app/Http/ app/Models/ | tee phpcs-results.txt
  

3. Custom Ruleset Overrides

• Extend the Ruleset: Create a custom ruleset.xml in your project root:

  <?xml version="1.0"?>
  <ruleset name="LaravelHybridRuleset">
      <rule ref="PSR12NeutronRuleset">
          <!-- Disable WordPress-specific rules for Laravel -->
          <exclude name="WordPress.DB.DirectDatabaseQuery"/>
          <exclude name="WordPress.Security.EscapeOutput.OutputNotEscaped"/>
  
          <!-- Adjust Slevomat strictness -->
          <arg name="severity" value="5" name="SlevomatCodingStandard.TypeHint"/>
      </rule>
  
      <!-- Add custom sniffs for Laravel patterns -->
      <rule ref="Custom/Laravel/NoMagicMethodOverrides"/>
  </ruleset>
  

• Run with Custom Ruleset:

  ./vendor/bin/phpcs --standard=LaravelHybridRuleset app/
  

Integration Tips

• Laravel Facades: Exclude Neutron rules that flag Facades (e.g., Route::, Cache::) as "disallowed short open tags":

  <exclude name="WordPress.Security.NonceVerification.Missing"/>
  

• Eloquent vs. WPCS: Disable WordPress.DB rules entirely if using Eloquent:

  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --exclude=WordPress.DB.* app/
  

• Slevomat Trade-offs: Disable NoUnusedPrivateMethods if Laravel’s magic methods (e.g., __get) trigger false positives:

  <exclude name="SlevomatCodingStandard.UnusedPrivateElements.UnusedPrivateMethod"/>
  

• Auto-Fix: Use --fix for PSR-12 formatting (but avoid for Neutron/Slevomat):

  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --fix app/ --rules=PSR12
  

Gotchas and Tips

Pitfalls

1. False Positives with Laravel Patterns:

   • Issue: Neutron’s WordPress.Security rules may flag Laravel’s {{ }} Blade syntax or Facades.
   • Fix: Exclude irrelevant rules or add custom sniffs to whitelist Laravel constructs.
   • Example:

     <exclude name="WordPress.Security.EscapeOutput.OutputNotEscaped"/>
     

2. Performance Overhead:

   • Issue: PHPCS scans can slow down CI pipelines, especially for large Laravel monorepos.
   • Fix:
     • Cache results with --cache.
     • Parallelize scans using php-parallel-lint.
     • Exclude tests/ and vendor/ directories.

3. Slevomat Over-Strictness:

   • Issue: Rules like TypeHint or NoUnusedPrivateMethods may break Laravel’s dynamic properties or magic methods.
   • Fix: Disable or adjust severity for problematic rules:

     <arg name="severity" value="3" name="SlevomatCodingStandard.TypeHint"/>
     

4. Neutron’s WordPress-Centric Rules:

   • Issue: Rules like WordPress.DB.DirectDatabaseQuery are irrelevant for Laravel but may still trigger warnings.
   • Fix: Exclude the entire WordPress.DB category:

     ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --exclude=WordPress.DB.* app/
     

5. IDE Misconfiguration:

   • Issue: IDEs may not recognize the custom ruleset, leading to inconsistent feedback.
   • Fix: Configure your IDE to use the ruleset via .php-cs-fixer.dist.php or PHPCS plugins.

Debugging Tips

• Isolate Rule Failures: Run PHPCS on a single file to debug specific issues:

  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset app/Http/Controllers/UserController.php
  

• Verbose Output: Use --verbose to see which rules are being applied:

  ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --verbose app/
  

• Rule-Specific Debugging: Check why a rule failed by inspecting its documentation (e.g., Neutron rules on GitHub).

Configuration Quirks

1. @package Tag Confusion:

   • Issue: The ruleset enforces @package tags using PEAR-style naming (e.g., Vendor\Package), which may conflict with Composer autoloading.
   • Fix: Disable the rule or adjust the expected format:

     <exclude name="Generic.Files.DocCommentPackageNotMatchClass"/>
     

2. File Permissions:

   • Issue: The ruleset enforces strict file permissions (e.g., 644), which may conflict with Laravel’s storage/ or bootstrap/cache/ directories.
   • Fix: Exclude directories with custom permissions:

     ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --ignore=storage/,bootstrap/cache/ app/
     

3. Strict Types:

   • Issue: Slevomat’s TypeHint rule may fail on Laravel’s dynamic properties (e.g., $fillable in models).
   • Fix: Disable the rule or use @var annotations:

     /** @var array<string, mixed> */
     protected $fillable = [];
     

Extension Points

1. Custom Sniffs for Laravel:
   • Create project-specific sniffs to handle Laravel patterns not covered by the hybrid ruleset. Example:

     // Custom/Laravel/NoMagicMethodOverrides.php
     class NoMagicMethodOverrides extends AbstractSniff {
         public function register() {
             return [
                 T_METHOD => $this,
             ];
         }
         public function process(Tokens $tokens, $position) {
             // Logic to detect magic method overrides (e.g.,