imanghafoori/laravel-microscope
Laravel Microscope is a static analysis tool that scans your Laravel codebase without running it, catching bugs, code smells, and convention issues across routes, views, classes, and more. It reports problems and suggests fixes so you can clean up your project fast.
Architecture fit. Laravel Microscope is a developer-time static analysis and auto-correction tool, not a runtime library. It registers artisan commands via a service provider and inspects the application's own source, views, routes, and migrations rather than participating in request handling. That makes it a natural fit for the engineering toolchain layer of a Laravel codebase (alongside Pint, PHPStan/Larastan, PHP_CodeSniffer, Rector) and a poor fit for anything requiring production runtime behaviour. Because it reasons about Laravel-specific conventions — route action methods that don't exist, view() references to missing Blade files, PSR-4 namespace/file mismatches, unused imports, missing return statements, malformed migration filenames — it covers a class of defect that generic PHPStan rules do not reach without custom extensions. The correct architectural decision is require-dev only; it should never be installed in a production image.
Integration feasibility. Low effort. Installation is a single Composer dev dependency plus an optional vendor:publish of its config file. There is no database, queue, external service, credential, or network dependency. It runs synchronously and terminates, so it slots cleanly into a CI job or a Git pre-commit/pre-push hook. The main design decision is report-only versus auto-fix: the package ships paired check:* commands (diagnostic, non-mutating, suitable for CI gating) and fix:* commands (rewrite source files in place). The former is a low-risk, high-value gate; the latter needs a governance wrapper.
Technical risk. Three material risks. First, the auto-fix surface. Commands that rewrite source will produce diffs that must be reviewed; on dynamic or unconventional code (magic method dispatch, string-built route names, runtime-registered views, package-provided routes) the analyser can flag false positives, and an unreviewed fix pass could alter behaviour. Mitigation: run fixers on a branch only, require PR review, start with a narrow check set. Second, maintainer concentration. This is effectively a single-maintainer project (MIT, one prominent author). Bus factor is 1, and the release cadence depends on that individual's availability. Third, the adoption signal. ~1.5k stars and a recent (2025-08) release indicate an active, real user base, but the reported zero dependents is a weak positive-validation signal — likely a Packagist indexing artefact for dev-only tooling rather than genuine absence of use, but it should be verified by trialling the package against your own codebase before committing organisationally.
Key questions.
Stack fit. Requires Composer and a Laravel application skeleton with the standard app/, routes/, resources/views/, and database/migrations/ layout. It assumes conventional Laravel structure — applications with heavy custom bootstrapping, non-standard view resolution, or modular/package-based architecture will see more noise and need more exclusions in config/microscope.php. No conflict with Pint, PHPStan, or PHPUnit; it is a complementary layer, and in practice several of its checks (imports, early returns) overlap with what Pint/Rector would handle, so sequencing matters to avoid two tools fighting over the same lines.
Migration path. Additive, not invasive: composer require --dev imanghafoori/laravel-microscope, commit the lockfile change, publish config, commit the config. No application code changes are required for the diagnostic mode. Rollback is a single composer remove --dev plus deleting the config file — the blast radius is confined to dev dependencies and CI config.
Compatibility. Verify the package's composer.json constraints against the project's PHP and laravel/framework versions before rollout; on older Laravel majors, expect to pin an older package tag. Also confirm behaviour under the CI PHP version and with opcache/JIT enabled, though neither should affect a CLI static pass. Teams on monorepos or multi-app repositories should confirm the commands can be scoped to subdirectories rather than scanning the whole tree.
Sequencing. (1) Install as a dev dependency on a throwaway branch and run the check:* suite in report-only mode against the full codebase to build a baseline of findings and false positives. (2) Triage: codify exclusions in the published config for known false positives, and file the genuine findings as remediation tickets. (3) Add a non-blocking CI job that produces a report artifact — this builds visibility without breaking builds. (4) After the backlog is cleared, flip the agreed subset of checks to blocking on new/changed code (diff-scoped if the tooling allows). (5) Only then evaluate fix:* commands, wired into a developer-invoked branch workflow or a scheduled cleanup PR, never into the main CI pipeline. (6) Run a periodic full sweep (weekly or per-release) to catch drift.
Maintenance. Very low steady-state cost: one dev dependency, one config file, occasional version bumps. The config file becomes an owned artifact — exclusions accumulate and should be reviewed, since a stale ignore list silently weakens the tool. Budget a small recurring allocation (a few hours per quarter) for upgrades and false-positive triage; the real ongoing cost is the human review of auto-fix diffs if that mode is enabled.
Support. Community-supported MIT project with no vendor SLA and a single primary maintainer. Internal ownership must be explicit — a named engineer or the platform team — with a documented fallback: if upstream stalls, the diagnostic checks can be partially replaced by Larastan custom rules or Rector rules, and the package can be forked given the permissive licence. Do not let it become load-bearing for release gating without a named owner.
Scaling. Analysis time scales with codebase size and is CPU-bound single-process work; on large monorepos expect multi-minute runs, which argues for CI-only execution plus optional local runs on changed directories rather than a pre-commit hook on every commit. There is no runtime, memory, or concurrency scaling concern because nothing runs in production. Team scaling is the real constraint: value depends on every developer running the same version and config, so the config must be committed and the dependency pinned rather than left floating.
Failure modes. (a) Silent no-op — a version incompatibility or misconfiguration means the tool runs and reports nothing, giving false assurance; mitigate with a deliberately-seeded failing fixture or a sanity assertion that the check runs and exits as expected. (b) False positives on dynamic code — noisy output that teams learn to ignore; mitigate with exclusions and diff-scoped gating. (c) Auto-fix corruption — the highest-severity failure, a source rewrite that changes behaviour or breaks syntax; mitigate with branch-only execution, mandatory PR review, and PHPUnit/PHPStan runs after every fix pass. (d) CI flakiness from a non-deterministic or slow full scan; mitigate by scoping the scan and caching dependencies. (e) Upstream abandonment — no security exposure since it is dev-only, but a frozen dependency on an unsupported PHP/Laravel version eventually blocks framework upgrades; track this as a standard dependency-health item.
Ramp-up. Low for individuals — the commands are discoverable via artisan and findings are self-describing, so a mid-level Laravel developer is productive within an hour. Organisational ramp-up is medium: the team needs a short written policy covering which checks are blocking, how to handle false positives (edit config, don't suppress inline), and the review rule for auto-fix PRs. A single lunch-and-learn or a short README section is sufficient. The main adoption risk is cultural, not technical: if the first rollout produces hundreds of pre-existing findings, teams will dismiss the tool — hence the report-only baseline phase before any gating.
How can I help you explore Laravel packages today?