Repository files navigation

PHPMD is a spin-off project of PHP Depend and aims to be a PHP equivalent of the well known Java tool PMD. PHPMD can be seen as an user friendly frontend application for the raw metrics stream measured by PHP Depend.

https://phpmd.org

Seehttps://phpmd.org/download/index.html

Typephpmd [filename|directory[,filename|directory[,...]]] [report format] [ruleset file], i.e:

mapi@arwen ~ $ phpmd php/PDepend/DbusUI/ xml rulesets.xml

While therulesets.xml ruleset file could look like this:

<?xml version="1.0"?><rulesetname="My first PHPMD rule set"xmlns="https://phpmd.org/xml/ruleset/1.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="https://phpmd.org/xml/ruleset/1.0.0                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd"xsi:noNamespaceSchemaLocation="                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd">  <description>    My custom rule set that checks my code...  </description>  <ruleref="rulesets/codesize.xml" />  <ruleref="rulesets/cleancode.xml" />  <ruleref="rulesets/controversial.xml" />  <ruleref="rulesets/design.xml" />  <ruleref="rulesets/naming.xml" />  <ruleref="rulesets/unusedcode.xml" /></ruleset>

The xml report would like like this:

<?xml version="1.0" encoding="UTF-8" ?><pmdversion="0.0.1"timestamp="2009-12-19T22:17:18+01:00">  <filename="/projects/pdepend/PHP/Depend/DbusUI/ResultPrinter.php">    <violationbeginline="81"endline="81"rule="UnusedFormalParameter"ruleset="Unused Code Rules"externalInfoUrl="https://phpmd.org/rules/unusedcode.html#unusedformalparameter"priority="3">      Avoid unused parameters such as '$builder'.    </violation>  </file></pmd>

You can pass a comma-separated string with list of file namesor a directory names, containing PHP source code to PHPMD.

ThePHPMD Phar distribution includes the rule set files insideits archive, even if the "rulesets/codesize.xml" parameter above lookslike a filesystem reference.

• Notice that the default output is in XML, so you can redirect it toa file and XSLT it or whatever

• You can also use shortened names to refer to the built-in rule sets,like this:

  phpmd PHP/Depend/DbusUI/ xml codesize

