Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev corpus/coding-standard
   

2. Configure PHP_CodeSniffer by creating a .phpcs.xml file in your project root:

   <?xml version="1.0"?>
   <ruleset name="Corpus Coding Standard">
       <config name="installed_paths" value="./vendor/corpus/coding-standard"/>
       <rule ref="Corpus"/>
   </ruleset>
   

3. Run PHPCS on a file or directory:

   vendor/bin/phpcs app/Http/Controllers/
   

First Use Case

• Quickly enforce consistent formatting in a Laravel controller:

  vendor/bin/phpcs app/Http/Controllers/UserController.php
  

  Fix violations automatically with:

  vendor/bin/phpcbf app/Http/Controllers/UserController.php
  

Implementation Patterns

Workflows

1. Pre-commit Hooks Integrate PHPCS into your Git workflow using husky or pre-commit:

   composer require --dev php-parallel-lint/php-parallel-lint
   

   Add a script to package.json:

   "scripts": {
       "test:phpcs": "phpcs --standard=Corpus --report=json app/ > phpcs-results.json"
   }
   

2. CI/CD Pipeline Add PHPCS checks in GitHub Actions:

   - name: Run PHPCS
     run: vendor/bin/phpcs --standard=Corpus --warning-severity=0 app/
   

3. Custom Rulesets Extend the default ruleset in .phpcs.xml:

   <ruleset>
       <rule ref="Corpus"/>
       <rule ref="Corpus.Methods.MethodParameterFormatting">
           <properties>
               <property name="maxLength" value="120"/>
           </properties>
       </rule>
   </ruleset>
   

Integration Tips

• Laravel IDE Helper Use barryvdh/laravel-ide-helper alongside PHPCS for consistent docblocks and type hints.
• PHPStan Combine with PHPStan for static analysis:

  composer require --dev phpstan/phpstan
  vendor/bin/phpstan analyse --level=5
  

• EditorConfig Sync PHPCS rules with .editorconfig for IDE consistency:

  [*.php]
  indent_style = space
  indent_size = 4
  

Gotchas and Tips

Pitfalls

1. Conflicting Rules

   • Corpus.ControlStructures.OpeningOneTrueBrace may clash with PSR-12’s brace style. Exclude it if needed:

     <rule ref="Corpus.ControlStructures.OpeningOneTrueBrace" severity="0"/>
     

   • MethodParameterFormatting aggressively breaks lines at 130 chars by default. Adjust via XML:

     <rule ref="Corpus.Methods.MethodParameterFormatting">
         <properties>
             <property name="maxLength" value="100"/>
         </properties>
     </rule>
     

2. Performance

   • PHPCS can be slow on large codebases. Use parallel linting:

     composer require --dev php-parallel-lint/php-parallel-lint
     vendor/bin/parallel-lint app/
     

3. False Positives

   • BinaryOperationNewline may flag complex ternary operators. Disable with:

     <rule ref="Corpus.General.BinaryOperationNewline" severity="0"/>
     

Debugging

• Dry Run Test rules without fixing:

  vendor/bin/phpcs --standard=Corpus --report=full app/ | grep -E "ERROR|WARNING"
  

• Verbose Output Debug sniff application:

  vendor/bin/phpcs -v app/Controller.php
  

Extension Points

1. Custom Sniffs Extend the standard by creating a custom sniff in app/CodeSniffer/Corpus/. Example: app/CodeSniffer/Corpus/Sniffs/Arrays/TrailingCommaSniff.php. Reference it in .phpcs.xml:

   <rule ref="app/CodeSniffer/Corpus/Sniffs/Arrays/TrailingCommaSniff"/>
   

2. Overriding Inherited Sniffs Disable Slevomat sniffs selectively:

   <rule ref="SlevomatCodingStandard.Arrays.TrailingArrayComma" severity="0"/>
   

3. Dynamic Configuration Use environment variables for rule properties (via phpcs.xml):

   <property name="maxLength" value="%env(MAX_PARAM_LENGTH,130)%"/>
   

   Set in .env:

   MAX_PARAM_LENGTH=100