Php Quality Tools Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev bernardosecades/php-quality-tools
   

   Register the service provider in config/app.php under providers:

   Bernardosecades\PhpQualityTools\PhpQualityToolsServiceProvider::class,
   

2. Basic Configuration Publish the default config file:

   php artisan vendor:publish --provider="Bernardosecades\PhpQualityTools\PhpQualityToolsServiceProvider" --tag="config"
   

   Edit config/php-quality-tools.php to define your preferred tools (e.g., phpstan, pint, phpunit).

3. First Use Case Run a quality check for your project:

   php artisan php-quality-tools:check
   

   This executes all configured tools in sequence, stopping on failures if stop_on_failure is true.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Trigger checks in GitHub Actions, GitLab CI, or other CI tools:

   # Example GitHub Actions workflow
   jobs:
     quality-check:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: php artisan php-quality-tools:check
   

2. Pre-Commit Hooks Use php-quality-tools:check in a pre-commit hook (via husky or pre-commit) to enforce quality before commits:

   # .husky/pre-commit
   #!/bin/sh
   php artisan php-quality-tools:check --stop-on-failure
   

3. Custom Commands Extend the base command for project-specific logic:

   // app/Console/Commands/CustomQualityCheck.php
   namespace App\Console\Commands;
   
   use Bernardosecades\PhpQualityTools\Commands\QualityCheckCommand;
   use Illuminate\Console\Scheduling\Schedule;
   
   class CustomQualityCheck extends QualityCheckCommand
   {
       protected function getTools(): array
       {
           return array_merge(parent::getTools(), [
               'phpstan' => [
                   'command' => 'phpstan analyse --level=max src',
               ],
           ]);
       }
   }
   

   Register the command in app/Console/Kernel.php:

   protected function commands()
   {
       $this->load(__DIR__.'/Commands');
       $this->call('custom:quality-check');
   }
   

4. Parallel Execution For faster feedback, run tools in parallel using parallel-lint or GNU parallel:

   find . -name "*.php" | parallel --will-cite php -l {} > /dev/null
   php artisan php-quality-tools:check --tools=phpstan,pint
   

Tool-Specific Patterns

1. PHPStan Configure in php-quality-tools.php:

   'phpstan' => [
       'command' => 'phpstan analyse --level=max src',
       'ignore_failures' => false,
   ],
   

   Use phpstan.neon for project-specific rules.

2. Pint Auto-format PHP files:

   php artisan php-quality-tools:check --tools=pint
   

   Customize rules in pint.json.

3. PHPUnit Run tests with custom configurations:

   'phpunit' => [
       'command' => 'phpunit --testdox-html=tests/coverage.html',
   ],
   

4. Custom Tools Add arbitrary commands (e.g., psalm or infection):

   'psalm' => [
       'command' => 'vendor/bin/psalm --init',
       'stop_on_failure' => true,
   ],
   

Gotchas and Tips

Common Pitfalls

1. Tool Dependencies Ensure all tools (e.g., phpstan, pint) are installed via Composer:

   composer require --dev phpstan/phpstan pintphp/pint
   

2. Configuration Overrides Avoid hardcoding tool paths. Use the config file or environment variables:

   'phpstan' => [
       'command' => env('PHPSTAN_COMMAND', 'vendor/bin/phpstan analyse'),
   ],
   

3. Performance

   • Cache Results: Use --generate-baseline for PHPStan to skip unchanged files.
   • Parallelize: Run independent tools (e.g., pint, phpstan) in parallel.

4. Exit Codes Tools may return non-zero exit codes on warnings. Use ignore_failures to bypass:

   'pint' => [
       'command' => 'pint',
       'ignore_failures' => env('IGNORE_PINT_WARNINGS', false),
   ],
   

Debugging Tips

1. Verbose Output Enable debug mode for detailed logs:

   php artisan php-quality-tools:check --verbose
   

2. Dry Runs Test configurations without executing:

   php artisan php-quality-tools:check --dry-run
   

3. Tool-Specific Flags Pass custom flags directly:

   php artisan php-quality-tools:check --tools="phpstan:--memory-limit=1G"
   

Extension Points

1. Custom Validators Extend the QualityCheckCommand to add validation logic:

   protected function validateTools(): void
   {
       foreach ($this->tools as $tool => $config) {
           if (!file_exists($config['command'])) {
               $this->error("Tool '$tool' command not found: {$config['command']}");
               exit(1);
           }
       }
   }
   

2. Event Listeners Dispatch events for post-check actions (e.g., Slack notifications):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'Bernardosecades\PhpQualityTools\Events\CheckCompleted' => [
          'App\Listeners\NotifySlackOnFailure',
      ],
   ];
   

3. Dynamic Tool Loading Load tools dynamically from a database or API:

   protected function getTools(): array
   {
       return Cache::remember('quality-tools', now()->addHours(1), function () {
           return Tool::where('enabled', true)->pluck('command', 'name')->toArray();
       });
   }
   

Configuration Quirks

1. Environment-Specific Tools Use environment variables to toggle tools:

   'phpstan' => [
       'command' => env('RUN_PHPSTAN', false) ? 'phpstan analyse' : null,
   ],
   

2. Tool Chaining Chain tools to pass output between them (e.g., phpunit → phpstan):

   'phpunit' => [
       'command' => 'phpunit --testdox-html=tests/coverage.html',
       'output_file' => 'tests/coverage.html',
   ],
   'phpstan' => [
       'command' => 'phpstan analyse --coverage tests/coverage.html',
   ],
   

3. Silent Mode Suppress output for CI/CD:

   php artisan php-quality-tools:check --quiet