Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev ninjify/coding-standard
   

2. Create ruleset.xml in your project root:

   <?xml version="1.0"?>
   <ruleset name="YourProject">
       <rule ref="./vendor/ninjify/coding-standard/ruleset.xml"/>
       <!-- Exclude test folders -->
       <exclude-pattern>tests/*</exclude-pattern>
   </ruleset>
   

3. Run PHPCS:

   vendor/bin/phpcs --standard=ruleset.xml src/
   

First Use Case

• Pre-commit hook: Integrate with phpcs to block non-compliant code:

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

  Add to .git/hooks/pre-commit:

  #!/bin/sh
  vendor/bin/phpcs --standard=ruleset.xml --report=emacs src/ || exit 1
  

Implementation Patterns

Workflows

1. Team Enforcement:

   • Use contributte.xml for Contributte/Apitte/Nettrine projects:

     <rule ref="./vendor/ninjify/coding-standard/contributte.xml"/>
     

   • Enforce via CI (GitHub Actions example):

     - name: PHP Coding Standards
       run: vendor/bin/phpcs --standard=ruleset.xml --warning-severity=0 src/
     

2. IDE Integration:

   • Import phpstorm/ rules into PhpStorm:
     • File > Settings > Editor > Code Style > PHP
     • Click Import Scheme > IntelliJ IDEA > Select phpstorm/coding-standard.xml

3. Custom Rulesets:

   • Extend ruleset.xml to override defaults:

     <config name="line_ending" value="LF"/>
     <rule ref="ruleset.xml">
         <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
     </rule>
     

Integration Tips

• Parallel Linting: Speed up checks with php-parallel-lint:

  vendor/bin/parallel-lint --no-cache src/ | vendor/bin/phpcs --standard=ruleset.xml --report=diff -
  

• Fix Automatically: Use phpcbf for auto-fixes (where possible):

  vendor/bin/phpcbf --standard=ruleset.xml src/
  

• GitHub PR Checks: Use phpcs in workflows to gate PRs:

  - name: Run PHPCS
    if: github.event_name == 'pull_request'
    run: vendor/bin/phpcs --standard=ruleset.xml --warning-severity=0 src/ || exit 1
  

Gotchas and Tips

Pitfalls

1. Strict Type Declarations:

   • Requires declare(strict_types=1); on first line of files (v0.12+).
   • Fix: Add to composer.json scripts:

     "scripts": {
         "post-autoload-dump": "php -r \"file_put_contents('src/index.php', '<?php declare(strict_types=1);\\n');\""
     }
     

2. Exclusion Patterns:

   • Wildcards (*) in <exclude-pattern> may not work as expected. Use absolute paths:

     <exclude-pattern>./tests/tmp/</exclude-pattern>
     

3. PHP Version Mismatch:

   • Rules assume PHP 7.4+ (v0.10+). Older PHP versions may trigger false positives.
   • Workaround: Downgrade to v0.9 for PHP 7.2/7.3:

     composer require ninjify/coding-standard:^0.9
     

4. Ternary Operator:

   • v0.11+ disallows forced ternary operators (e.g., return $a ? true : false;).
   • Fix: Rewrite to return $a; or use <exclude> in ruleset.xml.

Debugging

• Verbose Output: Run with -v to debug rule failures:

  vendor/bin/phpcs -v --standard=ruleset.xml src/
  

• Rule-Specific Checks: Isolate issues by referencing individual rules:

  vendor/bin/phpcs --standard=ruleset.xml --report=full src/ | grep "ERROR"
  

Extension Points

1. Custom Rules:

   • Add Slevomat sniffs to ruleset.xml:

     <rule ref="vendor/slevomat/coding-standard/Sniffs/Arrays/ArrayPushSniff.php"/>
     

   • Note: Ensure compatibility with existing rules.

2. PHPCS Configuration:

   • Override global PHPCS settings in ruleset.xml:

     <config name="tab_width" value="4"/>
     <config name="encoding" value="utf-8"/>
     

3. PHPStorm Integration:

   • Sync IDE settings with phpstorm/ folder:
     • Copy phpstorm/coding-standard.xml to ~/.PhpStorm2023.1/config/codestyles/.
     • Set as default in Settings > Editor > Code Style.

Pro Tips

• CI Caching: Cache vendor/ and .php_cs.cache/ in CI to speed up runs:

  - uses: actions/cache@v3
    with:
      path: |
        vendor/
        .php_cs.cache/
      key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
  

• Selective Enforcement: Use <exclude> for legacy code:

  <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint">
      <file>src/legacy/</file>
  </exclude>
  

• Documentation: Link to the Contributte Coding Standards for team onboarding.