Php Quality Config Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require assoconnect/php-quality-config
   

   Add the package to your project’s composer.json under require-dev if using it for testing/quality checks.

2. First Use Case Integrate with PHPStan or Psalm by extending their config files:

   // phpstan.neon
   extends = php://vendor/assoconnect/php-quality-config/phpstan.neon
   

   For PHP-CS-Fixer, use the included ruleset:

   # .php-cs-fixer.dist.php
   return PhpCsFixer\Config::create()
       ->setRulesetFile(__DIR__.'/vendor/assoconnect/php-quality-config/php-cs-fixer.ruleset.php');
   

3. Key Files to Explore

   • phpstan.neon: Strict type-checking rules (e.g., Laravel-specific checks).
   • psalm.xml: Static analysis configurations (e.g., docblock parsing).
   • php-cs-fixer.ruleset.php: Coding standard presets (e.g., PSR-12 + AssoConnect tweaks).

Implementation Patterns

Workflows

1. Laravel-Specific Integrations

   • Route/Controller Checks: PHPStan’s Laravel extension is pre-configured to enforce:
     • Route parameter type safety.
     • Middleware validation (e.g., auth, guest).
   • Database Rules: Psalm’s mixed return types for Eloquent queries are restricted to array|Collection.

2. Team Onboarding

   • Shared Baseline: Use the package’s configs as a starting point, then override in .phpstan.override.neon:

     includes = php://vendor/assoconnect/php-quality-config/phpstan.neon
     [phpstan.rules.laravel]
     checkRouteModelBinding = true
     

3. CI/CD Pipelines

   • Run checks in parallel (e.g., PHPStan + Psalm) with GitHub Actions:

     - name: PHPStan
       run: vendor/bin/phpstan analyse --level=max src
     - name: Psalm
       run: vendor/bin/psalm --init
     

Integration Tips

• Custom Rules: Extend PHPStan’s services.neon to add project-specific rules:

  services:
     - Assoconnect\QualityConfig\Rules\CustomRule
  

• Dynamic Configs: Use environment variables to toggle strictness:

  // phpstan.neon
  level = %env{STRICT_MODE}?max:5
  

Gotchas and Tips

Pitfalls

1. Overly Strict Defaults

   • The package enables max level in PHPStan by default. Start with level=5 and incrementally raise it.
   • Fix: Use --error-format=github to see actionable feedback.

2. Psalm Compatibility

   • Psalm’s mixed type may conflict with Laravel’s dynamic return types (e.g., Model::all()).
   • Fix: Add @var array<int, Model> to docblocks or use @psalm-suppress MixedReturnStatement.

3. PHP-CS-Fixer Conflicts

   • The ruleset may enforce line lengths (e.g., 120 chars) that clash with IDE settings.
   • Fix: Override in .php-cs-fixer.dist.php:

     ->setLineEnding("\n")
     ->setRules(['line_ending' => false])
     

Debugging

• PHPStan Errors:

  • Use --generate-mock-files to auto-generate mocks for unresolved dependencies.
  • Check phpstan.neon for excludePaths to ignore tests/vendors temporarily.

• Psalm Plugins:

  • Enable the laravel plugin in psalm.xml:

    <pluginClass>Vimeo\PsalmPlugin\Plugin</pluginClass>
    

Extension Points

1. Custom Rules Create a PHPStan rule by extending PhpStan\Rule\Rule and reference it in services.neon:

   namespace App\Rules;
   class NoHardcodedUrlsRule implements Rule
   {
       public function getNodeType(): string { return Url::class; }
       // ...
   }
   

2. Dynamic Analysis Use PHPStan’s parameters to conditionally enable rules:

   [phpstan.rules.functions]
   callableParametersCanBeTypeChecked = %env{DEBUG}?true:false
   

3. CI Feedback Generate a quality gate script (bin/quality-check.sh):

   #!/bin/bash
   set -e
   vendor/bin/phpstan analyse --level=max src || exit 1
   vendor/bin/psalm --no-cache --init || exit 1