PHPMD 3.0: PHP 8.1 minimum, new CLI, YAML/JSON/PHP configuration and #[SuppressWarnings]
PHPMD (PHP Mess Detector) is a static analysis tool that reports rule violations such as
unused code, naming problems and complexity thresholds. According to the
GitHub release, 3.0.0 was published on
4 October 2026 (13:38 UTC). It is the first release since 2.15.0, and the release notes point to
UPGRADING.md for the migration from PHPMD 2. This wiki first recorded it on 15 October 2026,
from a secondary news feed. That is not the release date.
Breaking changes
- PHP 8.1 or newer is required. The previous minimum was 5.3.9.
- New command line. The CLI now uses Symfony Console with named options. The command is
phpmd analyze [options] [--] [<paths>...]instead of positional format and rule set arguments. CI scripts that call PHPMD 2 need to change. - Options removed:
--ignore(use--exclude),--extensions(use--suffixes),--reportfile(use the format-specific--reportfile-text,--reportfile-xmland so on), and the--minimumpriority/--maximumpriorityaliases (use--minimum-priority/--maximum-priority). - Thresholds are named
maximum(#670), for exampleCyclomaticComplexity.reportLevelandTooManyMethods.maxmethods. The old property names are still accepted as aliases. Rules that used to report when the value equaled the threshold now report only when it is greater, so the configured maximum is the highest value that passes. Rules that check a lower bound (ShortVariable,ShortMethodName,ShortClassName) keepminimum. - Exit codes: processing errors exit with 3 instead of 1.
--update-baselinenow reports violations that are not in the baseline (#1344). It exits with 2 and does not add them to the baseline file. - Rule classes renamed, for example
LongMethod→ExcessiveMethodLengthandNpathComplexity→NPathComplexity. The rule names stay the same. - Extension API: pdepend/pdepend 3.x is required, the deprecated
PHP_PMD_*class aliases are removed, and there is a new exception hierarchy underPHPMD\Exception\. Suppressions are now applied by filtering violations after the rules run, andAbstractRule::setStrict()is removed. Several namespaces (Baseline,Cache,Config,TextUIand others) are marked@internaland are outside the 3.x compatibility promise.
New features
- Configuration formats: rule sets can be YAML, JSON or PHP as well as XML.
phpmd.yml,phpmd.yaml,phpmd.json,phpmd.xmlandphpmd.phpare detected automatically. Run without arguments,phpmddetects the configuration and target paths. Paths, format, cache, baseline, threads and priorities can be set in the file. phpmd initbuilds aphpmd.ymlwith an interactive wizard.phpmd migrateconverts a PHPMD 2 configuration to YAML.#[SuppressWarnings]attribute is the preferred way to suppress a warning. The@SuppressWarningsdocblock annotation is deprecated but still works. The newUnusedSuppressionrule (#1230) reports attributes that no longer suppress anything. It does not check docblock annotations.--threadsparses files in parallel. A progress bar is written to stderr (--no-progresshides it), and--xdebugand--bootstrapoptions were added.- New rules:
IfStatementWithoutLogic(conditions that contain only literals) andLongMethodName. - Rule changes:
UnusedFormalParameterskips methods marked#[Override].StaticAccessignores the static methods every enum has.UnusedPrivateField,UnusedFormalParameterandExcessiveParameterListaccept anexceptionslist. - GitHub Check Runs renderer (#965), custom renderers via
RendererFactory(#1196) and relative paths in reports (#706).
The release also lists many false-positive fixes, for example UnusedLocalVariable with ??=.
It also fixes a result-cache problem: the types declared in unchanged files were hidden from the
rules applied to changed files.
Limitations
This page summarizes the project's release notes and was not tested. It does not reproduce the
full list of fixes or the upgrade guide. Check UPGRADING.md in the repository before migrating.
Release notes are not evidence of adoption or of analysis quality.
Related
- PHPStan 2.3.0, another static analysis tool.