PhpMetrics: Static Analysis Reports for PHP Projects

What PhpMetrics measures and who it is for

PhpMetrics is a static analyzer for PHP. It reads a folder of source files and produces metrics about the project and about individual classes, then renders them as an HTML report. The README describes the output as "beautiful and readable HTML report", and the repository ships a screenshot of the standard report under doc/overview.png.

The audience is a PHP team that wants a shared artifact to look at: which classes are large, which are coupled to many others, where the inheritance trees are deep. That is a different job from enforcing a style or a rule set during a build. PhpMetrics is a reporting tool. Nothing in the README describes it as a gate that fails a pipeline on its own.

That distinction matters when you pick it. If your team already argues about code quality with no shared data, a generated report gives the argument a common reference. If your team wants a tool that refuses a pull request, PhpMetrics is the wrong shape of tool unless you configure the CI rules it mentions.

How the analysis pipeline works

The tool is distributed as a Composer package with a binary at vendor/bin/phpmetrics, and the repository also builds a PHAR into releases/phpmetrics.phar. The Dockerfile copies that PHAR to /usr/local/bin/phpmetrics, sets the entrypoint to phpmetrics, mounts /app as a volume and uses --version as the default command. So the same artifact runs from a Composer install or from a container.

The command takes an output option and a target folder. The README example uses --report-html=myreport and a folder path, and the result is written to ./myreport/index.html. The Dockerfile installs git specifically so the --git option works, which tells you the analyzer can read repository history as an input alongside the source tree, not only the current state of the files.

Configuration is a separate file. The repository root carries config-example.json and config.yml, and the README points to a configuration page for customizing the report, adding options and defining rules for continuous integration. The binary also exposes its own metric list through php ./vendor/bin/phpmetrics --metrics. That flag is the reliable way to see what a given version reports, since the README does not enumerate the metrics itself.

Installing PhpMetrics and generating a first report

The README's quick start installs the package as a development dependency with Composer, then runs the binary against a folder. The example below is copied from it, with a placeholder folder name in place of the real path.

# install the package as a dev dependency
composer require phpmetrics/phpmetrics --dev

# run PHPMetrics to analyze a folder and generate a report
php ./vendor/bin/phpmetrics --report-html=myreport <folder-to-analyze>

Replace the angle-bracketed folder with something like src or app. The command writes a directory named myreport next to where you ran it. Open ./myreport/index.html in a browser and you get the standard report.

Before you trust the numbers, ask the binary what it can produce. This prints the metric list for the installed version:

php ./vendor/bin/phpmetrics --metrics

The README gives no example of a configuration file's contents, only links to the configuration page and points at config-example.json and config.yml in the repository. Read those files in the version you installed rather than copying a snippet from a blog post, because the README does not guarantee their keys.

Running PhpMetrics from the container image

The repository Dockerfile is short and worth reading before you build anything around it. It starts from php:8.4, copies releases/phpmetrics.phar into /usr/local/bin/phpmetrics, makes it executable, installs git, declares /app as a volume and sets the working directory there. The entrypoint is phpmetrics and the default command is --version.

FROM php:8.4
COPY releases/phpmetrics.phar /usr/local/bin/phpmetrics
RUN chmod +x /usr/local/bin/phpmetrics \
    && apt-get update && apt-get install -y git \
    && rm -rf /var/lib/apt/lists/*
VOLUME ["/app"]
WORKDIR /app
ENTRYPOINT ["phpmetrics"]
CMD ["--version"]

The practical consequence is that the image runs the packaged PHAR, not the source in your working copy, so the image version and the Composer version can drift. Mount your project at /app and pass the report option and folder as arguments. The git install is there for --git; if you drop it, that option stops working.

Where PhpMetrics is the wrong tool

PhpMetrics does not decide anything for you. The README mentions configuring rules for continuous integration, but it does not show the syntax, and the quick start never runs the tool in a mode that exits non-zero on a threshold. If what you need is a build that fails when a class gets too large, you are writing that rule yourself in a configuration file whose format the README does not document. Budget time to read the configuration documentation before you promise a team a quality gate.

The report is also a snapshot of a folder, not a service. Nothing in the README describes a server, a persistent dashboard or a metrics endpoint, so the HTML file is something you regenerate and publish yourself. The related searches include a phrase about PHP metrics and Prometheus; the README and the repository files here describe no Prometheus exporter, so do not assume one exists.

Finally, static analysis of this kind reads code, not behaviour. A class with high coupling in the report may be perfectly reasonable, and a small class may hide a hard problem. The numbers start a conversation; they do not end one, and treating them as a verdict produces the usual arguments about thresholds.

How PhpMetrics differs from PHPStan and PHPMD

PHPStan is the natural alternative people reach for, and the difference is in what each one produces. PHPStan is built around finding errors in code by inferring types and reporting problems at specific lines. PhpMetrics does not report defects at lines; it computes measurements about classes and the project as a whole and renders them as a report you browse. A type error and a coupling score are not the same kind of output, and neither tool substitutes for the other.

PHPMD is closer in shape: it applies rules to source and reports violations, which is the enforcement model PhpMetrics only reaches through configuration. If your goal is a list of rule violations in a CI log, PHPMD's model is the direct fit. If your goal is a page a developer can open to see the shape of the codebase, PhpMetrics is the direct fit.

The honest framing is that PhpMetrics answers "what does this codebase look like" and the other tools answer "is this line wrong". Teams often end up running one of each, and there is no conflict in doing so.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-08-21. Recent releases are v2.11.0 on 2026-08-09, v2.10.0 on 2026-07-21 and v2.9.0 on 2025-07-07. The gap between v2.9.0 and v2.10.0 is roughly a year, followed by two releases within a month, which is a pattern worth knowing if you pin versions: quiet stretches happen.

The release process is visible in the Makefile and it is manual. A tag must match the pattern vX.Y.Z with an optional alpha, beta or rc suffix, checked by the check-tag target. The tag target rewrites the version string in several files, including src/functions.php, where getVersion() returns the version without the v prefix. The new_git_version target commits those files, tags the commit and pushes the tag, and a comment in the Makefile states that master is protected and never pushed to, so the release commit lives only under the tag. If you build from a branch rather than a tag, you are not on the released artifact.

The licence is MIT, and the README defers to the LICENSE file. MIT is permissive, which is the usual reason a tool like this is easy to adopt inside a company. That is a statement about the licence identifier, not advice about your situation; read the LICENSE file and your own policy if the distinction matters to you.

Editorial conclusion

Adopt PhpMetrics if you want a browsable HTML picture of class and project metrics for a PHP codebase and you are willing to read the report rather than have a tool fail your build for you. Skip it if you need a rule engine that blocks a merge on its own; PhpMetrics reports, and the CI rules live in a configuration file you have to write. Before committing to it, run php ./vendor/bin/phpmetrics --metrics to see the metric list your version actually exposes, and check the configuration documentation for the CI rule syntax, because the README does not describe it.

Frequently asked questions

Official sources

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