Phpcs Neutron Ruleset Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev automattic/phpcs-neutron-ruleset
   

   Ensure phpcs is installed globally or via Composer:

   composer global require squizlabs/php_codesniffer
   

2. Basic Configuration Create a phpcs.xml (or phpcs.xml.dist) in your project root with the Neutron ruleset:

   <?xml version="1.0"?>
   <ruleset>
       <config name="installed_paths" value="./vendor/automattic/phpcs-neutron-ruleset"/>
       <rule ref="Neutron"/>
   </ruleset>
   

3. First Run Run PHPCS on a Laravel file (e.g., app/Http/Controllers/ExampleController.php):

   phpcs app/Http/Controllers/ExampleController.php
   

   Focus on fixing WordPress-specific violations (e.g., WordPress.WP.CapitalPDOTOR for class naming).

First Use Case: Laravel-WordPress Hybrid Project

If your Laravel app integrates with WordPress (e.g., REST API, plugins), use Neutron to enforce:

• Naming conventions (e.g., WP_ prefix for WordPress classes).
• Hook/Filter standards (e.g., add_action('init', [$this, 'method'])).
• Security rules (e.g., WordPress.Security.ValidatedSanitizedInput).

Example workflow:

1. Run PHPCS on a WordPress plugin directory inside Laravel:

   phpcs wp-plugins/my-plugin/
   

2. Fix violations like:
   • WordPress.WP.PrefixAllGlobals (ensure $_GET vars use WP_ prefix).
   • WordPress.WP.AlternativeFunctions (replace mysql_* with wpdb).

Implementation Patterns

1. Ruleset Composition

Combine Neutron with Laravel-specific rules (e.g., phpcs-standards):

<ruleset>
    <config name="installed_paths" value="./vendor/automattic/phpcs-neutron-ruleset,./vendor/squizlabs/php_codesniffer-standard"/>
    <rule ref="Neutron"/>
    <rule ref="Squiz"/>
    <exclude-pattern>*/tests/*</exclude-pattern> <!-- Skip tests -->
</ruleset>

2. CI/CD Integration

Add PHPCS to Laravel’s GitHub Actions (.github/workflows/phpcs.yml):

name: PHPCS
on: [push, pull_request]
jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: composer install
      - run: phpcs --standard=./phpcs.xml --extensions=php app/

3. Custom Exceptions

Disable specific rules for Laravel-specific code (e.g., WordPress.WP.PrefixAllGlobals for config files):

<rule ref="Neutron">
    <exclude name="WordPress.WP.PrefixAllGlobals"/>
</rule>

4. Pre-Commit Hook

Use husky to run PHPCS before commits:

# package.json
{
  "scripts": {
    "pre-commit": "phpcs --standard=./phpcs.xml --extensions=php app/"
  }
}

5. IDE Integration

Configure PHPStorm to use Neutron:

1. Go to Settings > PHP > Code Sniffer.
2. Set PHP Code Sniffer Path to your global PHPCS.
3. Add ./phpcs.xml as the Configuration File.

Gotchas and Tips

Pitfalls

1. False Positives in Laravel

   • Neutron’s WordPress.WP.PrefixAllGlobals may flag Laravel’s $_ENV or config vars.
   • Fix: Exclude config/ or bootstrap/ in phpcs.xml:

     <exclude-pattern>config/*,bootstrap/*</exclude-pattern>
     

2. Outdated Rules

   • Last release (2021) may miss Laravel 10+ features (e.g., enums, attributes).
   • Workaround: Pair with phpcs-standards/laravel or suppress irrelevant rules.

3. Performance

   • PHPCS can slow down CI for large projects.
   • Tip: Cache results or run only on changed files:

     phpcs --diff app/PreviousCommitHash app/CurrentCommitHash
     

4. WordPress-Specific Assumptions

   • Rules like WordPress.WP.AlternativeFunctions may conflict with Laravel’s DB layer.
   • Tip: Use <exclude> for non-WP files:

     <exclude name="WordPress.WP.AlternativeFunctions" from="Database/*"/>
     

Debugging

• Verbose Output: Run with -v to see skipped rules:

  phpcs -v app/Http/Controllers/
  

• Rule Explanation: Use --report=full to get details on violations.

Extension Points

1. Custom Rules Extend Neutron by adding your own ruleset:

   <rule ref="Neutron"/>
   <rule ref="./ruleset.xml"/> <!-- Your custom rules -->
   

2. Sniffs for Laravel Contribute to the package by adding Laravel-specific sniffs (e.g., for Illuminate\Support\Facades).

3. Dynamic Configuration Use PHPCS’s <arg> to pass project-specific values:

   <arg name="tab-width" value="4" />
   

Pro Tips

• Focus on Critical Rules: Prioritize WordPress.Security and WordPress.WP.CapitalPDOTOR for WordPress-Laravel hybrids.
• Leverage phpcs --ignore: Temporarily skip files during refactoring:

  phpcs --ignore=app/OldCode.php app/
  

• Combine with phpmd: Use PHPMD for additional complexity analysis:

  phpmd app/ text cleancode,codesize,unusedcode --exclude tests/