Phpquality Bundle Laravel Package

Product Decisions This Supports

• Code Quality as a First-Class Feature: Integrate static analysis into the development lifecycle to enforce maintainability standards, reducing technical debt and improving onboarding.
• Architecture Enforcement: Adopt Clean Architecture principles (e.g., layer dependency rules) to standardize project structure and reduce coupling, aligning with long-term scalability goals.
• Build vs. Buy: Replace manual code reviews or legacy tools (e.g., unmaintained phpmetrics) with an automated, framework-aware solution to save engineering time.
• CI/CD Pipeline Enhancement: Fail builds on quality violations (e.g., high complexity, SOLID violations) to shift left on code quality, reducing production defects.
• Developer Productivity: Provide actionable insights (e.g., Hall of Fame/Shame, per-author metrics) to incentivize quality contributions and identify mentorship opportunities.
• Onboarding Acceleration: Generate baseline reports for new hires to contextualize legacy codebases, reducing ramp-up time.
• Compliance/Standards: Enforce team-wide coding standards (e.g., MI scores, CCN thresholds) to align with organizational best practices.

When to Consider This Package

• Avoid if:
  • Your team lacks PHP/Symfony expertise to interpret reports or configure rules (e.g., startups with non-technical stakeholders).
  • You need real-time analysis (this is a batch tool; pair with IDE plugins like PHPStan for live feedback).
  • Your project is small (<5K LOC) or monolithic (layer violations may not apply).
  • You require custom metrics beyond SOLID/architecture (e.g., security-focused analysis; use tools like Psalm or SonarQube instead).
  • Your stack is non-PHP (e.g., JavaScript, Go) or uses non-Symfony frameworks (e.g., Yii, Zend).
• Consider alternatives if:
  • You need enterprise-grade features (e.g., SonarQube for large-scale teams).
  • Your CI environment lacks Docker/Symfony (use the CLI bundle directly).
  • You prioritize performance over depth (e.g., phpstan/extension-installer for lightweight checks).
  • Your project uses legacy PHP (<7.4) (requires PHP 8.3).

How to Pitch It (Stakeholders)

For Executives: "This tool automates code quality enforcement, reducing bugs and maintenance costs by 30%+ (based on industry benchmarks). It acts like a ‘linter for architecture,’ catching design flaws early—similar to how spellcheck improves writing. For example, it can flag when a developer accidentally couples business logic to a database layer, which we’ve seen cause critical outages in [Project X]. By integrating this into our CI pipeline, we’ll fail builds on technical debt, saving $Y annually in fire-drills. It’s a low-lift way to professionalize our codebase, with reports that even non-technical leaders can understand."

For Engineering: *"PhpQuality replaces manual code reviews for architecture and complexity with actionable data. Key benefits:

• Framework-aware: Understands Laravel/Symfony patterns (e.g., ignores ServiceProvider in DIP checks) to reduce false positives.
• CI-friendly: Fail builds on violations (e.g., CCN > 10) or generate baselines to grandfather in legacy code.
• Developer insights: Hall of Fame/Shame reports show who needs mentoring, and per-author metrics tie quality to performance reviews.
• Zero config for 80% use cases: Auto-detects project type (Laravel/Symfony) and layers; customize via phpquality.json. Example workflow: Add it to your CI, run php bin/console phpquality:analyze, and start failing on solid.dip violations. The HTML report gives a dashboard with trends over time—great for retrospectives."*

For PMs: *"This tool lets us enforce quality gates without slowing down velocity. Use cases:

1. Pre-release: Run in CI to block merges with high complexity or layer violations.
2. Onboarding: Generate a ‘code health’ report for new hires to explain legacy quirks.
3. Tech debt tracking: Baseline current violations, then measure progress quarterly.
4. Vendor evaluation: Audit third-party PHP libraries for maintainability risks. Tradeoff: It’s not a silver bullet—pair it with PHPStan for type safety and SonarQube for security. But for architecture and metrics, it’s the most developer-friendly option I’ve seen."*