• The command line interface also accepts the following optional arguments:

  • --verbose, -v, -vv, -vvv - The output verbosity level. Will print more informationwhat is being processed or cached. Will be send toSTDERR to not interferewith report output.text output will also have under each error a linkto the documentation of the rule and format the location in a way that mostIDEs will convert into a link to open the file at the line of the errorwhen clicked.
  • --minimumpriority - The rule priority threshold; rules with lowerpriority than they will not be used.
  • --reportfile - Sends the report output to the specified file,instead of the default output targetSTDOUT.
  • --suffixes - Comma-separated string of valid source code filenameextensions, e.g. php,phtml.
  • --exclude - Comma-separated string of patterns that are used to ignoredirectories. Use asterisks to exclude by pattern. For example*src/foo/*.php or*src/foo/*
  • --strict - Also report those nodes with a @SuppressWarnings annotation.
  • --ignore-errors-on-exit - will exit with a zero code, even on error.
  • --ignore-violations-on-exit - will exit with a zero code, even if anyviolations are found.
  • --cache - will enable the result cache. Will default to.phpmd.result-cache.php in thecurrent working directory.
  • --cache-file - in cooperation with--cache will override the default result cache file path of.phpmd.result-cache.php to the given file path.
  • --cache-strategy - sets the caching strategy to determine if a file is still fresh. Eithercontent to base it on the file contents, or timestamp to base it on the file modified timestamp.
  • --generate-baseline - will generate aphpmd.baseline.xml for existing violationsnext to the ruleset definition file. The file paths of the violations will be relative to the currentworking directory.
  • --update-baseline - will remove all violations from an existingphpmd.baseline.xmlthat no longer exist. New violations will _not_ be added. The file path of the violations will be relativeto the current working directory.
  • --baseline-file - the filepath to a custom baseline xml file. If absent willdefault tophpmd.baseline.xml
  • --color - enable color in output, for instance text rendererwill show rule name in yellow and error description in red.
  • --extra-line-in-excerpt - specify how many extra lines are added to a code snippet in html format

  An example command line:

  phpmd PHP/Depend/DbusUI xml codesize --reportfile "phpmd.xml" --suffixes "php,phtml"

  Options can be before or after arguments. They can be separated from their value either with a space or an equal (=) sign.Thus, the following syntax is equivalent to the previous one:

  phpmd --reportfile="phpmd.xml" --suffixes="php,phtml" PHP/Depend/DbusUI xml codesize

  Strings starting with- will be recognized as option names. If you have arguments starting with-, set optionsfirst, then use-- to mark the explicit start or the arguments list:

  phpmd --reportfile "phpmd.xml" --suffixes "php,phtml" -- -foo/Folder xml codesize

PHPMD uses so called rule sets that configure/define a set of rules which willbe applied against the source under test. The default distribution of PHPMD isalready shipped with a few default sets, that can be used out-of-box. You cancall PHPMD's cli tool with a set's name to apply this configuration:

~ $ phpmd /path/to/source text codesize

But what if you would like to apply more than one rule set against your source?You can also pass a list of rule set names, separated by comma to PHPMD's clitool:

~ $ phpmd /path/to/source text codesize,unusedcode,naming

You can also mix customrule set files with build-in rule sets:

~ $ phpmd /path/to/source text codesize,/my/rules.xml

That's it. With this behavior you can specify you own combination of rule setsthat will check the source code.

PHPMD also allows you to specify multiple source directories in case you wantto create one output for certain parts of your code

~ $ phpmd /path/to/code,index.php,/another/place/with/code text codesize

Or use glob pattern:

~ $ phpmd src/main/php/*/*/*{Renderer,Node}.php text my/rules.xml

PHPMD can also read the standard input stdin:

~ $ cat src/MyService.php | phpmd - text my/rules.xml

So the PHP code to be scanned may be generated by an other programnot necessarily to be store in file.

PHPMD's command line tool currently defines four different exit codes.

• 0, This exit code indicates that everything worked as expected. This meansthere was no error/exception and PHPMD hasn't detected any rule violationin the code under test.
• 1, This exit code indicates that an exception occurred which hasinterrupted PHPMD during execution.
• 2, This exit code means that PHPMD has processed the code under testwithout the occurrence of an error/exception, but it has detected ruleviolations in the analyzed source code. You can also prevent this behaviourwith the--ignore-violations-on-exit flag, which will result to a0even if any violations are found.

• 3, This exit code means that one or multiple files under test could not

  be processed because of an error. There may also be violations in otherfiles that could be processed correctly.

At the moment PHPMD comes with the following renderers:

• xml, which formats the report as XML.
• text, simple textual format.
• html, single HTML file with possible problems.
• json, formats JSON report.
• ansi, a command line friendly format.
• github, a format that GitHub Actions understands.
• gitlab, a format that GitLab CI understands.
• sarif, the Static Analysis Results Interchange Format.
• checkstyle, language and tool agnostic XML format

For existing projects a violation baseline can be generated. All violations in this baseline will be ignored in further inspections.

The recommended approach would be aphpmd.xml in the root of the project. To generate thephpmd.baseline.xml next to it:

~ $ phpmd /path/to/source text phpmd.xml --generate-baseline

To specify a custom baseline filepath for export:

~ $ phpmd /path/to/source text phpmd.xml --generate-baseline --baseline-file /path/to/source/phpmd.baseline.xml

By default PHPMD will look next tophpmd.xml forphpmd.baseline.xml. To overwrite this behaviour:

~ $ phpmd /path/to/source text phpmd.xml --baseline-file /path/to/source/phpmd.baseline.xml

To clean up an existing baseline file andonly remove no longer existing violations:

~ $ phpmd /path/to/source text phpmd.xml --update-baseline

Available as part of the Tidelift Subscription.

The maintainers ofPHPMD and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.Learn more.

If you want to contribute to PHPMD, please consult thecontribution guide.