Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev supportpal/coding-standard
   

   Add to phpcs.xml (or phpcs.xml.dist):

   <config name="standard" value="SupportPal"/>
   

2. First Run

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

   Verify the default rules align with your team’s conventions (e.g., PSR-12 + SupportPal extensions).

3. Quick Check Use --report=summary to audit a single file:

   vendor/bin/phpcs --standard=SupportPal --report=summary app/Http/Controllers/UserController.php
   

Implementation Patterns

Workflows

• Pre-Commit Hooks Integrate with phpcs in Git hooks (e.g., via husky or pre-commit):

  vendor/bin/phpcs --standard=SupportPal --warning-severity=0 --error-severity=1
  

  Fail builds on warnings/errors (adjust severity as needed).

• CI/CD Integration Add to Laravel’s CI pipeline (e.g., GitHub Actions):

  - name: Run PHPCS
    run: vendor/bin/phpcs --standard=SupportPal --report=json > phpcs-results.json
  

  Use phpcs output to block merges or annotate PRs.

• Custom Rule Overrides Extend the standard by creating a custom phpcs.xml snippet:

  <rule ref="SupportPal">
      <exclude name="Generic.Files.LineEndings" /> <!-- Disable if using LF -->
      <arg name="lineEndings" value="LF" />       <!-- Force LF if enabled -->
  </rule>
  

Integration Tips

• IDE Support Configure PHPStorm/VSCode to use SupportPal as the default PHPCS standard:

  • PHPStorm: Settings > PHP > Quality Tools > PHP Code Sniffer > Default Standard.
  • VSCode: Extend phpcs.executablePath in settings.json and set "phpcs.standard": "SupportPal".

• Laravel-Specific Rules Leverage SupportPal’s Laravel-focused rules (e.g., Laravel.Artisan.CommandMethod, Laravel.Route.Naming) by:

  vendor/bin/phpcs --standard=SupportPal --extensions=php app/Console/ app/Http/
  

• Autofix Use --fix for auto-correctable issues (e.g., indentation, spacing):

  vendor/bin/phpcbf --standard=SupportPal src/
  

Gotchas and Tips

Pitfalls

• Rule Conflicts SupportPal extends PSR-12 but may override defaults (e.g., line length). Test with:

  vendor/bin/phpcs --standard=PSR12 --standard=SupportPal --report=diff
  

  Resolve conflicts by explicitly excluding rules:

  <exclude name="PSR12.Files.FileOpeningComment.SpaceAfterOpen" />
  

• Performance Exclude vendor/ and node_modules/ from scans to avoid slowdowns:

  <arg name="exclude" value="vendor|node_modules" />
  

• False Positives SupportPal’s Laravel.Route.Naming may flag dynamic routes (e.g., {id}). Suppress with:

  <exclude name="Laravel.Route.Naming" from="routes/web.php" />
  

Debugging

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

  vendor/bin/phpcs --standard=SupportPal --verbose app/Models/
  

• Rule Documentation Check the PHPCS documentation for rule names (e.g., SupportPal.Files.LineEndings).

Extension Points

• Custom Rules Add project-specific rules by creating a CustomSupportPal standard:

  <config name="standard" value="SupportPal,CustomSupportPal"/>
  

  Define CustomSupportPal in a separate phpcs.xml file.

• Severity Tuning Adjust severity per rule to avoid noise:

  <rule ref="SupportPal">
      <severity name="SupportPal.Files.LineEndings" value="warning" />
  </rule>
  

• Parallel Execution Speed up large codebases with --parallel=8 (requires PHPCS ≥3.7):

  vendor/bin/phpcs --standard=SupportPal --parallel=8 src/