Php Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package to your Laravel project via Composer:

   composer require --dev shlinkio/php-coding-standard
   

2. Configure PHPCS Create or update phpcs.xml in your project root with:

   <?xml version="1.0"?>
   <ruleset name="Shlink Laravel Standard">
       <rule ref="Shlinkio" />
       <arg name="colors" value="true"/>
       <arg name="report" value="summary"/>
       <exclude-pattern>vendor/</exclude-pattern>
       <exclude-pattern>storage/</exclude-pattern>
       <exclude-pattern>bootstrap/cache/</exclude-pattern>
   </ruleset>
   

3. First Run Execute PHPCS on your Laravel app directory:

   vendor/bin/phpcs app/
   

   Focus on fixing errors in app/Http/Controllers/ or app/Models/ first.

Implementation Patterns

Daily Workflow

1. Local Development Run PHPCS before committing:

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

   Use --diff to check changes:

   vendor/bin/phpcs --diff --standard=Shlinkio app/
   

2. CI/CD Integration Add to your GitHub Actions workflow (.github/workflows/phpcs.yml):

   name: PHPCS
   on: [push, pull_request]
   jobs:
     phpcs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: shivammathur/setup-php@v2
           with:
             php-version: '8.2'
         - run: composer install --dev
         - run: vendor/bin/phpcs --standard=Shlinkio --warning-severity=3
   

3. IDE Integration Configure PHPStorm to use this standard:

   • Go to Settings > Editor > Code Style > PHP
   • Click ... > Import Scheme and select phpcs.xml

Laravel-Specific Patterns

1. Excluding Blade Files Add Blade exclusions to phpcs.xml:

   <exclude-pattern>resources/views/*.blade.php</exclude-pattern>
   

2. Handling Laravel Generators Ignore auto-generated files (e.g., migrations, factories):

   <exclude-pattern>database/migrations/*.php</exclude-pattern>
   <exclude-pattern>database/factories/*.php</exclude-pattern>
   

3. Custom Rules Overrides Override specific Shlink rules in phpcs.xml:

   <rule ref="Shlinkio.ArrayNotation">
       <severity>ignore</severity>
   </rule>
   

Gotchas and Tips

Common Pitfalls

1. False Positives in Blade Templates

   • Issue: PHPCS may flag array() syntax in Blade files.
   • Fix: Exclude Blade files or use {{ @php }} wrappers for complex logic.

2. Strict Comparisons in Laravel Core

   • Issue: Laravel uses == in some core files (e.g., Illuminate\Support\Arr).
   • Fix: Exclude vendor/ and focus on app/ directory.

3. Trailing Commas in JSON Configs

   • Issue: PHPCS may flag trailing commas in config/app.php.
   • Fix: Exclude config files or adjust the rule:

     <rule ref="Shlinkio.TrailingComma">
         <exclude-pattern>config/*.php</exclude-pattern>
     </rule>
     

Debugging Tips

1. Detailed Reports Use --report=full for verbose output:

   vendor/bin/phpcs --standard=Shlinkio --report=full app/
   

2. Rule-Specific Checks Test individual rules:

   vendor/bin/phpcs --standard=Shlinkio --rules=StrictComparisons app/
   

3. Ignoring Specific Files Temporarily ignore files during development:

   vendor/bin/phpcs --standard=Shlinkio --ignore=app/OldController.php
   

Performance Tips

1. Parallel Execution Speed up CI runs with --parallel:

   vendor/bin/phpcs --standard=Shlinkio --parallel=4
   

2. Cache Results Use --cache to avoid re-scanning unchanged files:

   vendor/bin/phpcs --standard=Shlinkio --cache=/tmp/phpcs.cache
   

Extension Points

1. Custom Rules Add project-specific rules after <rule ref="Shlinkio" />:

   <rule ref="Shlinkio">
       <exclude name="StrictComparisons"/>
   </rule>
   <rule ref="CustomRuleSet">
       <file>app/Rules/</file>
   </rule>
   

2. Integration with PHP-CS-Fixer Combine with PHP-CS-Fixer for auto-fixing:

   composer require --dev friendsofphp/php-cs-fixer
   ./vendor/bin/php-cs-fixer fix --rules=@Shlinkio
   

3. Visual Studio Code Add to .vscode/settings.json:

   {
       "php.validate.executablePath": "vendor/bin/phpcs",
       "php.validate.run": "onType",
       "php.validate.standard": "Shlinkio"
   }