PHP Insights: console quality checks for PHP projects, and what they actually measure

The problem PHP Insights addresses, and who it is written for

A PHP codebase accumulates opinions. One contributor's formatting, another's long methods, a controller that quietly grew a dozen responsibilities. Linters catch some of it, static analysers catch other parts, and neither produces a number a team can look at together. PHP Insights was built for that gap: the README describes it as "the perfect starting point to analyze the code quality of your PHP projects", and it runs from the terminal rather than from an editor plugin or a hosted dashboard.

The audience is therefore teams that already have a PHP application and want a periodic or per-commit read on its shape. The README lists Laravel, Symfony, Yii and Magento as frameworks it is designed to work out-of-the-box with, which tells you the intended user is running a framework, not a bare set of scripts. It is a dev-time tool, not something you ship: the install command places it in require-dev, and the entry point is a binary inside vendor/bin.

What the report measures: quality, style, architecture and complexity

The README's feature list names four things the tool analyses: code quality, coding style, code architecture and complexity. That grouping is the design decision worth understanding. PHP Insights is not a single analyser with a single rule set. It is a runner that collects checks from several sources and presents them as one scored report, which is why a run can flag a formatting issue and a structural issue side by side.

Two consequences follow. First, the score is only as meaningful as the checks enabled in your configuration, so a high percentage does not mean the code is correct, it means the enabled checks passed. Second, because the tool mixes style and structure, a project can be penalised heavily for cosmetic issues while its genuinely tangled classes sit below the threshold. The repository layout reflects this aggregation: there is a config/ directory, a phpinsights.php file at the top level, a schema.json describing the configuration shape, and a src/ tree that holds the checks and the framework adapters. The adapters matter because a Laravel or Symfony project has conventions (facades, service providers, generated code) that a generic rule set would flag as noise, and the adapter is what stops that.

Installing PHP Insights and running a first analysis

The README's quick start is two commands. The first adds the package as a development dependency through Composer, so it lands in require-dev and never in a production install.

composer require nunomaduro/phpinsights --dev

The second runs the binary that Composer placed in your project's vendor/bin directory. With no arguments it analyses the project from the current directory and prints the scored report to the terminal.

./vendor/bin/phpinsights

For a Laravel application the README gives a different path. First publish the configuration file through the framework's vendor:publish command, naming the package's service provider explicitly.

php artisan vendor:publish --provider="NunoMaduro\PhpInsights\Application\Adapters\Laravel\InsightsServiceProvider"

After that the tool is reachable as an Artisan command rather than as the vendor binary.

php artisan insights

What you should expect from the first run is a set of failures, not a clean sheet. The published configuration file is where you decide which checks run and at what threshold, and the repository's schema.json describes the keys that file accepts. The README does not document a baseline or ignore mechanism in the text given here, so if you need to exclude files or checks, the configuration file and the project's own documentation site at nunomaduro.github.io/phpinsights/ are the places to look rather than the README.

Where PHP Insights is the wrong tool

The honest limitation is scope. PHP Insights reports on quality, style, architecture and complexity, and the README makes no claim about type inference, dead code detection or framework-specific correctness. If your failure mode is a wrong argument type passed to a method, or a class that no longer resolves, this tool is not the instrument for it, and running it will not surface those problems.

The second limitation is the first-run experience on existing code. A legacy application that has never been measured will fail a large share of the enabled checks, and because the output is a score, the temptation is to treat that number as a verdict on the team rather than a description of the code. The score also moves when you change the configuration, which means two projects' percentages are not comparable unless their phpinsights.php files match. Treat the number as a trend inside one repository, not as a ranking between repositories.

Third, the adapters are the boundary. The README names Laravel, Symfony, Yii and Magento as covered out-of-the-box. A framework outside that list, or a project with heavy code generation, will produce findings the tool cannot distinguish from real problems, and someone has to maintain the exclusion list.

How PHP Insights differs from PHPStan and PHP Mess Detector

The obvious alternative is PHPStan. The two answer different questions. PHPStan builds a model of your types and reports where the model breaks, which is why its findings are usually phrased as errors about values and signatures. PHP Insights counts and scores, grouping findings under quality, style, architecture and complexity, and its output is a report you read for shape rather than a list of type errors you fix one by one. A team serious about static analysis typically wants both, and the order matters: fix the type errors first, because refactoring for complexity while the types are still wrong means refactoring code you do not yet understand.

The other comparison is PHP Mess Detector, usually paired with PHP_CodeSniffer. That combination is the traditional route to the same territory, and the repository itself carries a .phpcs.xml.dist and a .php-cs-fixer.php, which suggests the maintainers run those tools alongside their own. The difference in approach is packaging. With PHP_CodeSniffer and PHPMD you assemble and configure several tools and read several outputs; PHP Insights bundles a set of checks behind one command and one score. You trade granular control of individual rule sets for a single, consistent report. If your team already has a tuned PHP_CodeSniffer ruleset and a PHPMD ruleset, PHP Insights adds a summary layer rather than replacing them.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-15, the same date as the v2.15.0 release. The previous release, v2.14.2, was on 2026-04-12, so the cadence visible in the release list is roughly a few months between tagged versions rather than a continuous stream. That is normal for a tool whose checks change slowly, but it does mean a new PHP language version or a new framework major version may land before the corresponding adapter update does, and you should check the release notes for the version you install rather than assuming support.

Upgrading is a Composer operation, and the practical cost is configuration drift. Because the enabled checks and thresholds live in phpinsights.php, a version that adds, removes or renames a check can change your score without a line of application code changing. Pin the version in composer.json and read the CHANGELOG.md before moving the constraint, particularly across a minor bump.

The licence is MIT, stated in the README and present as LICENSE.md at the repository root. MIT is permissive: it allows commercial and closed-source use, modification and redistribution, with the copyright notice and permission notice retained. That is a description of the licence text, not legal advice, and if your organisation has a policy on third-party dependencies you should route it through whoever owns that policy.

Editorial conclusion

Adopt PHP Insights when you want one terminal command that turns code quality, coding style, architecture and complexity into a shared, inspectable score for a PHP application, and when the framework you use is one the adapters cover, such as Laravel or Symfony. Do not adopt it as your only static analysis: it aggregates style and metric checks, and it does not do the type-level reasoning a dedicated analyser does, so a project whose main risk is type errors should keep that analyser and treat Insights as the readability and structure layer. Before rolling it out, run ./vendor/bin/phpinsights on the current codebase and read the failing checks and their thresholds, because a legacy project will fail many of them on the first run and the score is only useful once you know which checks you intend to fix and which ones the config excludes.

Frequently asked questions

Official sources

1. License: MIT
2. nunomaduro/phpinsights on GitHub
3. Project website
4. README
5. Releases