Mago Laravel Package

Technical Evaluation

Architecture fit

• Mago is not a runtime library and exposes no PHP API surface — it is a Rust-compiled CLI toolchain (linter, formatter, static analyzer) distributed through a thin Composer/Packagist shim. Integration effort is therefore concentrated in CI, pre-commit hooks, and composer.json scripts, not in application code. Zero risk of leaking into production request paths or vendor/ autoload graphs.
• For a Laravel codebase the natural substitution map is: formatter → Laravel Pint / PHP-CS-Fixer; linter → PHP_CodeSniffer; analyzer → PHPStan (via Larastan) / Psalm. Mago collapses three vendor relationships and three config surfaces into one mago.toml, which is the core architectural value proposition.
• The differentiator is performance: a single Rust binary with parallel parsing versus three PHP userland tools that each bootstrap the interpreter. For a mid-to-large Laravel monolith this is typically the difference between a 2–6 minute static-analysis job and a sub-30-second one, which changes whether analysis can run on every push and in the IDE loop rather than nightly.
• The critical architectural gap is Laravel semantic awareness. Larastan exists because Laravel is hostile to naive static analysis: Eloquent magic properties and query-builder dynamic returns, facade static proxies, container resolve()/app() typing, Blade and config magic strings, and macro-generated methods. Mago's type system is impressive (generics, sealed hierarchies, template inference, Psalm annotation interop) but ships PHP-standard prelude stubs, not Laravel stubs. Expect meaningful false positives on models, facades, and repositories until stubs or ignores are authored.

Integration feasibility

• Low-friction to start: install via pinned version, add mago lint, mago fmt, mago analyze to CI, run in report-only mode. No code changes, no dependency changes, no framework hooks.
• Configuration migration is not mechanical. phpstan.neon, pint.json, and phpcs.xml do not translate 1:1 into mago.toml; rule codes differ, severities differ, and the ignore model differs. Treat this as a scoped engineering task (rough order: days per repository, not hours), owned jointly by the TPM and the platform/DevEx engineer.
• Release 1.6.0's path-scoped ignores and per-rule exclusions materially improve feasibility for a Laravel repo, because generated and framework-owned paths (_ide_helper.php, bootstrap/cache, storage/framework, database/migrations in some shops, src/Generated/) can be carved out declaratively instead of with inline suppressions.
• Supply-chain reality check: the README's primary install path is curl … | bash. That is not acceptable for reproducible enterprise CI. Use the Composer package with an exact version constraint (or Homebrew/Cargo in a pinned toolchain image) and verify checksums.

Technical risk

• Analyzer parity risk (high). Replacing Larastan/PHPStan before proving parity on our own code is the single largest risk. Mitigation: run side-by-side with both tools emitting into the same CI job, and diff issue sets per directory.
• Semver discipline risk (medium-high). The changelog shows rules being removed across minor releases (1.6.0 removed five deprecated linter rules and flipped formatter defaults to PER-CS), plus a documented formatter setting removed in a patch. Minor upgrades can therefore change CI outcomes. Pin exact versions; upgrade deliberately; never use a floating constraint.
• Formatter divergence risk (medium). Mago's formatter is PER-CS-aligned, Pint defaults to Laravel's preset. A wholesale mago fmt will produce a large one-time diff and will likely disagree with Pint on some constructs. Sequence this as a single dedicated formatting commit, not mixed with feature work, and only after confirming the team accepts the style delta.
• Docs/versioning inconsistency (low, but a signal). The README advertises --version=1.47.3 while published release notes are 1.x (1.6.0, 1.9.1). Small, but it flags that release documentation is not fully regression-tested — factor into how much you trust unpinned upgrade paths.
• Adoption signal ambiguity (low). 3.5k stars with 0 Packagist dependents is consistent with a dev-tool that is installed as a binary rather than depended upon as a library — not necessarily a red flag, but it means we cannot infer ecosystem commitment from that number.
• Bus factor / governance (low-medium). Apache-2.0/MIT dual license is commercially safe and forkable, but the project is early and largely single-vendor (Carthage Software) with sponsor funding. A fork-and-maintain contingency is cheap given a Rust binary toolchain, but should be acknowledged.

