Php Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev arty/php-coding-standard
   

2. Initialize PHPCS by creating phpcs.xml in your project root:

   <?xml version="1.0"?>
   <ruleset name="Arty Coding Standard">
       <rule ref="./vendor/arty/php-coding-standard/lib/phpcs/phpcs.xml" />
   </ruleset>
   

3. Initialize PHPStan by creating phpstan.neon:

   includes:
       - vendor/arty/php-coding-standard/lib/phpstan/phpstan.neon
   

4. Run PHPCS on your Laravel codebase:

   ./vendor/bin/phpcs src
   

5. Run PHPStan with max level (adjust --level as needed):

   ./vendor/bin/phpstan analyse --level=max src
   

First Use Case

Pre-commit hook: Integrate PHPCS/PHPStan into your Git workflow to catch style/bug issues before merging:

# Example in .git/hooks/pre-commit
#!/bin/sh
./vendor/bin/phpcs src || exit 1
./vendor/bin/phpstan analyse --level=5 src || exit 1

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline

   • Run PHPCS/PHPStan in GitHub Actions/GitLab CI:

     # .github/workflows/lint.yml
     jobs:
       lint:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install
           - run: ./vendor/bin/phpcs src
           - run: ./vendor/bin/phpstan analyse --level=max src
     

2. Laravel-Specific Rules

   • Extend PHPCS rules for Laravel conventions (e.g., App\Services\ namespace):

     <!-- phpcs.xml -->
     <rule ref="vendor/arty/php-coding-standard/lib/phpcs/phpcs.xml">
         <exclude-pattern>*/Tests/*</exclude-pattern>
         <exclude-pattern>*/Resources/*</exclude-pattern>
     </rule>
     

3. PHPStan Level Tuning

   • Use --level=5 for development, --level=max for production:

     # In package.json scripts
     "lint:strict": "phpstan analyse --level=max src"
     

4. PHPAt for Architecture

   • Validate Clean Architecture in Laravel:

     # phpstan.neon
     services:
         - { class: ArtyCodingStandard\PHPAt\CleanArchitectureTest, tags: ["phpat.test"] }
     

   • Run with:

     ./vendor/bin/phpstan analyse --extension=phpat src
     

Daily Usage

• Quick Checks:

  # Run PHPCS on changed files (via Git)
  git diff --name-only HEAD~1 | xargs ./vendor/bin/phpcs
  

• Fix Common Issues:
  • Use --fix flag for PHPCS (where supported):

    ./vendor/bin/phpcs --fix src
    

Gotchas and Tips

Pitfalls

1. PHPStan Performance

   • --level=max can be slow for large Laravel apps. Start with --level=5 and incrementally raise.
   • Exclude heavy dependencies (e.g., vendor/, node_modules/):

     excludeFiles:
         - '*/vendor/*'
         - '*/node_modules/*'
     

2. PHPCS False Positives

   • Laravel’s dynamic properties (e.g., $fillable) may trigger rules. Exclude or override:

     <!-- phpcs.xml -->
     <rule ref="vendor/arty/php-coding-standard/lib/phpcs/phpcs.xml">
         <exclude name="Generic.Files.LineEndings" />
     </rule>
     

3. PHPAt Overhead

   • Architecture tests (PHPAt) add runtime. Run separately:

     ./vendor/bin/phpstan analyse --extension=phpat --no-progress src
     

Debugging

1. PHPCS Errors

   • Use --report=full for detailed output:

     ./vendor/bin/phpcs --report=full src
     

   • Check phpcs.xml paths if rules fail to load.

2. PHPStan Errors

   • Isolate issues with --generate-baseline:

     ./vendor/bin/phpstan analyse --generate-baseline src
     

   • Compare against baseline to track regressions.

3. PHPAt Failures

   • Disable specific tests in phpstan.neon:

     services:
         - { class: ArtyCodingStandard\PHPAt\CleanArchitectureTest, tags: ["phpat.test"], disabled: true }
     

Extension Points

1. Custom Rules

   • Extend PHPCS rules in phpcs.xml:

     <rule ref="vendor/arty/php-coding-standard/lib/phpcs/phpcs.xml">
         <arg name="tab-width" value="4" />
     </rule>
     

   • Add PHPStan extensions via phpstan.neon:

     extends:
         - phpstan/extension-installer
     

2. Laravel-Specific Extensions

   • Use phpstan/laravel extension alongside:

     includes:
         - vendor/arty/php-coding-standard/lib/phpstan/phpstan.neon
         - vendor/phpstan/extension-installer/laravel.neon
     

3. Git Hooks

   • Combine with roave/security-advisories for dependency checks:

     composer require --dev roave/security-advisories
     

   • Add to composer.json:

     "scripts": {
         "lint": "phpcs src && phpstan analyse --level=5 src"
     }