- What is Laravel Microscope and what does it actually check?
- Laravel Microscope is a static analysis tool that inspects your Laravel codebase without executing it. It focuses on Laravel-specific conventions that generic PHP analysers rarely reach: route actions pointing at methods that do not exist, view() calls referencing missing Blade files, PSR-4 namespace and filename mismatches, unused imports, missing return statements, and malformed migration filenames. It reports the problems it finds and can also suggest or apply fixes. It is a developer-time toolchain addition, not a runtime library.
- How do I install Laravel Microscope in a Laravel project?
- Install it as a dev dependency with composer require --dev imanghafoori/laravel-microscope, then commit the composer.json and lockfile changes. Optionally publish its configuration file with the vendor:publish command so you can manage exclusions in config/microscope.php. No application code changes are required to start using the diagnostic commands. Because it only registers artisan commands through a service provider, it does not touch request handling.
- Should Laravel Microscope be installed only as a dev dependency?
- Yes, it should always be require-dev and never shipped in a production image. The package is a static analysis and auto-correction tool for engineering workflows, not a runtime component, so there is no reason to carry it into production. Keeping it out of production also avoids unnecessary autoload and image weight. Pin a version in your lockfile so local runs and CI stay consistent.
- What is the difference between the check:* and fix:* commands in Laravel Microscope?
- The check:* commands are diagnostic only: they scan and report problems without mutating any files, which makes them safe for CI gating. The fix:* commands rewrite your source files in place to correct the detected issues. Start with a narrow set of check commands to measure noise on your codebase, then decide whether auto-fix is appropriate. If you enable fixers, run them on a dedicated branch and require pull request review before merging.
- Which Laravel and PHP versions does Laravel Microscope support?
- Support depends on the version constraints declared in the current release's composer.json, so check those against your supported matrix before adopting it. The project is actively released, with a 2025 release indicating ongoing compatibility work. If you maintain multiple Laravel versions across projects, trial the package on each one rather than assuming uniform behaviour. Pin the version you validate so a future upstream release cannot silently change results.
- Can I run Laravel Microscope in CI or a git pre-commit hook?
- Yes. The tool runs synchronously, terminates on its own, and has no database, queue, external service, credential, or network dependency, so it slots cleanly into a CI job or a git hook. Use the check:* commands for CI so the pipeline only reports and never rewrites files. A common pattern is a pre-push or CI step that fails the build on findings, with fixes applied deliberately by a developer. This keeps the gate low risk and high value.
- Does Laravel Microscope conflict with PHPStan, Larastan, Pint, or Rector?
- No, it is designed as a complementary layer rather than a replacement. It reasons about Laravel conventions that PHPStan and Larastan do not cover without custom extensions, such as route-to-method resolution and Blade view existence. There is some overlap with Pint and Rector around unused imports and early returns, so sequence your tools to avoid two of them rewriting the same lines. A typical order is formatters first, then static analysis and Microscope checks.
- How do I exclude directories or customize Laravel Microscope's checks?
- Publish the config file with vendor:publish and manage the exclusions list in config/microscope.php. Projects with heavy custom bootstrapping, non-standard view resolution, or modular and package-based architecture usually need more exclusions than a conventional Laravel skeleton. Assign a clear owner for that config file, since it will drift as the codebase evolves. Commit the config alongside the dependency so every environment behaves the same.
- What false positives should I expect, and is auto-fix risky?
- False positives show up on dynamic or unconventional code such as magic method dispatch, string-built route names, runtime-registered views, and package-provided routes. In diagnostic mode that is only noise you can suppress; in fix mode an unreviewed pass could alter real behaviour. Mitigate by starting with a narrow check set, running fixers only on a branch, and requiring pull request review of the resulting diff. Treat every generated change as untrusted until a human has read it.
- Is Laravel Microscope actively maintained, and is it a good alternative to PHPStan?
- It has roughly 1.5k GitHub stars and a 2025 release, indicating an active real user base, but it is effectively a single-maintainer MIT project, so bus factor is 1 and release cadence depends on that individual. Reported zero dependents is likely a Packagist indexing artefact for dev-only tooling rather than genuine absence of use, but verify by trialling it on your own codebase. It does not replace PHPStan or Larastan; it complements them by covering Laravel-specific convention defects. Before committing organisationally, confirm you can pin a version and survive a six to twelve month upstream gap.