Key questions

1. Does Mago provide Laravel-specific stubs or an official framework preset today, and if not, what is the effort to author stubs for our Eloquent models, facades, and custom macros?
2. Is there an incremental/cached analysis mode suitable for a monorepo and for pre-commit hooks on changed files only?
3. Is there a language server / editor integration and does it match our IDE fleet, or is this CI-only in practice?
4. What is the exit plan if formatter output diverges from Pint — can we run Mago for lint/analyze only and retain Pint for formatting during a transition period?
5. Does the Composer package pin a platform-specific binary and support our CI base image (glibc vs musl, ARM runners), and what are the checksum verification mechanics?

Integration Approach

Stack fit

• Fits as a dev-tooling layer, not an application dependency: require-dev (or a pinned toolchain container image), invoked via Composer scripts and CI steps. Nothing ships to production; no PHP version constraint interaction with Laravel's runtime.
• Best initial fit is mago lint + mago fmt on changed files in PR pipelines. mago analyze should enter as a non-blocking reporting job while the team measures false-positive rate against Larastan.
• Composer package name (carthage-software/mago) makes it discoverable and installable through the mechanism Laravel teams already trust, which reduces onboarding friction versus a bespoke install script.

Migration path

• Phase 0 — Evaluate (1–2 weeks): install pinned, run all three subcommands in report-only mode over the full repo, publish a metrics baseline (runtime, issue counts by code, false-positive sample on Eloquent/facade-heavy directories).
• Phase 1 — Lint and format enforcement: adopt the linter in CI blocking mode on changed files after fixing or path-scoping the initial backlog; land formatter adoption as one isolated mechanical commit with .git-blame-ignore-revs configured so history stays readable. Retain or retire Pint as an explicit decision, not by drift.
• Phase 2 — Analyzer shadow mode: run Mago analyze and Larastan in parallel, both non-blocking, and track convergence over sprint cycles. Author Laravel stubs and path-scoped ignores ({ code = "...", in = "tests/" }) to reach an acceptable noise floor.
• Phase 3 — Analyzer cutover: promote mago analyze to blocking on changed files with an agreed baseline/budget, and demote Larastan to a periodic full-repo job before eventual retirement.
• Sequencing rationale: each phase is independently revertible, and no phase requires deleting the incumbent tool before the successor is proven. The formatter is deliberately early because it is the lowest-semantic-risk, highest-perceived-speed win.

Compatibility

• Formatter: PER-CS alignment means a real style delta vs Laravel Pint. Decide explicitly — align Pint config as closely as possible beforehand, accept the remaining diff, or split responsibilities (Mago for lint/analyze, Pint for format) during transition.
• Analyzer: PHPStan/Psalm configs are not portable. Psalm annotation interop (@psalm-mutation-free, @psalm-api, @internal) is a positive signal for codebases already annotated, and the ability to consume existing docblocks lowers re-annotation cost.
• Version compatibility: pin an exact release; treat every minor bump as a change requiring CI validation (rule removals and default flips are documented behavior). Maintain a mago.toml review checklist in the upgrade PR template.
• Platform compatibility: verify binary availability for every runner architecture in use (x86_64 and ARM Linux, macOS for developer machines) before declaring CI parity.

Sequencing

1. Pin version + supply-chain hardening (checksums, no curl | bash in CI).
2. Baseline metrics capture and false-positive triage on the top 5 most-affected directories.
3. Linter adoption → formatter adoption → analyzer shadow → analyzer cutover.
4. Only after cutover: retire PHP_CodeSniffer / Pint configs and reduce PHPStan scope. Never retire an incumbent before the successor has one full release cycle of blocking CI behind it.

Operational Impact

Maintenance

