Coding Standard Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require --dev shipmonk/coding-standard
   

2. Generate phpcs.xml.dist: Copy the provided XML snippet into your project root. Ensure <file> tags match your project structure (e.g., src/, tests/).
3. Run a quick check:

   vendor/bin/phpcs src/
   

   Verify output for errors/warnings in your codebase.

First Use Case

• Onboarding: Use phpcs to validate new developer contributions before PRs.
• CI/CD: Integrate phpcs into your pipeline to block non-compliant code (e.g., GitHub Actions or GitLab CI).
• Pre-commit hooks: Run phpcs locally via a hook (e.g., with PHP-CS-Fixer or Husky).

Implementation Patterns

Workflows

1. Daily Development:

   • Run phpcs on modified files before committing:

     vendor/bin/phpcs src/Feature/NewFeature.php
     

   • Use --standard=ShipMonkCodingStandard to override phpcs.xml.dist temporarily:

     vendor/bin/phpcs --standard=ShipMonkCodingStandard src/
     

2. Team Enforcement:

   • Pull Requests: Add a step in your CI to fail PRs with coding standard violations:

     # Example GitHub Actions
     - name: Run PHP Coding Standard
       run: vendor/bin/phpcs --report=full --report-width=120
     

   • Code Reviews: Reference the ShipMonk Coding Standard rules in PR templates.

3. Automated Fixes:

   • Use phpcbf for auto-fixable issues (e.g., indentation, spacing):

     vendor/bin/phpcbf src/
     

   • Combine with PHP-CS-Fixer for broader fixes:

     composer require --dev friendsofphp/php-cs-fixer
     vendor/bin/php-cs-fixer fix src/ --rules=@ShipMonkCodingStandard
     

Integration Tips

• Laravel-Specific:
  • Exclude vendor/ and generated files (e.g., bootstrap/cache/) in phpcs.xml.dist:

    <exclude-pattern>vendor/</exclude-pattern>
    <exclude-pattern>bootstrap/cache/*</exclude-pattern>
    

  • Focus on app/, app/Http/, and routes/ for Laravel projects.
• Custom Rules:
  • Extend the standard by adding a custom rule file (e.g., ruleset.xml) and reference it:

    <rule ref="ShipMonkCodingStandard"/>
    <rule ref="ruleset.xml"/>
    

• IDE Integration:
  • Configure PHPStorm/VSCode to use phpcs for real-time feedback:
    • PHPStorm: Settings > PHP > Quality Tools > PHP Code Sniffer → Path to vendor/bin/phpcs.
    • VSCode: Install the PHP Intelephense extension and configure phpcs.executablePath.

Gotchas and Tips

Pitfalls

1. Cache Issues:

   • If phpcs behaves unexpectedly, clear the cache:

     rm -rf var/phpcs.cache
     

   • Ensure the cache directory in phpcs.xml.dist is writable.

2. Rule Conflicts:

   • ShipMonk’s standard may override default PSR rules. Test with:

     vendor/bin/phpcs --standard=PSR12 src/  # Compare with PSR12
     

   • Disable specific rules temporarily:

     <rule ref="ShipMonkCodingStandard">
       <exclude name="Generic.Files.LineEndings"/>
     </rule>
     

3. Performance:

   • Exclude large directories (e.g., storage/, public/) to speed up checks:

     <exclude-pattern>storage/*</exclude-pattern>
     

4. False Positives:

   • ShipMonk’s standard may flag Laravel-specific patterns (e.g., Route::group). Suppress these with:

     <exclude name="Generic.Files.DisallowPHPEndTags"/>
     

Debugging

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

  vendor/bin/phpcs --verbose src/
  

• Rule Explanation: For unclear errors, check the rule’s documentation in the slevomat/coding-standard repo (ShipMonk’s standard extends this).

Extension Points

1. Custom Rules:

   • Add rules to ruleset.xml:

     <rule ref="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
     

   • ShipMonk’s standard is modular; extend it without forking.

2. Severity Adjustments:

   • Change error/warning severity in phpcs.xml.dist:

     <rule ref="ShipMonkCodingStandard">
       <severity name="Generic.Files.LineEndings" value="1"/> <!-- 1 = warning -->
     </rule>
     

3. Sniffs Configuration:

   • Override sniff parameters (e.g., line length):

     <rule ref="SlevomatCodingStandard.Classes.LineLength">
       <properties>
         <property name="lineLength" value="140"/>
       </properties>
     </rule>
     

Pro Tips

• Consistency: Run phpcs on the entire codebase periodically to catch drift:

  vendor/bin/phpcs --report=summary
  

• Documentation: Add a CONTRIBUTING.md section linking to the ShipMonk Coding Standard for contributors.
• CI Feedback: Use --report=json for CI to parse violations programmatically:

  vendor/bin/phpcs --report=json > phpcs-results.json