Cakephp Codesniffer Laravel Package

Getting Started

Minimal Setup

1. Installation Update to the latest version via Composer (now fully compatible with PHP_CodeSniffer 4.0+):

   composer require --dev cakephp/cakephp-codesniffer:^5.3
   

   Ensure PHP_CodeSniffer 4.0+ is installed (no need for separate installation if using Composer):

   composer require --dev squizlabs/php_codesniffer:^4.0
   

2. First Run Run PHPCS with the CakePHP standard (remove all installed_paths references from config):

   vendor/bin/phpcs --standard=CakePHP app/
   

   • Use --report=full for detailed output.
   • Add --extensions=php to limit checks to PHP files.

3. Integration with Laravel Add a phpcs command to composer.json scripts:

   "scripts": {
       "test:phpcs": "phpcs --standard=CakePHP app/"
   }
   

   • Run via Artisan (if wrapped in a custom command):

     php artisan phpcs
     

Implementation Patterns

Workflows

1. Pre-Commit Hooks Use PHPCS 4.0+ in a Git pre-commit hook (adjust severity levels as needed):

   # .git/hooks/pre-commit
   #!/bin/sh
   vendor/bin/phpcs --standard=CakePHP --warning-severity=3 --error-severity=5 app/ || exit 1
   

   • Key Change: PHPCS 4.0 uses --warning-severity/--error-severity instead of deprecated flags.

2. CI/CD Pipeline Integrate into GitHub Actions with PHPCS 4.0’s JSON output:

   # .github/workflows/phpcs.yml
   jobs:
     phpcs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/phpcs --standard=CakePHP --report=json app/ > phpcs-results.json
   

   • Fail builds on warnings/errors or generate PR comments using phpcs-github-pr-comment.

3. Custom Rulesets (PHPCS 4.0+) Create a .phpcs.xml without installed_paths (fully deprecated in PHPCS 4.0):

   <config name="cache" value="true"/>
   <rule ref="CakePHP">
       <exclude name="CakePHP.NamingConventions.ValidClassNamePrefix.UpperCasePrefix"/>
   </rule>
   

   • Reference with --config-file=.phpcs.xml.

4. Laravel-Specific Adjustments

   • Namespaces: Override CakePHP rules for Laravel’s App namespace:

     <rule ref="CakePHP.NamingConventions.ValidClassNamePrefix">
         <properties>
             <property name="prefix" value="App\\|Illuminate\\"/>
         </properties>
     </rule>
     

   • Exclusions: Skip non-CakePHP files (e.g., config/, database/).

Gotchas and Tips

Pitfalls

1. Critical: installed_paths Deprecation

   • Issue: PHPCS 4.0 removes installed_paths support. Old configs will fail with:

     Warning: The 'installed_paths' config option is no longer supported.
     

   • Fix: Delete all installed_paths entries from .phpcs.xml and .phpcs.dist.xml. PHPCS 4.0 auto-detects the CakePHP standard via Composer autoload.

2. False Positives in Laravel

   • Issue: CakePHP’s ValidClassNamePrefix may flag Laravel’s RouteServiceProvider or AppServiceProvider.
   • Fix: Exclude files or adjust the rule:

     vendor/bin/phpcs --standard=CakePHP --ignore=app/Console/Kernel.php app/
     

     Or in .phpcs.xml:

     <file>app/Console/Kernel.php</file>
     

3. Performance with PHPCS 4.0

   • Issue: PHPCS 4.0 may be slower due to stricter rule processing.
   • Fix:
     • Enable caching in .phpcs.xml:

       <config name="cache" value="true"/>
       

     • Use --parallel=4 (if supported) for parallel processing:

       vendor/bin/phpcs --standard=CakePHP --parallel=4 app/
       

4. Dynamic Class Names in Laravel

   • Issue: CakePHP’s ValidClassNamePrefix may fail on Laravel’s dynamic classes (e.g., Eloquent models).
   • Fix: Update the rule in .phpcs.xml:

     <rule ref="CakePHP.NamingConventions.ValidClassNamePrefix">
         <properties>
             <property name="prefix" value="App\\|Generated\\"/>
         </properties>
     </rule>
     

Debugging

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

  vendor/bin/phpcs --standard=CakePHP --verbose app/Models/User.php
  

• List Rules: PHPCS 4.0+ supports:

  vendor/bin/phpcs --standard=CakePHP --list-rules
  

• Test Locally: Run against a single file to isolate issues:

  vendor/bin/phpcs app/Http/Controllers/UserController.php
  

Extension Points

1. Custom Rules with PHPCS 4.0 Extend PHPCS by creating a Custom standard in vendor/custom-codesniffer/CakePHP/Sniffs/:

   mkdir -p vendor/custom-codesniffer/CakePHP/Sniffs/
   

   • Reference in .phpcs.xml:

     <rule ref="Custom"/>
     

2. Autofix with phpcbf Use PHPCS’s built-in fixer (test in a branch first):

   vendor/bin/phpcbf --standard=CakePHP --report=diff app/
   

3. IDE Integration

   • PHPStorm: Update the PHPCS path to vendor/bin/phpcs and ensure PHPCS 4.0+ is selected.
   • VSCode: Use the PHP Intelephense extension with PHPCS 4.0.

4. GitHub PR Comments Use phpcs-github-pr-comment with PHPCS 4.0’s JSON output:

   vendor/bin/phpcs --standard=CakePHP --report=json app/ > phpcs.json
   vendor/bin/phpcs-github-pr-comment --file=phpcs.json