• Ongoing cost is concentrated in three places: mago.toml ownership (a named owner, reviewed like code), the ignore/baseline discipline (ignores must be code-and-path scoped and periodically re-audited, or they become permanent debt), and upgrade validation on each release.
• Recurring upgrade ceremony is non-trivial: because minor releases can remove rules and flip defaults, budget a scheduled upgrade window (e.g., monthly) rather than opportunistic bumps. The changelog quality is genuinely good — detailed, credited, issue-linked — which materially lowers this cost.
• Formatter upgrades are the sneakiest maintenance item: a default change can produce repo-wide diffs on an unrelated PR. Mitigate with an isolated formatter job and a "formatting-only commit" convention enforced in review.

Support

• No vendor SLA. Support paths are GitHub issues, Discord, and the docs site. Acceptable for a dev tool; unacceptable as a hard CI gate without a documented internal fallback (pin-and-hold, or temporarily disable the blocking step).
• Internal support surface is small — a single binary, one config file — so the "who do I ask" question is answerable by the platform team rather than requiring a distributed ownership model. This is a real advantage over running three separate PHP tools with three config dialects.
• Dual-license MIT/Apache-2.0 removes legal review friction; no copyleft implications for a proprietary Laravel product.

Scaling

• Strong scaling characteristics: a compiled, parallel analyzer avoids the PHP-tool pattern of scaling CI cost linearly with codebase size times tool count. This is the argument that survives the procurement conversation — the same analysis coverage at a fraction of CI minutes, or deeper coverage at the same minutes.
• Path-scoped ignores and per-rule exclusions are the primary lever for large or polyglot repos (generated code, legacy modules, vendor-adjacent directories). Use them deliberately and document each entry with a reason.
• Monorepo scaling depends on incremental analysis on changed files, which should be the default CI mode regardless of tool — but verify Mago's caching/incrementality before assuming full-repo scans are affordable at our largest package.
• Team scaling: one shared config and one binary is easier to standardize across many Laravel services than per-service PHPStan baselines, making Mago a plausible platform standard rather than a per-team choice — the highest-leverage outcome for a TPM.

Failure modes

• False-positive flood on Eloquent/facade code → blocking CI, developer revolt, tool abandoned. Mitigation: shadow mode until noise floor is measured; Laravel stubs authored up front.
• Formatter mass-diff → unreviewable PR, lost blame history, merge conflicts across in-flight branches. Mitigation: single isolated commit, .git-blame-ignore-revs, coordinated freeze window.
• Silent rule removal / default flip on upgrade → CI goes green for the wrong reason, or red unexpectedly. Mitigation: pinned versions, upgrade PRs with explicit changelog review, CI diff of issue counts before/after.
• Binary unavailable or unverified on a runner → CI breaks on a platform-specific PR. Mitigation: pre-bake into the CI image, checksum verification, matrix-test on all runner architectures.
• Toolchain abandonment upstream → analysis coverage gap. Mitigation: keep PHPStan configs dormant-but-valid for one cycle post-cutover; the fork option is cheap.
• Install-script compromise → supply-chain incident. Mitigation: never curl | bash in CI; Composer with exact version and verified artifacts.

Ramp-up

• Developer ramp-up is low for fmt (invisible once configured) and linter fixes (fast, mechanical, often auto-fixable). Analyzer errors on Laravel idioms are the real learning curve — expect 1–2 sprints of "why is it complaining about my model" before instinct adjusts, plus a maintained internal FAQ of accepted suppressions.
• Platform/DevEx ramp-up is moderate: CI wiring, image baking, baseline management, and the Laravel stub authoring effort. This is the actual cost center of adoption and should be resourced explicitly rather than absorbed silently.
• Recommendation for the portfolio decision: adopt Mago now as an additive, pinned, non-blocking dev-tooling layer (formatter + linter first) for its clear CI-cost and consolidation upside; gate analyzer cutover — and any retirement of PHPStan/Larastan — on measured false-positive parity against our own Laravel codebase. The score of ~78 with opportunity at ~64 reflects a genuinely strong tool with an immature framework-integration story; buy the speed and consolidation now, buy the analyzer substitution only after evidence.