Coding Standard Laravel Package

Getting Started

Minimal Setup

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

   composer require --dev gyro/coding-standard
   

   Ensure phpcs is installed globally or via Composer:

   composer global require squizlabs/php_codesniffer
   

2. First Run Run PHPCS against your project’s root directory:

   vendor/bin/phpcs --standard=./vendor/gyro/coding-standard
   

   Or alias it in composer.json for convenience:

   "scripts": {
       "cs-check": "phpcs --standard=./vendor/gyro/coding-standard --report=full src/"
   }
   

   Execute with:

   composer cs-check
   

3. First Use Case Integrate into your CI pipeline (e.g., GitHub Actions) to enforce standards pre-merge:

   - name: Run Coding Standard
     run: composer cs-check
   

Implementation Patterns

Workflows

1. Pre-Commit Hooks Use phpcs in a pre-commit hook (e.g., via Husky) to block non-compliant commits:

   composer require --dev laravel/pint  # Optional: Auto-fix with Pint
   

   Example hook script:

   #!/bin/sh
   vendor/bin/phpcs --standard=./vendor/gyro/coding-standard --report=summary src/ || exit 1
   

2. IDE Integration Configure your IDE (PHPStorm/VSCode) to use the Gyro standard:

   • PHPStorm: Settings > Editor > Inspections > PHP > Coding Style > PHP > Configure > Custom Profile (point to the standard).
   • VSCode: Use the PHP Intelephense extension and add to settings.json:

     "intelephense.codingStandards": ["./vendor/gyro/coding-standard"]
     

3. Laravel-Specific Rules Extend the standard for Laravel conventions (e.g., route naming, service container binding):

   composer require --dev friendsofphp/php-cs-fixer
   

   Create a custom rule set in phpcs.xml:

   <config name="installed_paths" value="./vendor/gyro/coding-standard,./vendor/friendsofphp/php-cs-fixer"/>
   

4. Team Onboarding Document the standard in your CONTRIBUTING.md:

   ## Coding Standards
   Run `composer cs-check` before submitting PRs. Fix issues with:
   ```bash
   composer cs-fix  # If using PHP-CS-Fixer
   

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • The standard is forked from Doctrine/Tideways. Override conflicting rules in .phpcs.xml:

     <rule ref="Generic.Files.LineEndings" severity="warning">
         <properties>
             <property name="lineEnding" value="LF"/>
         </properties>
     </rule>
     

   • Common conflicts: PSR12 vs. Gyro’s property hooks syntax (see PR #1).

2. Performance

   • Exclude vendor/ and node_modules/ from checks to speed up runs:

     vendor/bin/phpcs --standard=./vendor/gyro/coding-standard --ignore=vendor/,node_modules/ src/
     

   • Cache results in CI with phpcs --cache-file=.phpcs.cache.

3. PHP Version Mismatch

   • The package drops PHP 7.4 support (see v1.2). Ensure your project uses PHP 8.0+:

     composer require php:^8.0
     

Debugging

1. Verbose Output Use --verbose to diagnose rule failures:

   vendor/bin/phpcs --standard=./vendor/gyro/coding-standard --verbose src/
   

   Look for FILE:LINE -- [TYPE] Found X messages.

2. Rule-Specific Help List available rules:

   vendor/bin/phpcs --standard=./vendor/gyro/coding-standard --list-rules
   

   Get help for a specific rule (e.g., Generic.Files.LineEndings):

   vendor/bin/phpcs --standard=./vendor/gyro/coding-standard --help=Generic.Files.LineEndings
   

Extension Points

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

   composer require --dev phpmd/phpmd
   

   Create CustomRuleset.xml:

   <ruleset>
       <rule ref="./vendor/gyro/coding-standard"/>
       <rule ref="custom-rules.xml"/>
   </ruleset>
   

2. Property Hooks Syntax The standard supports both #[Property] and @property syntax. Enforce consistency in phpcs.xml:

   <rule ref="Gyro.PropertyHooks.Syntax">
       <properties>
           <property name="preferred" value="verbose"/> <!-- or "regular" -->
       </properties>
   </rule>
   

3. Autofix Integration Pair with php-cs-fixer for auto-correction:

   composer require --dev friendsofphp/php-cs-fixer
   

   Configure in .php-cs-fixer.dist.php:

   return (new PhpCsFixer\Config())
       ->setRules([
           '@Gyro' => true,
           'array_syntax' => ['syntax' => 'short'],
       ]);