Repository Definition Laravel Package

Product Decisions This Supports

• Standardization of Code Quality in Laravel Ecosystems: Enables consistent enforcement of PHP code quality rules (e.g., PSR-12, security checks) across monorepos, multi-repo setups, or legacy Laravel projects. Reduces fragmentation from ad-hoc tooling (e.g., standalone PHP_CodeSniffer configs).
• CI/CD Pipeline Optimization: Aligns with roadmap goals to automate quality gates in GitHub Actions/GitLab CI, blocking low-quality PRs before merge. Integrates with Laravel’s existing CI workflows (e.g., phpunit, pint) without reinventing the wheel.
• Build vs. Buy: A cost-effective alternative to proprietary tools (e.g., SonarQube) or over-engineered solutions. Leverages open-source tools (PHP_CodeSniffer, PHPMD) with a lightweight abstraction layer.
• Use Cases:
  • Onboarding New Repositories: Standardize quality checks for new Laravel projects via a shared phpcq.yml template.
  • Legacy Code Refactoring: Audit technical debt in older Laravel apps (e.g., pre-5.0) with consistent rules.
  • Security Compliance: Enforce PHP-specific security rules (e.g., SQL injection patterns, dependency vulnerabilities) in CI.
  • Team Alignment: Replace subjective code reviews with objective, automated checks (e.g., "No hardcoded configs in Laravel apps").

When to Consider This Package

• Adopt When:

  • Your Laravel project lacks a centralized code quality toolchain and relies on manual reviews or disparate tools.
  • You need lightweight, PHP-native static analysis without the overhead of full platforms (e.g., SonarQube).
  • Integrating with existing tools (PHP_CodeSniffer, PHPMD) is a priority, and you want to avoid reinventing configuration.
  • You’re managing multiple Laravel repositories and want to enforce consistent quality rules across them.
  • Budget constraints or open-source preferences rule out commercial tools, but you still need automation.
  • Your team is early in the Laravel adoption curve and needs a scalable way to enforce best practices (e.g., PSR-12, dependency management).

• Look Elsewhere If:

  • You require advanced dynamic analysis (e.g., runtime behavior, performance profiling) → Use PHPStan, Psalm, or Xdebug-based tools.
  • Your team needs real-time IDE integration (e.g., VS Code plugins for PHP) → Explore PHP Intelephense, PHPMD IDE plugins, or Laravel-specific extensions.
  • You’re already using a full-fledged platform (e.g., SonarQube, Snyk) and need deeper reporting/analytics or SAST features.
  • The project’s maturity is a risk (currently 0 stars, no dependents), and you lack resources to fork/maintain it.
  • Your Laravel project is highly customized (e.g., heavy use of dynamic facades, custom macros) and PHPCQ’s static rules may not cover edge cases.

How to Pitch It (Stakeholders)

For Executives: *"This package lets us automate Laravel code quality—like a spell-check for our PHP—directly in our CI pipeline. It’s free, open-source, and integrates with tools we already use (e.g., PHP_CodeSniffer). By catching issues early—like style violations, security risks, or technical debt—we’ll:

• Reduce bugs in production by enforcing standards before code is merged.
• Speed up PR reviews with fewer manual checks.
• Save costs by avoiding proprietary tools like SonarQube. Think of it as a quality gate for every Laravel PR, with minimal overhead. It’s especially valuable if we’re managing multiple repos or legacy codebases."*

For Engineering: *"This gives us a standardized, maintainable way to enforce code quality across all Laravel projects. It’s a thin wrapper around proven tools (PHP_CodeSniffer, PHPMD) but adds structure for:

• Repo-specific rules: E.g., ‘No hardcoded database configs in this app’ or ‘All Blade templates must use @props’.
• CI-friendly integration: Fail builds if checks exceed thresholds (e.g., critical PHPMD violations).
• Scalability: Works for monorepos or multi-repo setups with a shared phpcq.yml template. The tradeoff? It’s not as feature-rich as SonarQube, but it’s lightweight, PHP-native, and avoids vendor lock-in. We’d need to:

1. Define a Laravel-specific schema extension (e.g., for Blade/Eloquent rules).
2. Build a wrapper package (e.g., phpcq/laravel) for Artisan commands and service container integration.
3. Pilot it in one repo before rolling out widely. If we’re already using pint or phpstan, we’ll need to coordinate tooling to avoid duplication."*