Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev instaclick/coding-standard
   

   Add to your phpcs.xml or phpcs.xml.dist:

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

2. First Run

   vendor/bin/phpcs --standard=Instaclick app/
   

   Verify the standard applies by checking for BlankLineBeforeIfSniff violations.

3. Key Files

   • Focus on app/ and src/ directories first.
   • Check phpcs.xml for custom rules or exclusions.

Implementation Patterns

Workflow Integration

1. Pre-Commit Hook Add to .git/hooks/pre-commit:

   #!/bin/sh
   vendor/bin/phpcs --standard=Instaclick --warning-severity=0 $1
   

   Fail if violations exist (exit code 1).

2. CI/CD Pipeline Use in GitHub Actions or GitLab CI:

   - name: Run PHP_CodeSniffer
     run: vendor/bin/phpcs --standard=Instaclick --warning-severity=0 --report=json app/ > phpcs.json
   

   Parse JSON output for detailed reporting.

3. IDE Integration Configure PHPStorm:

   • Settings > PHP > Code Sniffer
   • Standard: Instaclick
   • Enable "Run inspection on save" for real-time feedback.

4. Team Onboarding

   • Document the standard in CONTRIBUTING.md.
   • Include a phpcs command in Makefile for quick checks:

     phpcs:
         @vendor/bin/phpcs --standard=Instaclick --report=full app/
     

Gotchas and Tips

Pitfalls

1. False Positives in Control Structures

   • BlankLineBeforeIfSniff may flag Laravel blade templates or inline if conditions.
   • Fix: Exclude directories or use exclude in phpcs.xml:

     <arg name="exclude" value="resources/views,tests/Unit/" />
     

2. Symfony/Object Calisthenics Overhead

   • Rules like "No else clauses" (from Object Calisthenics) may conflict with Laravel’s if-else patterns.
   • Tip: Disable specific sniffs temporarily:

     <rule ref="Instaclick">
         <exclude name="ObjectCalisthenics.NoElseClauseSniff"/>
     </rule>
     

3. Performance with Large Codebases

   • Running on vendor/ or node_modules/ is unnecessary.
   • Optimize: Use --ignore to skip non-PHP files:

     vendor/bin/phpcs --standard=Instaclick --ignore="*,*.blade.php,*.md" app/
     

Debugging

1. Verbose Output Use --report=full to see line numbers and context:

   vendor/bin/phpcs --standard=Instaclick --report=full app/
   

2. Sniff-Specific Help List available sniffs:

   vendor/bin/phpcs --standard=Instaclick --list-sniffs
   

   Example output:

   Instaclick.Formatting.BlankLineBeforeIfSniff
   Instaclick.ObjectCalisthenics.NoElseClauseSniff
   

3. Customizing Rules Override specific rules in phpcs.xml:

   <rule ref="Instaclick.Formatting.BlankLineBeforeIfSniff">
       <properties>
           <property name="allowEmptyStatements" value="true"/>
       </properties>
   </rule>
   

Extension Points

1. Adding Custom Sniffs Extend the standard by creating a new sniff class and referencing it in phpcs.xml:

   <rule ref="Custom.MyNewSniff"/>
   

2. Combining with Other Standards Merge with PSR12 or Laravel’s standard:

   <config name="standard" value="Instaclick,PSR12"/>
   

3. Autofixing Violations Use --fix for auto-correctable issues (if supported):

   vendor/bin/phpcbf --standard=Instaclick app/
   

   Note: Not all sniffs support autofixing. Test changes in a branch first.