Phpcs Neutron Standard Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require --dev squizlabs/php_codesniffer dealerdirect/phpcodesniffer-composer-installer automattic/phpcs-neutron-standard
   

   For a pre-configured ruleset (including WordPress standards), use:

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

2. Configure phpcs.xml Add this to your project’s root:

   <?xml version="1.0"?>
   <ruleset name="ProjectStandard">
       <rule ref="NeutronStandard"/>
       <!-- Optional: Extend with WordPress standards -->
       <rule ref="WordPress"/>
   </ruleset>
   

3. First Run Lint a file with sniff codes (critical for debugging):

   vendor/bin/phpcs -s src/MyClass.php
   

First Use Case: Enforcing Modern PHP Practices

Use this to catch:

• Missing strict types (declare(strict_types=1)).
• Long functions (configurable via maxFunctionLines).
• Improper spacing around return types (e.g., function foo():int vs. function foo(): int).
• Multiple blank lines between functions.

Implementation Patterns

Workflows

1. CI Integration Add to your CI pipeline (e.g., GitHub Actions):

   - name: Run PHP_CS_Fixer
     run: vendor/bin/phpcs --standard=NeutronStandard --warning-severity=0 src/
   

   Fail builds on warnings by omitting --warning-severity=0.

2. Editor Integration Configure your IDE (PHPStorm, VSCode) to use:

   • PHPStorm: Settings > Languages & Frameworks > PHP > Code Sniffer → Set standard to NeutronStandard.
   • VSCode: Install the PHP Intelephense extension and add to settings.json:

     "php-cs-fixer.executablePath": "vendor/bin/php-cs-fixer",
     "php-cs-fixer.rules": "@NeutronStandard"
     

3. Custom Rulesets Override defaults in phpcs.xml:

   <ruleset>
       <rule ref="NeutronStandard">
           <arg name="maxFunctionLines" value="50"/> <!-- Customize max lines -->
           <exclude name="DisallowGlobalFunctionsSniff"/> <!-- Disable a rule -->
       </rule>
   </ruleset>
   

Integration Tips

• Combine with WordPress Standards: Use NeutronRuleset for a pre-configured mix of Neutron + WordPress rules.
• Auto-Fixing: Pair with php-cs-fixer for automated fixes (e.g., spacing, newlines):

  composer require --dev friendsofphp/php-cs-fixer
  vendor/bin/php-cs-fixer fix --rules=@NeutronStandard src/
  

• Selective Linting: Target specific files/directories:

  vendor/bin/phpcs src/ --standard=NeutronStandard --extensions=php
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • Requires PHP 7.x+. Errors like TypeHintSniff failures may occur if using PHP <7.4.
   • Fix: Ensure your project’s php.ini and CI environment use PHP ≥7.4.

2. Strict Types Enforcement

   • RequireStrictTypesSniff ignores interfaces (per design). False positives may appear in interface files.
   • Workaround: Exclude interfaces from strict type checks in phpcs.xml:

     <rule ref="NeutronStandard.RequireStrictTypesSniff">
         <exclude pattern="#^.*\.php$#"/>
     </rule>
     

3. False Positives in Generators

   • TypeHintSniff may flag generator return types (e.g., Generator<int, string>) as invalid.
   • Fix: Update to v1.6.0+ (includes fixes for generator type hints).

4. Cache Issues

   • Outdated PHPCS cache can cause inconsistent results.
   • Fix: Clear cache before runs:

     vendor/bin/phpcs --config-set installed_paths vendor/automattic/phpcs-neutron-standard
     

5. Editor Plugin Quirks

   • Some IDE plugins (e.g., PHPStorm) may not auto-detect NeutronStandard. Manually specify the path:

     vendor/automattic/phpcs-neutron-standard
     

Debugging Tips

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

  vendor/bin/phpcs -v src/MyClass.php
  

• Isolate Rules: Test individual sniffs:

  vendor/bin/phpcs --standard=NeutronStandard/TypeHint src/MyClass.php
  

• Check Rule Severity: Use --severity to filter errors:

  vendor/bin/phpcs --severity=warning src/
  

Extension Points

1. Custom Sniffs Extend the standard by adding your own sniffs to phpcs.xml:

   <rule ref="NeutronStandard"/>
   <rule ref="./custom-sniffs/MySniff.php"/>
   

2. Override Rule Properties Modify rule behavior dynamically:

   <rule ref="NeutronStandard.DisallowLongformArraySniff">
       <properties>
           <property name="allowedPatterns" value="\['a', 'b'\]"/>
       </properties>
   </rule>
   

3. Exclude Files/Directories Skip specific paths:

   <file>src/</file>
   <exclude-pattern>.*/tests/.*</exclude-pattern>
   

Pro Tips

• Pair with phpstan: Combine with PHPStan for static analysis:

  composer require --dev phpstan/phpstan
  vendor/bin/phpstan analyse --level=max src/
  

• Document Violations: Add comments to phpcs.xml to explain rule rationale:

  <!-- NeutronStandard enforces strict types for type safety -->
  <rule ref="NeutronStandard.RequireStrictTypesSniff"/>
  

• Benchmark Rules: Profile performance with large codebases:

  time vendor/bin/phpcs --standard=NeutronStandard src/