Code Sniffer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev php-collective/code-sniffer
   

   Add to composer.json under require-dev:

   "php-collective/code-sniffer": "^1.0"
   

2. Configure phpcs.xml: Place this in your project root:

   <?xml version="1.0"?>
   <ruleset name="ProjectName">
       <file>src/</file>
       <file>tests/</file>
       <rule ref="vendor/php-collective/code-sniffer/PhpCollective/ruleset.xml"/>
   </ruleset>
   

3. First Run:

   vendor/bin/phpcs
   

   Or via Composer script (add to composer.json):

   "scripts": {
       "cs-check": "phpcs -nps"
   }
   

   Run with:

   composer cs-check
   

First Use Case: Enforcing PSR-2/12 + Custom Rules

• Goal: Ensure all PHP files adhere to PSR-2/12 with PhpCollective’s extended rules (e.g., docblock consistency, type hints, array formatting).
• Workflow:
  1. Run composer cs-check to identify violations.
  2. Fix automatically where possible with:

     composer cs-fix  # Uses `phpcbf`
     

  3. Address manual fixes (e.g., docblock alignment, custom naming conventions).

Implementation Patterns

1. Integrating into CI/CD

• GitHub Actions Example:

  name: PHP Code Sniffer
  on: [push, pull_request]
  jobs:
    phpcs:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: composer install
        - run: composer cs-check
  

• Git Hooks: Use pre-commit hooks to run phpcs on staged files:

  composer require --dev laravel-pint/pre-commit
  

  Configure in .php-cs-fixer.dist.php or .phpcs.xml.

2. Custom Rule Extensions

• Override Default Rules: Extend phpcs.xml to disable/enable sniffs:

  <rule ref="vendor/php-collective/code-sniffer/PhpCollective/ruleset.xml">
      <exclude name="PhpCollective.WhiteSpace.EmptyLines"/>
      <config name="PhpCollective.Arrays.DisallowLongArraySyntax" value="true"/>
  </rule>
  

• Add Project-Specific Sniffs: Create a custom sniffer class (e.g., app/Sniffs/YourSniff.php) and reference it:

  <rule ref="app/Sniffs/YourSniff"/>
  

3. IDE Integration

• PHPStorm:
  • Set up External Tools for phpcs/phpcbf (as per README).
  • Use File Watchers for auto-fixing (whitelist safe sniffs only):

    <rule ref="PhpCollective.WhiteSpace"/>
    <rule ref="PhpCollective.Formatting"/>
    

  • Bind to keyboard shortcuts (e.g., Ctrl+Alt+S for sniffing).

4. Strict Mode Workflow

• Enable PhpCollectiveStrict: Replace the rule reference in phpcs.xml:

  <rule ref="vendor/php-collective/code-sniffer/PhpCollectiveStrict/ruleset.xml"/>
  

• Gradual Adoption:
  • Start with PhpCollective in development.
  • Run PhpCollectiveStrict in CI to catch regressions early.

5. Team Onboarding

• Documentation: Add a CONTRIBUTING.md snippet:

  ## Code Style
  Run `composer cs-check` before submitting PRs.
  Use `composer cs-fix` to auto-correct where possible.
  

• Pair Programming: Use phpcs during code reviews to highlight violations in real-time.

Gotchas and Tips

Pitfalls

1. False Positives:

   • Issue: Sniffs like PhpCollective.Arrays.DisallowLongArraySyntax may flag legacy code.
   • Fix: Exclude files/directories in phpcs.xml:

     <exclude-pattern>*/legacy/*</exclude-pattern>
     

2. Performance:

   • Issue: Large codebases slow down phpcs.
   • Fix:
     • Use --parallel (PHP_CodeSniffer ≥ 3.7):

       vendor/bin/phpcs --parallel=4
       

     • Cache results with phpcs --cache.

3. IDE Conflicts:

   • Issue: File watchers may cause merge conflicts if phpcbf modifies files.
   • Fix: Disable auto-fix in watchers; use manual composer cs-fix.

4. Strict Mode Breaking Changes:

   • Issue: PhpCollectiveStrict enforces strict type hints (e.g., PhpCollectiveStrict.TypeHints.PropertyTypeHint).
   • Fix: Migrate incrementally; use --report=summary to track progress:

     vendor/bin/phpcs --standard=PhpCollectiveStrict --report=summary
     

Debugging Tips

1. Verbose Output: Run with -v to debug rule application:

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

2. Isolate Sniffs: Test individual sniffs:

   vendor/bin/phpcs --standard=PhpCollective.Arrays src/
   

3. Custom Error Reporting: Generate a JSON report for CI:

   vendor/bin/phpcs --report=json > phpcs-report.json
   

Extension Points

1. Custom Sniffs:

   • Extend PHP_CodeSniffer\Standards\AbstractStandard to add project-specific rules.
   • Example: Enforce Laravel-specific naming (e.g., Request class naming).

2. Dynamic Rules: Use PHP_CodeSniffer\Config to load rules dynamically:

   $config = new PHP_CodeSniffer\Config();
   $config->addConfigData([
       'installed_paths' => [__DIR__.'/vendor/php-collective/code-sniffer'],
       'default_standard' => 'PhpCollective',
   ]);
   

3. Integration with PHPStan: Combine with phpstan/extension-installer to enforce both static analysis and style:

   composer require --dev phpstan/phpstan
   composer require --dev phpstan/extension-installer
   

Pro Tips

1. Partial Fixes: Use phpcbf selectively:

   vendor/bin/phpcbf --rules=PhpCollective.Formatting src/
   

2. Pre-commit Hooks: Leverage pre-commit to block style violations:

   composer require --dev php-cs-fixer
   composer require --dev laravel-pint/pre-commit
   

   Configure in .php-cs-fixer.dist.php to match phpcs.xml rules.

3. Visual Studio Code: Use the PHP Intelephense extension with phpcs integration:

   // .vscode/settings.json
   {
       "intelephense.codeSnifferEnabled": true,
       "intelephense.codeSnifferStandard": "PhpCollective"
   }
   

4. Legacy Code: For large refactors, use --ignore to bypass critical sniffs temporarily:

   vendor/bin/phpcs --ignore=PhpCollective.Arrays.DisallowLongArraySyntax