Code Quality Pack Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev setono/code-quality-pack
   

   Publish the package's configuration (if applicable):

   php artisan vendor:publish --provider="Setono\CodeQualityPack\CodeQualityPackServiceProvider"
   

2. First Use Case Run the default code quality checks via Artisan:

   php artisan code-quality:check
   

   This executes all configured tools (e.g., PHPStan, Psalm, PHPMD, etc.) in a single command.

3. Where to Look First

   • Configuration: Check config/code-quality-pack.php for tool-specific settings (e.g., PHPStan paths, Psalm levels).
   • Artisan Commands: Explore available commands in vendor/setono/code-quality-pack/src/Console/ (e.g., php artisan code-quality:phpstan).
   • Git Hooks: Integrate with Git via php artisan code-quality:install-git-hooks for pre-commit/pre-push checks.

Implementation Patterns

Workflows

1. CI/CD Integration

   • Use the package in GitHub Actions/GitLab CI:

     - name: Run Code Quality Checks
       run: php artisan code-quality:check --fail-on-error
     

   • Cache dependencies (e.g., PHPStan) between runs to speed up pipelines.

2. Custom Tool Integration Extend the package by creating a custom tool:

   // app/Providers/CodeQualityPackServiceProvider.php
   public function register()
   {
       $this->app->singleton(ToolInterface::class, function () {
           return new CustomTool();
       });
   }
   

3. Parallel Execution Run tools in parallel using Laravel’s process helper or parallel-lint:

   php artisan code-quality:phpstan --parallel &
   php artisan code-quality:psalm --parallel &
   

Integration Tips

• Laravel Mix/Webpack: Add code quality checks to postcss/webpack.mix.js for frontend checks (e.g., ESLint).
• IDE Support: Configure your IDE (PHPStorm/VSCode) to use the same rulesets as the package for real-time feedback.
• Custom Reports: Override the default reporter to format output for Slack/Teams:

  // config/code-quality-pack.php
  'reporter' => \Setono\CodeQualityPack\Reporters\SlackReporter::class,
  

Gotchas and Tips

Pitfalls

1. Configuration Conflicts

   • Ensure tool-specific configs (e.g., phpstan.neon) don’t conflict with the package’s defaults.
   • Fix: Use --config flag to override:

     php artisan code-quality:phpstan --config=custom/phpstan.neon
     

2. Performance Overhead

   • Running all tools on large codebases may slow down CI.
   • Fix: Use --tools to run specific tools:

     php artisan code-quality:check --tools=phpstan,psalm
     

3. Git Hooks Pitfalls

   • Hooks may fail silently if dependencies aren’t installed.
   • Fix: Add a pre-check in hooks:

     # .git/hooks/pre-commit
     composer install --no-dev || exit 1
     

Debugging

• Verbose Output: Use --verbose for detailed logs:

  php artisan code-quality:check --verbose
  

• Dry Runs: Test tool configs without failing:

  php artisan code-quality:phpstan --dry-run
  

Extension Points

1. Custom Rules Add tool-specific rules via config:

   // config/code-quality-pack.php
   'phpstan' => [
       'rules' => [
           'Setono\CodeQualityPack\Rules\CustomRule::class',
       ],
   ],
   

2. Event Listeners Listen for tool execution events:

   // app/Listeners/CodeQualityEventListener.php
   public function handle(ToolExecuted $event) {
       Log::info("Tool {$event->tool} completed with status {$event->status}");
   }
   

3. Dynamic Tool Loading Load tools dynamically based on environment:

   // config/code-quality-pack.php
   'tools' => env('CODE_QUALITY_TOOLS', 'phpstan,psalm,phpmd') === 'all' ? ['*'] : explode(',', env('CODE_QUALITY_TOOLS')),