Codesniffer Standard Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require --dev shiftonelabs/codesniffer-standard
   

   Add the standard to your phpcs.xml or phpcs.xml.dist:

   <config name="standard" value="Shiftonelabs"/>
   

2. First Use Case Run CodeSniffer on a file or directory:

   ./vendor/bin/phpcs app/
   

   Verify the new rules (e.g., Shiftonelabs.Arrays, Shiftonelabs.Namespaces) are applied.

3. Where to Look First

   • Ruleset Definition: Check vendor/shiftonelabs/codesniffer-standard/ruleset.xml for available rules.
   • Documentation: Review the PHP_CodeSniffer documentation for rule customization.
   • Example Config: Clone the default phpcs.xml from the package’s tests/ directory if available.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to your CI (e.g., GitHub Actions) to enforce standards pre-merge:

   - name: Run PHP_CodeSniffer
     run: ./vendor/bin/phpcs --standard=Shiftonelabs --warning-severity=0 app/
   

2. Pre-Commit Hook Use phpcs via a tool like Husky or Laravel Pint to catch issues early:

   composer require --dev laravel/pint
   ./vendor/bin/pint --test
   

3. Custom Rules Extension Extend existing rules by copying the package’s Shiftonelabs namespace to your project’s Custom namespace (e.g., app/Rules/Custom/Arrays.php) and override logic.

Common Use Cases

• Enforce Array Key Quotes: Ensure all array keys are quoted (rule: Shiftonelabs.Arrays.ArrayKeyQuotes).
• Namespace Consistency: Validate namespace declarations match directory structure (rule: Shiftonelabs.Namespaces).
• DocBlock Standards: Add project-specific PHPDoc requirements (e.g., @throws for exceptions).

Laravel-Specific Tips

• Artisan Command: Create a custom Artisan command to run phpcs with Shiftonelabs rules:

  php artisan make:command CheckCodeStandards
  

  public function handle() {
      $this->call('phpcs', [
          '--standard' => 'Shiftonelabs',
          '--extensions' => 'php',
          'app/',
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • If using multiple standards (e.g., PSR12 + Shiftonelabs), conflicts may arise. Prioritize rules in phpcs.xml:

     <arg name="report" value="full" />
     <arg name="report-width" value="120" />
     <config name="categories" value="1"/>
     

   • Test with --report=summary to identify overlapping rules.

2. Performance

   • Exclude large directories (e.g., vendor/, storage/) to speed up runs:

     <exclude-pattern>.*/vendor/.*</exclude-pattern>
     

3. False Positives

   • Custom rules may flag legitimate code. Adjust severity or disable rules:

     <rule ref="Shiftonelabs.Arrays.ArrayKeyQuotes">
         <severity>1</severity> <!-- Warning instead of error -->
     </rule>
     

Debugging

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

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

• Rule-Specific Help: Run ./vendor/bin/phpcs --help or check the package’s README for rule descriptions.

Extension Points

1. Add Custom Rules

   • Create a new rule class in app/Rules/Custom/ extending PHP_CodeSniffer_Standards_AbstractStandard.
   • Register it in phpcs.xml:

     <rule ref="Custom">
         <file>.</file>
     </rule>
     

2. Override Default Rules

   • Copy the package’s Shiftonelabs rules to your project’s Custom namespace and modify as needed.

3. Integrate with IDE

   • Configure your IDE (e.g., PHPStorm) to use the Shiftonelabs standard for real-time feedback:
     • PHPStorm: Settings > Editor > Inspections > PHP > CodeSniffer, add the standard path.

Configuration Quirks

• Case Sensitivity: Ensure phpcs.xml paths are case-sensitive (especially on Linux).
• PHP Version: Test with your project’s PHP version; some rules may behave differently across versions.
• Caching: Clear Composer cache if rules fail to load:

  composer clear-cache