Laravel Self Test Laravel Package

Technical Evaluation

Architecture fit

• Microscope is a dev-only static analysis tool for Laravel applications, not a runtime library. It inspects the application's own source tree via Artisan commands (check:all, check:imports, check:views, check:routes, check:early_returns, check:dead_controllers, check:blade_...) and reports structural defects that PHP's type system and Pint/PHPStan do not catch: missing or unused imports, wrong namespaces, PSR-4 mismatches, unused Blade views, route/controller drift, empty or dead methods.
• Architectural footprint is deliberately shallow: a service provider registered through package discovery, no database, no queue, no config publishing required for baseline use. It reads files and emits console output plus an optional fix mode. This makes it a peer of Pint and PHPStan in the "local + CI quality gate" layer rather than a component of the application's runtime architecture.
• Best fit is a Laravel monolith or a large modular Laravel codebase where the dominant failure mode is structural entropy during refactors — renamed namespaces, orphaned views, controllers that no longer resolve. It is a poor fit for small services (<20k LOC) where the defect classes it detects are rare and the signal-to-noise ratio degrades.

Integration feasibility

• Low integration cost: composer require --dev imanghafoori/laravel-self-test, run php artisan check:all, wire into CI. Realistic effort is 1–3 engineer-days for a first pass, dominated by triaging the initial finding set rather than by setup.
• Complements rather than replaces the existing toolchain. Pint handles formatting, PHPStan/Larastan handles type and flow analysis, Microscope handles Laravel-specific structural hygiene. Overlap is partial (unused imports) and can be de-duplicated by disabling the redundant check.
• Requires a decision on the fix mode (--fix). Bulk auto-fixing imports/namespaces on a mature codebase is a high-risk operation and must be gated behind a single dedicated PR with full test-suite validation, never run opportunistically in CI.

Technical risk

• Maintainer concentration. Single-author package with a long release history but no bus-factor buffer. A stalled release cycle that lags a new Laravel major is a live risk. Mitigation: it is a dev dependency — removal is a one-line revert, not a migration.
• Identity/naming ambiguity. The distribution name (imanghafoori/laravel-self-test) does not match the repository name (laravel-microscope). Confirm which Packagist name maps to which codebase, verify the tagged release SHA against the repo, and pin to an exact tag. Do not accept ^ ranges.
• Adoption signal is weak. "Dependents: 0" alongside ~1.5k stars suggests stars are not converting to installs, or that the metric is measuring the wrong package name. Either interpretation argues for a pilot before any org-wide mandate.
• False positives as a cultural risk. Static checkers that flag "dead code" or "unused views" are frequently wrong in Laravel (dynamic view resolution, container-resolved controllers, string-based route actions). A noisy first run that produces 400 findings will burn credibility with the team faster than the tool can earn it.
• Opportunity score of 0.38 is consistent with a crowded category (Pint, PHPStan, Rector, Larastan, Blade linters). Position this as a gap-filler for Laravel-structural checks, not as a category-defining bet.

Key questions

1. Does check:all return a non-zero exit code on findings, and is that behavior stable and documented? CI gating is impossible without it.
2. What is the supported Laravel/PHP version matrix, and how quickly has the maintainer historically shipped compatibility for new Laravel majors?
3. Can individual checks be disabled or scoped (paths, namespaces, --except) so we can start with a narrow, high-precision subset?
4. Which specific checks produce false positives on our codebase's patterns — dynamic Blade includes, invokable/container-resolved controllers, package-discovered service providers?
5. Is --fix idempotent and does it produce deterministic diffs suitable for code review?
6. What is the real install footprint and are there transitive dependency conflicts with our existing dev toolchain (PHPStan version, Symfony console)?

Integration Approach

Stack fit

• Target: Laravel 10/11/12 applications on PHP 8.1+, Composer 2, Git-based CI (GitHub Actions/GitLab CI). No infrastructure prerequisites, no secrets, no external service.
• Sits in the "local pre-push + PR gate" tier. Local: optional pre-commit hook or a composer check script. CI: a dedicated non-blocking job in phase 1, blocking in phase 2.
• Explicitly out of scope: production runtime, staging, deployment pipelines.

Migration path

• No data migration, no schema change, no API surface change. The "migration" is a workflow change: introducing a new PR gate.
• Phase 0 — evaluate: run check:all read-only on a branch, no CI wiring. Capture the full finding set as a baseline artifact.
• Phase 1 — triage: classify findings into true-positive (fix now), false-positive (suppress via config/flags), and deferred (add to a tracked backlog with counts). Produce a per-check precision number.
• Phase 2 — adopt: enable only checks with acceptable precision, wire into CI as a blocking job on changed paths.
• Phase 3 — expand: enable --fix in a single scoped, human-reviewed PR series; widen the check set.

Compatibility

• Pin the version exactly in composer.json ("imanghafoori/laravel-self-test": "x.y.z"), commit the lockfile, and record the pinned tag in the team runbook.
• Verify against the project's Laravel and PHP constraint before merging; run the full existing test suite plus Pint and PHPStan in the same CI job to detect toolchain conflicts early.
• Add a scheduled (quarterly or per-Laravel-major) review task to evaluate version bumps — an unpinned dev dependency that silently changes check behavior is worse than no check.

Sequencing

1. Confirm package identity and pin an exact version (0.5d).
2. Baseline read-only run and finding triage (1–2d, largely engineering time).
3. Land true-positive fixes as isolated, reviewable PRs — never mixed with feature work (1–3d, proportional to findings).
4. Add non-blocking CI job, observe for two sprints, measure flake/false-positive rate (0.5d).
5. Promote to blocking on changed files; document the suppression policy (0.5d).
6. Evaluate --fix adoption only after step 5 is stable.

Operational Impact

Maintenance

• Ongoing cost is low and mostly config-shaped: a suppression list, a pinned version, and a policy for which checks are enabled. Budget roughly 1–2 engineer-hours per month plus one review per Laravel major upgrade.
• The package itself requires no operational ownership. There is no service to run, no data to back up, no certificate to rotate. The only durable artifact is the CI job definition.
• Risk of the maintainer going inactive is real but cheaply hedged: removal is a composer remove and a CI job deletion. Keep the tool isolated to a single CI job and a single config file so removal is a contained revert rather than a refactor.

Support

• Support surface is internal: the platform/DevEx team owns the CI job and the suppression list. No vendor escalation path exists.
• Expect recurring "why is this flagged?" questions in the first month; publish a short internal FAQ mapping each enabled check to what it detects and how to suppress it legitimately.
• Escalation for a wrong finding is a code comment plus a suppression entry — not a bug report upstream, unless the team is willing to fund a fix.

Scaling

• Runtime scales with application size (file-count-bound, single-pass file reads). Expect minutes, not seconds, on very large monorepos; scope checks by path to keep CI under a tolerable threshold.
• Organizational scaling is the real constraint: with more teams contributing, the suppression list becomes a shared resource and needs an owner and a review rule, or it will silently grow until the tool is effectively disabled.
• Rollout across N services should be templated — one shared CI job include and one shared baseline config — not per-repo bespoke configuration.

Failure modes

• CI false-positive storms blocking unrelated PRs → highest-probability failure. Mitigate by starting non-blocking on changed paths only, then promoting.
• Aggressive auto-fix corrupting code on a bulk --fix run → mitigate by restricting --fix to a single scoped PR with full test validation and mandatory human review.
• Abandonment / Laravel-major incompatibility → mitigate with exact version pinning and a calendar review; keep the CI job in one file for instant removal.
• Silent suppression creep hollowing out the tool → mitigate with a quarterly suppression-list audit and a rule that every suppression carries a reason and an owner.
• Redundancy with Pint/PHPStan creating duplicate or conflicting reports → explicitly partition check ownership across the three tools.
• Exit-code semantics not honored → verify in phase 1 that a known-bad fixture fails the job; do not assume the gate works.

Ramp-up

• Onboarding is under an hour for an engineer already fluent in Laravel and CI: one README section, one composer check script, one CI job. No training program required.
• The steeper curve is organizational, not technical — establishing the norm that structural findings are fixed before a PR merges. Lead with a single team pilot, publish the finding counts and the false-positive rate, then expand.
• Recommend a two-sprint pilot with explicit success criteria: (a) CI job exit-code behavior verified, (b) per-check false-positive rate below an agreed threshold, (c) at least one class of real structural defect caught that the existing toolchain missed. If any criterion fails, do not promote to blocking — and be prepared to drop it, since the cost of doing so is near zero.