laravel-microscope: Laravel Code Checks and Refactoring

Why laravel-microscope Targets Laravel Repositories

laravel-microscope addresses repository inspection for PHP applications built on Laravel. Its users are developers who want targeted checks for framework-specific code, especially after refactoring or when reviewing output from an AI coding agent. The repository description calls it a tool for finding certain errors with smart checks, while the README presents it as an addition to tests rather than a test framework replacement.

The focus is Laravel structure. The documented commands cover routes, Blade views, gates, aliases, controllers, migrations, imports, helper functions, fully qualified class names, and action comments. That coverage matters because a general IDE may recognize PHP syntax without applying checks tied to a Laravel application's organization. Microscope's README claims that it understands Laravel runtime behavior and magic, although the README does not explain how each rule models those behaviors.

The project also has a refactoring component. Its `search_replace` command supports defined patterns, placeholders, a mutator, filters, captured PHP statements, captured global function calls, and repeating patterns. The `check:early_returns` command detects early-return cases, while the README says Microscope can apply those changes automatically. Detection and modification are separate concerns here: a check may identify a candidate, while automatic rewriting requires closer review because it changes executable code.

How laravel-microscope Checks a Laravel Application

Based on the README and repository layout, Microscope exposes its behavior through PHP Artisan commands implemented within a PHP package. There is no documented background service, web interface, configuration server, or remote API. A developer enters the Laravel project environment, selects a command associated with one check, and reviews its result in the terminal. The repository contains `src/`, `config/`, command-related files under `microscope/`, and templates, which is consistent with a package that ships Artisan commands and reusable analysis or rewriting logic.

Each command has a narrow subject. `check:imports` examines imports, `check:psr4` concerns PSR-4 issues, and `enforce:imports` is the enforcing counterpart named in the recent `v1.0.403` release. `check:routes` concerns routes, `check:views` concerns views, and `check:blade_queries` targets queries associated with Blade. Other commands inspect gates, models, aliases, migrations, comments, aborts, extracted Blade files, and extra fully qualified class names. This design allows a team to adopt one check without treating the entire command catalog as mandatory.

The pattern-oriented `search_replace` command operates at another layer. According to the README, users can define patterns, choose placeholders, apply a mutator, add filters, and capture PHP statements or global calls. Repeating patterns can match multiple occurrences. This indicates a configurable source transformation facility rather than a single built-in replacement. However, the README does not show the configuration file, complete syntax, replacement order, or conflict behavior, so those details remain undocumented interfaces.

Installing Microscope and Running a First Check

The README identifies an installation section, but the installation commands appear after the point where its text ends. No exact Composer command, Laravel provider registration step, configuration publish command, or minimum PHP and Laravel version is visible. The project links to Packagist through badges, but the README does not provide an installation command that can be copied without guessing. This tutorial therefore stops before an unverified installation snippet.

Once Microscope is installed according to the repository's complete installation instructions, the first practical use can be limited to one import check. Enter the Laravel project directory and run this documented command:

php artisan check:imports

The README lists this command but does not describe its exact terminal output, exit codes, affected paths, or behavior when no problems are found. A developer should therefore compare the command's result with the current source tree and its Git working copy rather than assuming a particular success message.

After reviewing the result, a developer can select a related enforcement command:

php artisan enforce:imports

The repository identifies `v1.0.403` with the description `enforce:imports`, which confirms that this command exists. The README does not state whether enforcement modifies files, rejects commits, or changes the command's exit status. It should therefore be treated as potentially mutating until its behavior has been reviewed. Starting with `check:imports` is the safer documented first step because the command name distinguishes checking from enforcement.

Search and Replace Capabilities Need Deliberate Guardrails

Microscope is more than a fixed list of read-only checks. Its `search_replace` command is documented as a configurable transformation tool with several matching controls. Patterns define the source text to locate, placeholders represent matched content, a mutator changes matched values, and filters narrow or condition the transformation. The documented capture features can include PHP statements or global function calls, while repeating patterns support multiple matches.

These features could reduce repetitive edits in a large Laravel repository, but they also move risk from finding a problem to changing source code at scale. A broad pattern may match more call sites than the developer intends. Repeating behavior makes that concern larger because one rule can affect several locations. A mutator adds another degree of freedom because it can alter the captured value rather than merely relocate it.

The README does not define dry-run output, a backup file, an undo command, conflict handling, or a guarantee that transformations preserve formatting. It also does not document whether the command skips vendor files or generated files. Those omissions matter for adoption. Developers should first use narrow patterns and inspect the repository diff after each transformation. The absence of a documented rollback mechanism is a real constraint, even if Git provides a separate recovery route outside the package.

Where Microscope Can Misjudge or Miss Application Intent

The strongest limitation is a mismatch between deterministic source checks and application intent. The README asserts that Microscope avoids false errors and understands Laravel runtime behavior, but it does not provide the rule catalog, examples of accepted exceptions, or output that would allow a reader to evaluate that claim. A check can identify an unusual pattern while still lacking enough context to know whether the pattern is intentional.

The command selection is also incomplete as a general quality system. The list does not present Microscope as a replacement for tests, static analyzers, type checkers, or code review. It also does not document one command that aggregates every available health check. Teams may still need their normal Laravel test suite, IDE diagnostics, and human review. Microscope's value is its focused Laravel checks, not comprehensive assurance by itself.

Automatic early-return refactoring deserves particular caution. A control-flow transformation can look cleaner while changing exception handling, authorization boundaries, side effects, or readability. The README confirms automatic application but does not specify exclusions or preview behavior. In projects with sensitive actions in controllers or policy-related methods, developers should treat a refactoring candidate as a proposal until its generated code has been reviewed. Microscope is the wrong tool when automatic source modification is prohibited or when a team requires an approval gate before any file changes.

Microscope Compared with General PHP Analysis Tools

The closest practical alternative is a general PHP static analyzer or IDE diagnostic system. The difference in approach is scope: general tools inspect PHP language constructs and can be configured with project-wide rules, while Microscope exposes commands named after Laravel concerns such as routes, gates, Blade views, migrations, aliases, and controllers. Microscope's Laravel focus may provide a shorter path to checks that require knowledge of framework structure.

The trade-off is transparency and breadth. A general analyzer may provide a documented rule system, machine-readable output, severity configuration, or broad language coverage. Those facilities are not documented in the Microscope README. Conversely, Microscope offers a transformation-oriented `search_replace` command and an enforcing import command that are not established features of the unnamed alternative. The right choice therefore depends on the missing capability: use a general PHP analyzer when portable static analysis is the requirement, and consider Microscope when targeted Laravel checks or its documented Artisan workflow are the priority.

Microscope can complement either approach. The README says that an application may still need it despite a substantial test suite. It does not claim that tests should be removed, nor does it explain how its results map into static-analysis standards. A team should therefore evaluate the packages as separate layers rather than assume that one subsumes the other.

Maintenance, Compatibility, and the MIT License

The repository is not archived. Its last push was on 2026-10-08, so there is a recent repository change, although a push date alone does not establish compatibility with every Laravel release. The listed release history includes `v1.0.403` for `enforce:imports` on 2025-08-15, `v1.0.272` with PHP 8.2 support on 2022-12-19, and `v1.0.213` labeled as a bug fix on 2022-03-02. The README badge mentions testing the package with Laravel 12, but the repository does not state the exact supported version range in the visible text.

Upgrade cost depends on which commands a project adopts. A read-only import check may require little configuration beyond installation. Pattern matching, mutators, filters, and automatic early-return changes can create a larger maintenance burden because teams need to preserve documented patterns and review generated edits across Laravel upgrades. The repository does not provide migration guidance for Microscope configuration in its README.

The project uses the MIT license. The license permits use, modification, distribution, and incorporation subject to its notice and disclaimer conditions. Package dependencies and internal policy still need separate review. This is an engineering licensing note, not legal advice, and the complete `LICENSE.md` should be reviewed for deployment and distribution decisions.

Editorial conclusion

laravel-microscope fits Laravel developers who want targeted Artisan checks alongside tests and review, particularly after broad changes or AI-assisted edits. It is a poor fit for non-Laravel applications, teams seeking a full replacement for static analysis, or developers who need documented output formats and rollback guarantees. Before adopting it, confirm compatibility with the project's Laravel and PHP versions, run only the relevant checks on a clean working copy, and review every changed file because automatic early-return refactoring can change control flow.

Frequently asked questions

Official sources

1. imanghafoori1/laravel-microscope on GitHub
2. Issues
3. License: MIT
4. README
5. Releases