Php Coding Standards Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add to your Laravel project’s composer.json under require-dev:

   composer require --dev solido/php-coding-standards:dev-master
   

   Ensure your composer.json explicitly locks the version to avoid unintended updates:

   "config": {
       "preferred-install": "dist",
       "sort-packages": true
   }
   

2. First Use Case: PHPCS Integration Run PHPCS with Solido’s standards directly:

   vendor/bin/phpcs --standard=./vendor/solido/php-coding-standards src/ tests/
   

   For a quick check, use the --report=summary flag to avoid overwhelming output.

3. First Use Case: PHPStan Integration Create a minimal phpstan.neon file in your project root:

   includes:
       - vendor/solido/phpstan-rules/extension.neon
       - vendor/kcs/phpstan-strict-rules/rules.neon
   parameters:
       level: max
       paths:
           - src
           - tests
   

   Run PHPStan:

   vendor/bin/phpstan analyse
   

4. First Use Case: Security Checks Add a security advisory check to your CI/CD pipeline:

   vendor/bin/security-checker security:check
   

Implementation Patterns

Daily Developer Workflows

1. Local Development

   • Pre-Commit Hook: Use a tool like Husky to run PHPCS and PHPStan before commits:

     # .husky/pre-commit
     #!/bin/sh
     vendor/bin/phpcs --standard=./vendor/solido/php-coding-standards src/ tests/ || exit 1
     vendor/bin/phpstan analyse --error-format=checkstyle || exit 1
     

   • VS Code Integration: Add PHPCS and PHPStan extensions to your editor for real-time feedback.

2. CI/CD Pipeline Integrate checks into Laravel’s GitHub Actions workflow (.github/workflows/laravel.yml):

   name: Laravel Coding Standards
   on: [push, pull_request]
   jobs:
       coding-standards:
           runs-on: ubuntu-latest
           steps:
               - uses: actions/checkout@v4
               - uses: actions/setup-php@v3
                 with:
                     php-version: '8.2'
               - run: composer install --prefer-dist --no-interaction
               - name: Run PHPCS
                 run: vendor/bin/phpcs --standard=./vendor/solido/php-coding-standards --report=full src/ tests/
               - name: Run PHPStan
                 run: vendor/bin/phpstan analyse --error-format=github
               - name: Run Security Check
                 run: vendor/bin/security-checker security:check
   

3. Custom Artisan Commands Create a custom Artisan command to run all checks:

   php artisan make:command CheckStandards
   

   Update the generated file (app/Console/Commands/CheckStandards.php):

   public function handle()
   {
       $this->info('Running PHPCS...');
       $this->callSilently('vendor/bin/phpcs', [
           '--standard=./vendor/solido/php-coding-standards',
           'src/',
           'tests/',
       ]);
   
       $this->info('Running PHPStan...');
       $this->callSilently('vendor/bin/phpstan', ['analyse']);
   
       $this->info('Running Security Check...');
       $this->callSilently('vendor/bin/security-checker', ['security:check']);
   }
   

   Run with:

   php artisan check:standards
   

Laravel-Specific Patterns

1. Excluding Laravel Framework Code Configure PHPStan to ignore Laravel’s internal files in phpstan.neon:

   parameters:
       excludePaths:
           - vendor/laravel/framework/
           - vendor/solido/*
   

2. Custom Rules for Laravel Extend Solido’s PHPStan rules to handle Laravel-specific patterns (e.g., dynamic properties):

   includes:
       - vendor/solido/phpstan-rules/extension.neon
       - vendor/kcs/phpstan-strict-rules/rules.neon
       - rules.neon  # Your custom rules
   

   Example rules.neon:

   parameters:
       rules:
           Solido\PHPStanRules\Rules\*:
               excludeClasses:
                   - Illuminate\Foundation\Application
                   - Illuminate\Database\Eloquent\Model
   

3. Integration with Laravel Valet Add checks to your ~/.valet/Laravel/valet.php for local development:

   if (file_exists(__DIR__ . '/../../composer.json')) {
       $composer = json_decode(file_get_contents(__DIR__ . '/../../composer.json'), true);
       if (isset($composer['require-dev']['solido/php-coding-standards'])) {
           putenv('VALET_PHPSTAN=1');
           putenv('VALET_PHPCS=1');
       }
   }
   

Gotchas and Tips

Common Pitfalls

1. Strict PHPStan Rules

   • Issue: PHPStan’s level: max may flag Laravel’s dynamic properties or magic methods as errors.
   • Fix: Exclude specific classes or methods in phpstan.neon:

     parameters:
         rules:
             PhpStan\Rules\*:
                 excludeClasses:
                     - Illuminate\Support\Traits\ForwardsCalls
     

2. PHPCS Path Issues

   • Issue: PHPCS fails with Could not open "./vendor/solido/php-coding-standards".
   • Fix: Ensure the path is correct and the package is installed. Use an absolute path if needed:

     vendor/bin/phpcs --standard=$(pwd)/vendor/solido/php-coding-standards src/
     

3. Dependency Conflicts

   • Issue: Conflicts between Solido’s PHPStan rules and other packages (e.g., phpstan/extension-installer).
   • Fix: Lock versions in composer.json:

     "require-dev": {
         "phpstan/extension-installer": "^1.1",
         "solido/phpstan-rules": "dev-master"
     }
     

4. CI/CD Timeouts

   • Issue: PHPStan or PHPCS runs take too long in CI, causing timeouts.
   • Fix: Cache dependencies and results:

     - name: Cache Composer
       uses: actions/cache@v3
       with:
           path: vendor
           key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
     - name: Cache PHPStan
       uses: actions/cache@v3
       with:
           path: .phpstan.cache
           key: ${{ runner.os }}-phpstan-${{ hashFiles('**/composer.lock') }}
     

5. Unstable dev-master

   • Issue: Breaking changes in dev-master may break your pipeline.
   • Fix: Regularly test updates in a separate branch and pin versions in composer.json:

     "minimum-stability": "dev",
     "prefer-stable": true,
     "config": {
         "allow-plugins": {
             "composer/semver": true
         }
     }
     

Debugging Tips

1. PHPCS Debugging

   • Run PHPCS with --debug to diagnose path or rule issues:

     vendor/bin/phpcs --standard=./vendor/solido/php-coding-standards --debug src/
     

   • Use --report=full for detailed error messages.

2. PHPStan Debugging

   • Run PHPStan with --verbose for detailed output:

     vendor/bin/phpstan analyse --verbose
     

   • Use --memory-limit=1G to avoid memory issues on large codebases.

3. Security Checker Debugging

   • Run with --format=json to analyze advisories programmatically:

     vendor/bin/security-checker security:check --format=json > security.json
     

Extension Points

1. Custom PHPCS Rules Extend Solido’s standards by creating a custom .phpcs.xml file:

   <config name="standard" value="./vendor/solido/php-coding-standards"/>
   <config name="extensions" value="php,inc,module,install,test,sh"/>
   <rule ref="solido">
       <exclude name="Generic.Files.LineEndings" />
   </rule>
   

2. Custom PHPStan Rules Add custom rules to phpstan.neon:

   includes:
       - vendor/solido/phpstan-rules/extension.neon
       - rules/custom.neon
   

   Example rules/custom.neon: