Php Code Sniffer Standard Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require --dev iodigital-com/php-code-sniffer-standard:^29.5
   

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

   <config name="standard" value="IODigitalCom\PHPCodeSnifferStandard"/>
   

2. First Run

   vendor/bin/phpcs --standard=IODigitalCom\PHPCodeSnifferStandard app/
   

3. Key Files to Review

   • ruleset.xml (if provided) – Defines custom rules or overrides.
   • tests/ (if included) – Example sniffs or edge cases.
   • README.md – May outline specific conventions (e.g., naming, spacing).
   • Note: Ensure your project uses PHP 8.2+ (PHP 8.1 is no longer supported).

First Use Case

Enforce Laravel-Specific Coding Standards with PHP 8.5 Support Run PHPCS on a Laravel project to catch:

• Missing @return/@throws in controllers (now validated against PHP 8.5 type system).
• Improper use of Route:: vs. route() helper.
• Inconsistent Eloquent method naming (e.g., getUser() vs. fetchUser()).
• New: PHP 8.5 features (e.g., new attributes, array_unpack syntax) are now properly linted.

Implementation Patterns

Workflows

1. Pre-Commit Hook Integrate with phpcs in a Git hook to block non-compliant code:

   composer require --dev dealerdirect/phpcodesniffer-composer-installer
   

   Add to composer.json:

   "scripts": {
       "test": "phpcs --standard=IODigitalCom\PHPCodeSnifferStandard --report=full"
   },
   "require-dev": {
       "php": "^8.2"  // Enforce PHP 8.2+ compatibility
   }
   

2. CI/CD Pipeline Use in GitHub Actions/GitLab CI with PHP 8.5:

   - name: Run PHPCS (PHP 8.5)
     run: vendor/bin/phpcs --standard=IODigitalCom\PHPCodeSnifferStandard --warning-severity=0
     env:
       PHP_VERSION: "8.5"
   

3. Custom Rules for PHP 8.5 Extend the standard to handle new PHP 8.5 features (e.g., array_unpack):

   // app/CodeSniffer/CustomSniffs/PHP85ArrayUnpackSniff.php
   class PHP85ArrayUnpackSniff implements Sniff {
       public function register() {
           return [
               T_ARRAY_UNPACK => [$this, 'processArrayUnpack']
           ];
       }
   }
   

Integration Tips

• Laravel IDE Helper: Pair with barryvdh/laravel-ide-helper to ensure PHPDoc compliance with PHP 8.5 types.
• Sniff Prioritization: Use --severity flags to focus on critical issues:

  phpcs --standard=IODigitalCom\PHPCodeSnifferStandard --severity=5
  

• Partial Validation: Target specific files/directories:

  phpcs app/Http/Controllers/ --standard=IODigitalCom\PHPCodeSnifferStandard
  

• PHP 8.5-Specific Checks: Enable new sniffs for PHP 8.5 features:

  <rule ref="IODigitalCom.PHP85.Arrays.DisallowLegacyArrayUnpack"/>
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch

   • Breaking Change: PHP 8.1 is no longer supported. Ensure your project uses PHP 8.2+.
   • Fix: Update composer.json:

     "require": {
         "php": "^8.2"
     }
     

2. False Positives with PHP 8.5

   • New PHP 8.5 syntax (e.g., array_unpack) may trigger false positives.
   • Fix: Exclude or override rules in phpcs.xml:

     <exclude name="IODigitalCom.PHP85.Arrays.DisallowLegacyArrayUnpack" />
     

3. Performance with Large Codebases

   • Running PHPCS on large projects (e.g., 10K+ files) can be slow.
   • Fix: Use caching and parallel processing:

     phpcs --cache=./phpcs.cache --standard=IODigitalCom\PHPCodeSnifferStandard --parallel=4
     

4. Composer Autoloader Issues

   • Test assets may be included in the autoloader (fixed in v29.5.0).
   • Fix: Ensure composer.lock is up-to-date and run:

     composer dump-autoload
     

Debugging

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

  phpcs --standard=IODigitalCom\PHPCodeSnifferStandard --verbose
  

• Rule Isolation: Test individual sniffs:

  phpcs --standard=IODigitalCom\PHPCodeSnifferStandard --sniffs=IODigitalCom.PHP85.Arrays
  

• PHP 8.5 Compatibility: Validate your project’s PHP version:

  php -v  # Ensure PHP 8.2+ is used
  

Extension Points

1. Custom Standards for PHP 8.5 Merge with other standards (e.g., PSR12) in phpcs.xml:

   <config name="standard" value="IODigitalCom\PHPCodeSnifferStandard,PSR12"/>
   

2. Dynamic Rules for New PHP Features Use Sniff classes to enforce Laravel-specific logic (e.g., validate HasFactory trait usage with PHP 8.5 attributes):

   public function process(SimpleToken $token) {
       if ($token->getContent() === '#[HasFactory]') {
           $this->recordWarning('Use "use Illuminate\Database\Eloquent\HasFactory;"', $token->getPosition());
       }
   }
   

3. Configuration Overrides for PHP 8.5 Override default values per file/directory:

   <arg name="extensions" value="php,blade" />
   <arg name="tab-width" value="4" />
   <arg name="php-version" value="8.5" />  <!-- Explicitly set PHP version -->
   

4. GitHub Actions Best Practices Update your workflow to use the latest composer-install action:

   - uses: ramsey/composer-install@v2
     with:
       dependency-versions: locked