Mago Laravel Package

Product Decisions This Supports

• Engineering velocity vs. quality trade-off: Mago bundles linting (code-smell detection), static analysis (undefined classes, type errors, union/array index bugs), formatting, and auto-fixes into a single Rust-powered binary. A PM can justify a "quality gate" initiative (CI enforcement + pre-commit hooks) without asking for new headcount — the tool does work that currently consumes reviewer time.
• Build vs. buy on internal tooling: The alternative is stitching together PHPStan + Psalm + PHP-CS-Fixer + PHP_CodeSniffer (four configs, four CI steps, four upgrade paths). Given 3.5k stars, active releases (1.6.0 → 1.9.1 cadence within weeks), Apache-2.0/MIT dual license, and named sponsorship from CHECK24 and JetBrains, "buy/adopt" is defensible over in-house tooling or glue-script maintenance.
• Roadmap investment in codebase health: Mago's analyzer is the product lever — issues like non-existent-class-like detection in @var docblocks, generic type parameter preservation on instanceof narrowing, and false-positive elimination on sealed/unsealed array unions translate directly into fewer runtime surprises after refactors. A PM can sequence "legacy module modernization" behind analyzer adoption as a prerequisite gate.
• Architecture/design policy enforcement as configuration: Opt-in checks (enforce-class-finality, require-api-or-internal, single-class-per-file, file-name) let a PM convert unwritten team conventions into CI-enforced policy without a written style guide that nobody reads.
• Monolith/Laravel upgrade risk reduction: Path-scoped ignores ({ code = "missing-return-type", in = "tests/" }) and per-rule exclusions (exclude = ["src/Legacy/"]) allow incremental adoption — enforce strictness on new code (src/) while grandfathering app/Legacy/ or tests/. This is the difference between a rollout that ships and one that stalls on 4,000 pre-existing violations.
• Technical debt quantification: code-count reporting with severity levels gives a PM a metric for a dashboard — "violations trending from X to Y over the quarter" — which is otherwise hard to source for "quality" workstreams.
• Onboarding and DX as a product surface: Sub-second lint/format cycles (Rust vs. PHP-interpreted tooling) and automatic fixes shorten the inner dev loop; a PM can attach this to "time-to-first-PR" onboarding metrics.

When to Consider This Package

Adopt when:

• You run a Laravel/PHP codebase with multiple contributors and CI, and currently have partial or no static analysis coverage.
• Static analysis runtime is a bottleneck — PHPStan/Psalm runs that take minutes on large monorepos, or are skipped locally because they're slow.
• You want one config surface (mago.toml) rather than four, to reduce the "which tool flagged this?" support load.
• You need incremental adoption — brownfield codebases where path-scoped ignores let you gate new src/ code first.
• You have typed/docblock-heavy code already (Psalm/PHPStan annotations), where Mago's @psalm-mutation-free interop and type-alias resolution reduce migration friction.
• You need design-intent enforcement (finality, @api/@internal) as an organizational policy, not just a style preference.

Look elsewhere or defer when:

• The tool is the runtime path — this is dev-only tooling, not production instrumentation; don't pitch it against observability or APM.
• You depend on PHPStan/Psalm custom rules or extensions — bespoke rule sets and Larastan's Laravel-specific type extensions are a real migration cost. Mago's Laravel-specific coverage deserves a proof-of-concept, not an assumption.
• You need hard SLAs, vendor support contracts, or a single-license commercial relationship (it's community-driven, dual-licensed OSS).
• Your team is on constrained Windows CI — the documented primary install path is a shell script for macOS/Linux; Composer install exists but the fast path is Unix-first.
• Your org bans post-1.0-but-young tooling in CI — pre-2.0 versioning means analyzer behavior can shift between minors (e.g., 1.6.0 removed deprecated linter rules in favor of the analyzer); pinning is mandatory.
• Zero dependents listed on the package registry means you won't find a large body of community migration write-ups — budget for internal ramp-up.

How to Pitch It (Stakeholders)

For executives: Mago is a single, fast, open-source (Apache-2.0) PHP quality toolchain — linter, formatter, and static analyzer — that replaces three to four overlapping tools in our CI. It cuts analysis time materially (Rust core vs. PHP-implemented tooling), converts our style and design conventions into enforced policy, and gives us a quantifiable code-health metric. Zero license cost, no vendor lock-in, adoptable incrementally behind path scoping so the migration is not a big-bang rewrite. Risk is bounded: it's dev-only, never ships to production, and version-pinning makes adoption reversible.

For engineering leadership: The rollout is low-risk and staged. Phase 1 — install in CI and pre-commit, run in report-only mode, measure baseline violations. Phase 2 — enable auto-fixes and formatting on a scoped path. Phase 3 — enforce analyzer errors on new code, grandfathering legacy directories via path-scoped ignores. We protect existing PHPStan/Psalm custom rules by running in parallel until parity is demonstrated on our codebase. Config lives in one mago.toml under version control. Success metrics: CI analysis wall-time, violation count trend, reviewer time on style nits, and pre-existing-bug catch rate in refactor PRs.

For the team: Faster local feedback (format/lint in the editor loop rather than waiting on CI), automatic fixes for many lint issues so review comments stop being about formatting, deeper type analysis that catches real bugs (undefined classes, impossible unions, wrong array keys), and opt-in design checks if we want them. It's not a black box — --only flags, per-rule path exclusions, and severity-aware reporting mean we can tune it to us rather than the reverse.