Plugin Api Laravel Package

Technical Evaluation

Architecture Fit

• Modular Extensibility: The phpcq/plugin-api provides a plugin-driven architecture for PHP code quality, aligning with Laravel’s modular design (e.g., service providers, commands). This enables custom rule engines without monolithic tooling, ideal for Laravel-specific checks (e.g., Blade template validation, Eloquent query optimization).
• Laravel Integration Points:
  • Artisan Commands: Plugins can expose CLI tools (e.g., php artisan phpcq:check).
  • Event System: Trigger phpcq scans on file.updated or repository.pushed.
  • Service Container: Bind PluginInterface to Laravel’s DI system for dependency injection.
• Limitations:
  • Generic PHP Focus: No native Laravel abstractions (e.g., Eloquent, Blade), requiring custom adapters.
  • Maturity Risk: 0 stars/dependents suggest limited real-world validation (mitigate via pilot testing).

Integration Feasibility

• Low Coupling: Interfaces (PluginInterface, RuleInterface) decouple logic from Laravel, enabling reuse.
• Dependency Graph:
  • Direct: phpcq/plugin-api → phpcq/phpcq (core runner).
  • Indirect: Laravel can invoke phpcq via Process facade or Artisan.
• Key Classes:
  • PluginInterface: Define plugin entry points (e.g., run()).
  • RuleInterface: Implement custom checks (e.g., isViolation()).
  • ConfigurationInterface: Merge Laravel config with phpcq settings.

Technical Risk

Key Questions

1. Use Case Clarity:
   • Is this for developer workflows (e.g., pre-commit hooks) or CI/CD enforcement?
   • Should it replace existing tools (e.g., pint, phpstan) or complement them?
2. Configuration Strategy:
   • How to merge Laravel’s config/ with phpcq’s .phpcq.php without conflicts?
3. Execution Context:
   • Run phpcq as a Laravel command or standalone CLI tool?
4. Violation Handling:
   • How to surface phpcq findings to Laravel users (e.g., notifications, GitHub PR comments)?
5. Performance:
   • Will phpcq scans block Laravel’s HTTP requests? (Avoid runtime execution.)
6. Plugin Development:
   • Should Laravel provide a scaffold for phpcq plugins (e.g., php artisan phpcq:plugin)?

Integration Approach

Stack Fit

• Laravel Core:
  • Artisan: Wrap phpcq commands (e.g., php artisan phpcq:check).
  • Service Container: Bind phpcq interfaces to Laravel’s DI system.
  • Events: Trigger phpcq on file.updated or repository.pushed.
• Ecosystem:
  • CI/CD: Use phpcq as a pre-push hook in GitHub Actions/GitLab CI.
  • Deployments: Integrate with Laravel Forge/Envoyer for runtime checks.
• Alternatives Considered:
  • PHP-CS-Fixer: For code style (already Laravel-friendly).
  • Psalm/PHPStan: For static analysis (more mature in Laravel).
  • Custom Rules: Roll your own if phpcq’s plugin system is overkill.

Migration Path

1. Phase 1: Standalone Integration (1–2 days)

   • Install phpcq/plugin-api and phpcq/phpcq as dev dependencies.
   • Create a custom Artisan command to execute phpcq:

     // app/Console/Commands/RunPhpcq.php
     public function handle() {
         $process = new Process(['phpcq', 'run']);
         $process->run();
         $this->output->write($process->getOutput());
     }
     

   • Register in app/Console/Kernel.php.

2. Phase 2: Configuration Layer (3–5 days)

   • Publish phpcq’s config to config/phpcq.php:

     php artisan vendor:publish --provider="Phpcq\ServiceProvider"
     

   • Override defaults in Laravel’s config:

     // config/phpcq.php
     return [
         'rules' => [
             'laravel_magic_methods' => ['enabled' => true],
         ],
     ];
     

3. Phase 3: Plugin Development (1–2 weeks)

   • Scaffold a Laravel-specific plugin:

     php artisan make:phpcq-plugin LaravelMagicMethodsCheck
     

   • Implement RuleInterface and bind to Laravel’s container.

4. Phase 4: Advanced Integration (Ongoing)

   • Integrate with Laravel notifications (e.g., Slack alerts for violations).
   • Cache results to avoid redundant scans.

Compatibility

Sequencing

1. Proof of Concept (1–2 days)
   • Install phpcq and test standalone execution via Artisan.
   • Validate configuration merging.
2. Basic Integration (3–5 days)
   • Build a custom command and publish config.
   • Add CI checks (fail build on phpcq violations).
3. Plugin Development (1–2 weeks)
   • Develop Laravel-specific plugins (e.g., Blade template rules).
   • Integrate with notifications.
4. Optimization (Ongoing)
   • Cache phpcq results.
   • Parallelize checks in CI.

Operational Impact

Maintenance

• Dependency Updates:
  • Pin versions in composer.json to avoid surprises:

    "require-dev": {
        "phpcq/plugin-api": "^1.0",
        "phpcq/phpcq": "^2.0"
    }
    

  • Monitor phpcq for breaking changes (low risk due to interface stability).
• Configuration Drift:
  • Use Laravel’s config:clear to reset phpcq settings.
  • Document overrides in README.md.
• Plugin Lifecycle:
  • Deprecate custom plugins via Laravel’s package:discover system.

Support

• Debugging Workflow:
  • Log phpcq output to Laravel’s storage/logs/phpcq.log.
  • Use telescope to track plugin execution times.
• Error Handling:
  • Catch ProcessFailedException in Artisan commands.
  • Surface phpcq errors as Laravel exceptions or notifications.
• Community Resources:
  • Limited upstream support (new project). Rely on:
    • GitHub Issues in phpcq/plugin-api.
    • Laravel Discord/Forums for integration help.

Scaling

• Performance:
  • Runtime: Avoid running phpcq in HTTP requests (use queues or CI).
  • CI: Parallelize checks with phpcq --parallel.
  • Caching: Cache results for config('phpcq.cache_ttl', 3600) seconds.
• Plugin Scalability:
  • Use Laravel’s Queue system to process violations asynchronously:

    Violation::dispatch($violation)->onQueue('phpcq-violations');
    

• Team Adoption:
  • Onboard via php artisan phpcq:docs (custom command to generate docs).
  • Provide a phpcq:status command to check compliance.

Failure Modes