Phpcs Psr 12 Neutron Hybrid Ruleset Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is primarily designed for WordPress OOP development, introducing potential conflicts with Laravel’s conventions (e.g., Facades, Eloquent ORM, Service Container). While PSR-12 is Laravel-friendly, Neutron’s WordPress-specific rules (e.g., WordPress.DB.DirectDatabaseQuery, WordPress.Security.EscapeOutput) are irrelevant or counterproductive for Laravel projects. The Slevomat rules (e.g., strict types, docblock enforcement) align well with Laravel’s modern PHP practices but may require custom overrides for dynamic properties or magic methods.
• Hybrid Ruleset Trade-offs: The combination of PSR-12 (formatting) + Neutron (WordPress) + Slevomat (advanced) creates a bloated ruleset for Laravel. A leaner custom ruleset (e.g., PSR-12 + Slevomat only) might be preferable unless WordPress interoperability is a hard requirement.
• Laravel-Specific Gaps: Lacks native support for Laravel’s Facades, Service Container, or Eloquent, which may trigger false positives or require manual exclusions.

Integration Feasibility

• PHPCS Overhead: Adding PHPCS as a dev dependency introduces CI/CD complexity (execution time, caching needs). Laravel projects already using Pint (PSR-12 auto-fixer) or PHPStan may see redundant tooling.
• Customization Requirements: Heavy reliance on ruleset.xml overrides to disable WordPress-specific rules, increasing maintenance burden.
• Performance: PHPCS runs can be slow for large codebases; parallel execution (e.g., php-parallel-lint) or cached results may be necessary.
• IDE Integration: Requires PHP_CodeSniffer IDE plugins (e.g., VSCode PHPCS) for real-time feedback, adding developer setup friction.

Technical Risk

Key Questions

1. Scope of Adoption:
   • Should this ruleset apply only to WordPress plugins within the Laravel project, or entirely to the Laravel codebase?
2. Rule Overrides:
   • Which Neutron/WPCS rules are non-negotiable for WordPress interop, and which can be disabled?
   • Example: Should WordPress.Security.EscapeOutput be enforced for Blade templates or API responses?
3. Performance Trade-offs:
   • Is the CI/CD slowdown acceptable, or should PHPCS runs be gated to PRs only?
4. Developer Experience:
   • Should auto-fix (--fix) be enabled for PSR-12 formatting, or left manual?
   • How will Slevomat’s strict rules (e.g., NoUnusedPrivateMethods) be received?
5. Long-Term Viability:
   • How will this interact with Laravel’s deprecations (e.g., Facades → Containers)?
   • Should custom sniffs be developed for Laravel-specific patterns (e.g., app/Providers)?

Integration Approach

Stack Fit

• Ideal Use Cases:
  • Laravel projects with embedded WordPress plugins/themes (e.g., custom admin panels, REST APIs for WordPress).
  • Teams needing PSR-12 + WordPress compliance without managing multiple rulesets.
• Poor Fit:
  • Pure Laravel applications (Neutron/WPCS rules add unnecessary constraints).
  • Teams using alternative static analysis tools (e.g., PHPStan, Psalm) for type enforcement.
• Complementary Tools:
  • Laravel Pint: Handles PSR-12 formatting; reduce PHPCS overlap by disabling PSR-12 rules in this package.
  • PHPStan: Can replace Slevomat’s type-related rules (e.g., TypeHint), reducing PHPCS load.
  • WordPress Plugin Boilerplate: If using, align PHPCS rules with its conventions.

Migration Path

1. Assessment Phase:

   • Run PHPCS on Laravel’s core files to identify false positives.
   • Example command:

     ./vendor/bin/phpcs --standard=PSR12NeutronRuleset --report=full src/ --exclude=vendor/
     

   • Document conflicting rules (e.g., WordPress.DB, Slevomat.TypeHint).

2. Custom Ruleset Creation:

   • Create a ruleset.xml to override irrelevant rules:

     <ruleset name="LaravelHybrid">
         <rule ref="PSR12NeutronRuleset">
             <exclude name="WordPress.DB.DirectDatabaseQuery" />
             <exclude name="WordPress.Security.EscapeOutput" />
             <exclude name="SlevomatCodingStandard.TypeHint.TypeHintDeclaration.MissingTraversableTypeHint" />
         </rule>
         <!-- Add custom sniffs for Laravel patterns -->
         <rule ref="Custom/LaravelSniffs" />
     </ruleset>
     

   • Use --ignore=* for initial runs to identify high-severity issues.

3. Phased Rollout:

   • Phase 1: Enforce PSR-12 formatting (low risk, use --fix).
   • Phase 2: Enable Slevomat rules (medium risk; allow opt-outs).
   • Phase 3: Enable WordPress-specific Neutron rules (high risk; limit to plugin directories).
   • Phase 4: Integrate with CI/CD as a required check.

4. CI/CD Integration:

   • Add to GitHub Actions/GitLab CI with caching and parallelization:

     - name: PHPCS
       uses: php-actions/phpcs@v1
       with:
         args: "--standard=PSR12NeutronRuleset --report=checkstyle --ignore=vendor/ src/"
         cache: true
     

   • Gate PHPCS only on PRs to reduce CI load.

Compatibility

Sequencing

1. Audit Existing Code:
   • Run PHPCS on Laravel’s core to baseline false positives.
   • Prioritize fixes for high-severity issues (e.g., file permissions, strict types).
2. Pilot with a Subteam:
   • Test with 1-2 developers in a non-critical module (e.g., a plugin).
   • Gather feedback on rule overrides and developer experience.
3. Gradual Enforcement:
   • Start with PSR-12 + Slevomat (disable Neutron for Laravel core).
   • Enable Neutron rules only for WordPress-related directories.
4. Automate Overrides:
   • Use ruleset.xml to permanently exclude Laravel-incompatible rules.
   • Develop custom sniffs for Laravel-specific patterns (e.g., app/Providers).
5. CI/CD Hardening:
   • Add PHPCS as a required check in CI.
   • Cache results to improve performance.

Operational Impact

Maintenance

• Dependency Management:
  • Neutron and Slevomat rulesets are **