Repository Definition Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package provides a standardized repository definition schema for PHP code quality automation, aligning well with Laravel’s need for consistent, scalable static analysis across repositories. It bridges the gap between ad-hoc tooling (e.g., PHP_CodeSniffer, PHPMD) and Laravel’s CI/CD pipelines, particularly for:
  • Monorepo/multi-repo setups where uniform quality checks are critical.
  • CI/CD gatekeeping (e.g., blocking PRs with violations).
  • Onboarding new repositories with predefined rules.
• Laravel-Specific Synergies:
  • Leverages Laravel’s service container to dynamically load PHPCQ configurations (e.g., via a custom PhpcqServiceProvider).
  • Complements Laravel’s Artisan CLI by enabling custom commands (e.g., php artisan phpcq:check).
  • Integrates with Laravel Forge/Vapor for infrastructure-level quality enforcement.
• Misalignment Risks:
  • Overlap with Laravel Tools: Conflicts may arise with laravel-pint, phpstan, or pestphp if not carefully scoped (e.g., PHPCQ for static analysis, Laravel tools for formatting/testing).
  • Lack of Laravel-Specific Rules: No built-in support for Blade templates, Eloquent queries, or Laravel conventions (e.g., App\Services\ namespace).

Integration Feasibility

• Core Integration Points:
  • Repository Definition Schema: Use PHPCQ’s YAML/JSON schema to define:
    • Tooling: PHP_CodeSniffer, PHPMD, or custom sniffs.
    • Rules: PSR-12, security checks, or Laravel-specific constraints.
    • Thresholds: Fail builds if violations exceed limits.
  • Laravel Abstractions:
    • Service Provider: Register PHPCQ as a Laravel service to inject configurations.
    • Artisan Commands: Expose PHPCQ checks via CLI (e.g., phpcq:run).
    • Event Listeners: Trigger PHPCQ on repo:clone or pr:opened.
  • CI/CD Plugins: Wrap PHPCQ in GitHub Actions/GitLab CI templates for seamless pipeline integration.
• Technical Debt:
  • No Laravel Plugins: Requires building adapters (e.g., a phpcq/laravel package) for tight integration.
  • Schema Extensibility: May need to fork or extend the schema to support Laravel-specific fields (e.g., blade_sniffs).
  • Tooling Coordination: Define clear boundaries (e.g., PHPCQ for static analysis, phpstan for type checking).

Technical Risk

Key Questions

1. Strategic Fit:
   • Does the project need centralized code quality definitions, or are existing tools (e.g., phpstan, pint) sufficient?
   • Would PHPCQ reduce tooling duplication across repositories, or add complexity?
2. Laravel-Specific Gaps:
   • Are there Laravel-specific rules (e.g., Blade syntax, Eloquent patterns) missing from PHPCQ?
   • How would PHPCQ integrate with Laravel’s testing tools (e.g., PestPHP, PHPUnit)?
3. Operational Overhead:
   • What’s the break-even point for adopting PHPCQ (e.g., time saved vs. setup cost)?
   • How would PHPCQ scale with 100+ repositories?
4. Alternatives:
   • Could custom GitHub/GitLab templates or existing Laravel packages (e.g., nunomaduro/collision) achieve similar goals with less friction?
5. Long-Term Viability:
   • Is the PHPCQ project actively maintained? If not, is the team willing to fork and maintain it?
6. Tooling Coordination:
   • How will PHPCQ coexist with phpstan/pint without redundancy?
   • Should PHPCQ replace or complement existing tools?

Integration Approach

Stack Fit

• Laravel Ecosystem Compatibility:
  • Pros:
    • PHPCQ’s YAML/JSON schema integrates with Laravel’s spatie/fork or symfony/yaml for parsing.
    • Service Container: PHPCQ configs can be injected as Laravel services.
    • Artisan CLI: Custom commands (e.g., phpcq:check) can be built.
    • CI/CD: Works with GitHub Actions, GitLab CI, or Laravel Forge.
  • Cons:
    • No native Laravel plugins: Requires custom wrappers (e.g., phpcq/laravel package).
    • Potential conflicts: Overlap with phpstan, pint, or psalm if not scoped.
    • Database/ORM: PHPCQ is file-system/CLI-focused; no direct integration with Eloquent.
• Tooling Synergies:
  • PHP_CodeSniffer/PHPMD: PHPCQ orchestrates these tools; Laravel can extend their rules.
  • Laravel Mix/Vite: PHPCQ could validate frontend checks (if extended to support JS/TS).
  • Custom Sniffs: Laravel-specific rules (e.g., for Blade templates) can be added.

Migration Path

1. Phase 1: Discovery (2 weeks)

   • Audit: Inventory existing code quality tools (PHP_CodeSniffer, PHPMD, etc.).
   • Define Rules: Identify non-negotiable standards (e.g., PSR-12, security checks).
   • Prototype: Create a minimal phpcq.yml for one repository and test locally.

     repositories:
       - path: .
         tools:
           - phpcs
           - phpmd
         rules:
           - "PSR12"
           - "NoHardcodedConfigs"
     

   • CI/CD Spike: Integrate PHPCQ into a GitHub Actions/GitLab CI workflow.

2. Phase 2: Pilot (4 weeks)

   • Single-Repo Rollout: Deploy PHPCQ in one repository with CI/CD integration.
   • Feedback Loop: Gather input on false positives/negatives and adjust rules.
   • Laravel Extensions: Add custom sniffs for Laravel-specific concerns (e.g., Blade syntax).
   • Documentation: Draft a phpcq.yml template for the team.

3. Phase 3: Standardization (6 weeks)

   • Template Repository: Create a boilerplate repo with PHPCQ configs for onboarding.
   • Team Training: Conduct workshops on PHPCQ usage and Laravel-specific rules.
   • Tooling Deprecation: Phase out legacy tools (e.g., standalone PHP_CodeSniffer configs) where PHPCQ provides better coverage.
   • Laravel Wrapper: Develop a phpcq/laravel package to:
     • Provide Artisan commands (php artisan phpcq:check).
     • Integrate with Laravel’s event system (e.g., trigger on repo:clone).

4. Phase 4: Optimization (Ongoing)

   • Performance Tuning: Cache results, parallelize checks, or use selective validation.
   • Schema Extensions: Add Laravel-specific fields (e.g., blade_sniffs, eloquent_rules).
   • Monitoring: Track PHPCQ’s impact on build times and code quality metrics.

Compatibility