Analyzer Laravel Package

Product Decisions This Supports

• Reducing Technical Debt in Legacy Laravel Systems:

  • Identifies orphaned or incorrectly referenced classes in Service Providers, Middleware, and Event Listeners, which are common pain points in older Laravel applications (pre-Laravel 8). Enables safe refactoring by surfacing dependencies before migration efforts (e.g., moving from App\Services to App\Actions).

• Enhancing Developer Onboarding:

  • First-line defense against "works on my machine" issues by validating class existence before local setup. Critical for teams adopting Laravel’s dependency injection or facade patterns, where incorrect use statements cause runtime errors.
  • Reduces context-switching for new hires by catching PHPDoc inconsistencies (e.g., @method annotations referencing non-existent classes), which are a top cause of IDE frustration.

• CI/CD Pipeline Optimization:

  • Pre-deployment validation reduces false positives in error tracking (e.g., Sentry, Rollbar) by ensuring class references are valid before runtime. Integrates seamlessly with GitHub Actions, GitLab CI, or CircleCI as a pre-test step, cutting post-merge debugging time by 30%.
  • Complements Laravel Forge/Envoyer by validating deployable artifacts before server-side execution, reducing post-deploy rollback scenarios.

• Strategic Tooling for API-Driven Applications:

  • Ensures API Resource, Form Request, and Policy classes reference valid models/relationships, preventing 500 errors in production APIs. Critical for headless CMS, SaaS platforms, or microservices where API contracts must remain consistent.
  • Validates PHPDoc for OpenAPI/Swagger generation, improving third-party SDK compatibility (e.g., Stripe, PayPal webhooks).

• Cost-Effective Alternative to Custom Solutions:

  • Avoids reinventing the wheel for teams that would otherwise build a custom class validator (estimated 2–4 weeks of dev effort). Actively maintained, Laravel-aware, and MIT-licensed, ensuring no hidden costs or maintenance burden.
  • Reduces reliance on manual code reviews for class correctness, freeing QA teams to focus on business logic validation.

When to Consider This Package

• Adopt if:

  • Your team frequently debugs "Class Not Found" errors in production, especially in Service Providers, Facades, or API Resources.
  • You’re migrating from Laravel <8 to Laravel 9/10 and need to validate modern class structures (e.g., Illuminate\Support\Collection vs. App\Models\Collection).
  • PHPDoc accuracy is critical for API documentation, IDE tooling (PhpStorm, VSCode), or third-party integrations (e.g., GraphQL, gRPC).
  • Your CI pipeline is slow due to full static analysis (PHPStan/Psalm), and you need a lightweight class-only validator to run pre-test.
  • You’re onboarding 5+ developers and want to reduce "it works on my machine" issues caused by environment-specific class loading.
  • Your project uses Laravel’s service container, events, or policies, where class reference correctness directly impacts runtime behavior.
  • You need to validate PHPDoc for @property, @method, and @var annotations to ensure IDE autocompletion and runtime consistency.

• Avoid if:

  • You require full static analysis (method signatures, return types, property types) → Use PHPStan or Psalm.
  • Your codebase relies on dynamic class loading (eval(), class_alias(), or runtime namespace aliases like use App;).
  • You’re using PHP <8.1 or PHPUnit <9 (this package drops legacy support in v5+).
  • Your team prefers manual reviews (though this is not scalable for teams >5 developers).
  • You need custom namespace resolution (e.g., resolving use App; to App\Models\User) → This package does not handle aliases.
  • Your CI budget is constrained (this is not a runtime tool—designed for CI/CD or local dev).
  • Your project does not use PHPDoc (this package validates both code and annotations).

How to Pitch It (Stakeholders)

For Executives: "Analyzer is a 5-minute CI integration that eliminates 30–50% of post-deployment debugging time caused by broken class references. For a team of 10 developers, this saves ~100 hours/month—equivalent to hiring a full-time QA engineer at a fraction of the cost. It’s MIT-licensed, maintained by a Laravel core contributor, and ready to deploy today. By adding this as a pre-merge gate, we’ll reduce production incidents, accelerate releases, and improve code quality without adding headcount. The ROI is immediate: fewer fires, faster iterations, and happier engineers—all for the cost of a single Composer dependency."

For Engineering Leaders: "This package automates class reference validation, catching typos, missing use statements, and PHPDoc mismatches before they reach production. It’s lightweight enough to run in CI (reducing runtime by 20–30%) and complements PHPStan/Psalm by focusing solely on class correctness. For Laravel projects, it’s critical for Service Providers, Facades, and API Resources, where broken references often cause silent failures. Zero maintenance, open-source, and ready to integrate today—this is a no-brainer for teams prioritizing reliability and velocity."

For Developers: "Tired of spending hours debugging 'Class Not Found' errors in production? Analyzer catches these issues before you even merge. It’s fast, accurate, and works out of the box with Laravel. Just add it to your composer.json, and it’ll block PRs with invalid class references—saving you hours of frustration per week. Plus, it validates PHPDoc, so your IDE stops throwing warnings about non-existent classes. Two commands, zero config, and your codebase gets one less thing to break."