Phpinsights Laravel Package

Product Decisions This Supports

• Code Quality Enforcement: Justify adoption of a build-time static analysis tool to enforce coding standards, reducing technical debt and improving maintainability. Aligns with initiatives to shift left on quality checks.
• Developer Experience (DX) Improvements: Pitch as a self-service tool for developers to catch issues early, reducing manual code reviews and onboarding friction.
• Framework-Specific Standards: Tailor Laravel/Symfony/Yii presets to enforce team-specific conventions (e.g., disallowing dd() in production code).
• CI/CD Integration: Propose as a gated check in PR pipelines to block non-compliant code, reducing merge conflicts and rework.
• Onboarding Acceleration: Use as a checklist for new hires to understand project standards (e.g., "Your PR failed because of LineLengthSniff—here’s how to fix it").
• Refactoring Roadmap: Identify high-complexity modules (via cyclomatic complexity metrics) to prioritize in refactoring sprints.
• Open-Source Contributions: Leverage the extensible insight system to add custom checks (e.g., "No final classes in our monorepo").
• Cost Avoidance: Replace manual audits (e.g., by senior devs) with automated checks, freeing time for strategic work.

When to Consider This Package

• Avoid if:
  • Your team lacks consensus on coding standards (tool will enforce opinions).
  • You’re using non-PHP languages (focuses solely on PHP/Laravel/Symfony).
  • Your project is small/early-stage (overhead may not justify benefits).
  • You already have a dedicated QA team performing manual reviews.
  • Your CI/CD pipeline cannot handle CLI tools (requires terminal access).
• Look elsewhere if:
  • You need runtime performance analysis (use Xdebug or Blackfire).
  • You require deep architectural reviews (consider SonarQube or custom tooling).
  • Your team resists automated enforcement (may need cultural buy-in first).
  • You’re using PHP 7.0 or below (requires PHP 7.4+).
• Consider when:
  • You’re scaling a team (reduces knowledge silos).
  • You’re migrating legacy code (identifies technical debt).
  • You need framework-specific insights (e.g., Laravel’s ForbiddenPrivateMethods).
  • You want IDE integration (clickable terminal links to fix issues).

How to Pitch It (Stakeholders)

For Executives:

"PHP Insights is a self-healing code quality assistant that catches bugs, style issues, and architectural problems before they reach production. Think of it as a linter for your entire codebase—like ESLint for JavaScript, but for PHP/Laravel. It integrates seamlessly into our workflow, reducing rework costs by automating 80% of manual code reviews. For example, it can block PRs with dd() calls in production code or flag overly complex classes that slow down development. The ROI? Fewer bugs, faster onboarding, and happier devs—all for the cost of a single composer require."

Key Metrics to Track:

• % of PRs blocked by PHP Insights (goal: >50% of style/architectural issues caught early).
• Time saved in code reviews (pre/post-adoption).
• Reduction in production incidents linked to code quality.

For Engineering Leaders:

*"This is a developer productivity multiplier. PHP Insights gives our team:

1. Actionable feedback: Terminal output with direct links to fix issues (works in VSCode/PhpStorm).
2. Framework-aware checks: Laravel-specific rules (e.g., no private methods in service containers) that align with our architecture.
3. Extensibility: We can add custom rules (e.g., ‘No str_replace in business logic’) without reinventing the wheel.
4. CI/CD guardrails: Fail builds on violations, so we never merge broken code.

Implementation Plan:

• Phase 1: Run locally for self-service fixes (devs opt in).
• Phase 2: Add to PR templates as a required check.
• Phase 3: Integrate with SonarQube for enterprise-grade reporting.

Trade-offs:

• Initial setup (~1 hour to configure phpinsights.php).
• False positives may require tuning (but we can start with defaults and iterate)."*

For Developers:

*"This is like GitHub Copilot for code quality—it tells you exactly what’s wrong and how to fix it, without you having to read a 50-page style guide. Here’s how it helps you:

• No more ‘nitpicky’ PR comments: It flags LineLengthSniff or UnusedParameter issues automatically.
• Laravel-specific rules: Know instantly if you’re using dd() in a controller or violating our service-layer conventions.
• One-click fixes: Terminal links take you directly to the problematic line in your IDE.
• Customizable: Want to ban foreach loops in our codebase? We can add it in 5 minutes.

How to Use:

1. Install: composer require nunomaduro/phpinsights --dev
2. Run: ./vendor/bin/phpinsights (or php artisan insights for Laravel).
3. Fix the red stuff—it’s your new best friend.

Pro Tip: Add it to your package.json scripts so you can run npm run check:php alongside your frontend linters!"*