Laravel Microscope Laravel Package

Getting Started

Install (dev only):

composer require imanghafoori/laravel-microscope --dev

The service provider is auto-discovered; there is no required configuration to get value on day one. On Laravel 5.5+ (through current versions) the package registers its Artisan commands automatically.

First command to run:

php artisan check:all

This runs the full suite of Laravel-aware static checks against your application and prints one block of findings per checker. To see the shape of the output without waiting on everything, start with a single checker:

php artisan check:imports

Where to look first:

1. php artisan check:imports — unused/incorrect use statements. This is the highest signal-to-noise check and the fastest win on any codebase.
2. php artisan check:imports --fix — auto-removes dead imports. Run it on a clean git tree, then git diff to review.
3. php artisan check:all — once imports are clean, this gives you a realistic picture of the rest of the backlog (routes, views, translations, dead controllers).

First use case: drop check:imports --fix into your workflow as a cleanup pass on the directories you already own (app/, routes/, database/). It is safe, mechanical, and immediately reduces diff noise in later PRs. Only after that should you turn on the broader checks, because they surface findings that need judgment.

Implementation Patterns

Triage-as-you-touch-a-feature. Microscope is most useful when scoped to the area of a PR rather than as a monolithic gate:

CI as a second line of defence. Add a job after your test suite so a broken reference is caught even if no test covers that path:

- run: php artisan check:all

Because the checks are static, they catch dead route(), view(), and translation references that only fail at runtime on an untested branch. Order it after PHPStan/Pint so the cheap, deterministic tools fail first and Microscope runs on code that already parses cleanly.

Composer script for local parity with CI:

"scripts": {
  "check": ["@php artisan check:all"],
  "fix":   ["@php artisan check:imports --fix"]
}

Then composer fix before committing and composer check before pushing — same commands locally and in CI, so there is no divergence.

Legacy-codebase rollout. Do not enable check:all on a ten-year-old app and expect a usable signal — you will get hundreds of findings and the team will mute the tool. Instead:

1. Run check:imports --fix once across the whole app and commit it as a standalone, reviewable "chore" commit.
2. Add check:all to CI with the legacy directories excluded in config/microscope.php (publish it with vendor:publish).
3. Shrink the exclusion list one directory per sprint.

Dead-controller pruning. check:dead_controllers finds controllers no route points at. This is a reliable, low-risk way to identify removable code — verify the controller isn't resolved from the container by a string name before deleting, then pair the deletion with a route file cleanup.

Blade extraction suggestions. check:extract_blades flags duplicated markup across templates and suggests extracting a partial. Treat the output as a code-review prompt, not an autofix — the suggested partial boundary is not always the right abstraction.

Pair with, don't replace, PHPStan. Microscope understands Laravel conventions (view(), route(), __(), container strings) that PHPStan misses without Larastan stubs; PHPStan understands types and generics that Microscope does not. Run both.

Gotchas and Tips

• --fix writes to disk. Always commit or stash first. Review the diff — auto-removal of an import can be wrong when the symbol is used only inside a string-evaluated context or a Blade template that the checker doesn't parse.
• Dynamic references produce false positives. view($template), route("{$prefix}.show"), and __("errors.{$code}") cannot be statically resolved. Expect these to be flagged; do not "fix" them by inlining literals. Exclude the file or ignore the finding.
• Vendor and framework internals are excluded, but your calls into them are not. A call to a package's view or route name will be validated against your app's registry, so third-party package views/translations registered at runtime can be reported as missing. Confirm before deleting.
• Static analysis cannot see runtime registration. Views, routes, and translations registered from a service provider via loadViewsFrom/loadTranslationsFrom are invisible to the scanner in some configurations. If a genuinely working reference is flagged, that is the usual cause.
• Large codebases are slow. Each checker re-reads files from disk. On a big app/, check:all can take tens of seconds. Run individual checkers locally while iterating and reserve check:all for CI.
• Exit codes matter more than the log. Confirm your version returns a non-zero status when findings exist, otherwise a green CI job is meaningless. Assert on the exit code, not on grep-ing output.
• Config quirks. Publish config/microscope.php before customising exclusions — editing a non-published config silently does nothing. Remember to re-publish after major package upgrades; the option set changes between releases.
• Not a test suite. Despite the tagline, Microscope verifies references and conventions, not behaviour. It will not catch a wrong if or a missing authorization check. Budget it as a linter, not as coverage.
• Extension point to know: exclusions/ignore paths in the published config are the intended escape hatch for false positives. Reach for that before patching source or suppressing output globally — a growing global suppression list is the signal you have scoped the tool too broadly.
• Pin the major version in composer.json and bump deliberately. Checker sets and output formatting shift between releases, which can turn a passing CI run red on an unrelated PR.