Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev aik099/coding-standard
   

   Ensure PHP_CodeSniffer (v3.x+) is installed globally or via Composer:

   composer global require squizlabs/php_codesniffer
   

2. First Run: Run PHPCS with the custom standard on your Laravel project:

   vendor/bin/phpcs --standard=vendor/aik099/coding-standard src app config routes tests
   

3. IDE Integration:

   • PhpStorm: Configure PHPCS in Settings > Languages & Frameworks > PHP > Code Sniffer:
     • Standard: vendor/aik099/coding-standard/CodingStandard
     • Recommended: Enable "Run inspection by clicking the warning icon" for on-save checks.

First Use Case: Enforcing Team Standards

Use this standard to standardize code reviews and onboarding by:

• Running PHPCS in CI (e.g., GitHub Actions) to block non-compliant PRs.
• Adding a pre-commit hook (via husky or pre-commit) to auto-check staged files:

  vendor/bin/phpcs --standard=vendor/aik099/coding-standard --report=json $(git diff --cached --name-only --diff-filter=ACM | grep '\.php$')
  

Implementation Patterns

Workflows

1. Team Onboarding:

   • Document the standard in CONTRIBUTING.md with a sample PHPCS command.
   • Use --diff to show new violations in PRs:

     vendor/bin/phpcs --standard=vendor/aik099/coding-standard --diff src/app/Http/Controllers/
     

2. CI Integration:

   • Fail builds on violations (example GitHub Actions workflow):

     - name: Run PHPCS
       run: |
         vendor/bin/phpcs --standard=vendor/aik099/coding-standard --warning-severity=3 -n || exit 1
     

3. Fixing Violations:

   • Use --fix to auto-correct simple issues (e.g., indentation, spacing):

     vendor/bin/phpcs --standard=vendor/aik099/coding-standard --fix src/
     

   • Note: Not all rules support auto-fixing (e.g., naming conventions).

Laravel-Specific Tips

• Exclude Vendor Files: Add this to phpcs.xml (create if missing):

  <config name="exclude" value="vendor,node_modules,storage"/>
  

• Focus on Key Directories: Prioritize app/, routes/, and tests/ in CI to reduce noise.
• Custom Rules: Extend the standard by creating a phpcs.xml in your project root:

  <ruleset>
      <config name="standard" value="vendor/aik099/coding-standard/CodingStandard"/>
      <file>app/</file>
      <arg name="extensions" value="php"/>
      <arg name="tab-width" value="4"/>
  </ruleset>
  

Gotchas and Tips

Pitfalls

1. Outdated PHPCS:

   • The package supports PHPCS 3.x+, but Laravel’s default PHPCS (via phpunit/phpunit) may use an older version. Pin PHPCS explicitly in composer.json:

     "require-dev": {
         "squizlabs/php_codesniffer": "^3.7"
     }
     

2. False Positives:

   • Laravel’s dynamic properties (e.g., $request->input()) may trigger Squizlabs.PHP.Commenting.DocComment.MissingShort or PSR12.Methods.CamelCapsMethodName. Suppress these in phpcs.xml:

     <rule ref="Squizlabs.PHP.Commenting.DocComment.MissingShort">
         <properties>
             <property name="ignore" value="^app\/Http\/Controllers\/.*"/>
         </properties>
     </rule>
     

3. Performance:

   • PHPCS can be slow on large projects. Use --parallel (PHPCS 3.6+) or cache results:

     vendor/bin/phpcs --standard=vendor/aik099/coding-standard --cache=~/.phpcs_cache src/
     

Debugging

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

  vendor/bin/phpcs --standard=vendor/aik099/coding-standard --verbose app/Http/Controllers/
  

• Rule-Specific Help: List available rules with descriptions:

  vendor/bin/phpcs --standard=vendor/aik099/coding-standard --help
  

Extension Points

1. Custom Rules: Add project-specific rules by extending the standard in phpcs.xml:

   <rule ref="vendor/aik099/coding-standard/CodingStandard">
       <exclude name="PSR12.Methods.CamelCapsMethodName"/>
   </rule>
   <rule ref="CustomRule">
       <file>app/</file>
   </rule>
   

2. Sniff Development: Extend the standard by creating a custom sniff (e.g., app/CodeSniffer/CustomSniff.php) and reference it in phpcs.xml:

   <rule ref="app/CodeSniffer/CustomSniff"/>
   

3. Integration with Laravel Tools:

   • Laravel Pint: Use PHPCS for linting and Pint for auto-formatting (they complement each other).
   • Laravel Valet: Add a valet.php hook to run PHPCS on project open:

     <?php
     return [
         'commands' => [
             'phpcs' => 'vendor/bin/phpcs --standard=vendor/aik099/coding-standard --report=summary',
         ],
     ];