PhpMetrics

Gives metrics about PHP project and classes.

Installation
Usage
Conditions of failure
IDE integration
Jenkins and CI
Configuration

Installation

As phar archive:

wget https://github.com/phpmetrics/PhpMetrics/raw/master/build/phpmetrics.phar
chmod +x phpmetrics.phar
mv phpmetrics.phar /usr/local/bin/phpmetrics

Then, if you need to update:

phpmetrics self-update

Or with Composer (Make sure you have ~/.composer/vendor/bin/ in your path):

php composer.phar global require 'phpmetrics/phpmetrics'

Usage

Do not hesitate to visit the official documentation.

The command command phpmetrics <folder or filename> will output:

If you want to get the summary HTML report (with charts):

phpmetrics --report-html=/path/of/your/choice.html <folder or filename>

No panic : you can read the How to read the HTML report page

If you need a pure string representation of the reports in StdOut, just use phpmetrics -q --report-xml=php://stdout <folder or filename>

## Compatibility

PhpMetrics can parse PHP code from PHP 5.3 to PHP 7.x.

I want to parse PHP7 code but I use PHP 5.x

You can parse PHP7 code, but your interpreter will detect syntax errors in your code. To prevent this, please use the --ignore-errors option.

Conditions of failure

Customizing the conditions of failure is very easy with the--failure-condition option. For example:

--failure-condition="average.maintainabilityIndex < 100 or sum.loc > 10000"

With this example, PhpMetrics script returns 1 if the average of Maintainability index is lower than 100 or if the total number of lines of code is greater than 10000.

You can also work with package:

--failure-condition="My/Package1/XXXX.average.bugs > 0.35"

Remember that in PhpMetrics packages are file oriented (and not object oriented).

Conditions are evaluated with the Hoa Ruler component. Available operators are and, or, xor, not, = (is as an alias), !=, >, >=, <, <=, in and sum

List of availables metrics is documented here.

## IDE integration

PhpMetrics plugin for PhpStorm

## Jenkins and CI

You'll find a complete tutorial in the documentation

You can easily export results to XML with the --report-xml option:

phpmetrics --report-xml=/path/of/your/choice.xml <folder or filename>

You can also export results as violations (MessDetector report), in XML format with the --violations-xml option:

phpmetrics --violations-xml=/path/of/your/choice.xml <folder or filename>

Configuration

Configuration options

--report-html - Path to save report in HTML format. Example: --report-html=/tmp/report.html
--report-xml - Path to save summary report in XML format. Example: --report-xml=/tmp/report.xml
--report-cli - Enable report in terminal.
--violations-xml - Path to save violations in XML format. Example: --violations-xml=/tmp/report.xml
--report-csv - Path to save summary report in CSV format. Example: --report-csv=/tmp/report.csv
--report-json - Path to save detailed report in JSON format. Example: --report-json=/tmp/report.json
--chart-bubbles - Path to save Bubbles chart, in SVG format. Example: --chart-bubbles=/tmp/chart.svg. Graphviz IS required
--level - Depth of summary report.
--extensions - Regex of extensions to include.
--excluded-dirs - Regex of subdirectories to exclude.
--symlinks - Enable following symlinks.
--without-oop - If provided, tool will not extract any information about OOP model (faster).
--failure-condition - Optional failure condition, in english. Example: --failure-condition="average.maintainabilityIndex < 50 or sum.loc > 10000"
--config - Config file (YAML). Example: --config=myconfig.yml
--template-title - Title for the HTML summary report.

A complete example command line:

phpmetrics --report-html=report.html --report-xml=report.xml --report-cli=true --violations-xml=violations.xml --report-csv=report.csv --report-json=report.json --chart-bubbles=chart.svg --level=3 --extensions=php|inc --excluded-dirs="cache|logs" --symlinks=true --without-oop=true --failure-condition="average.maintainabilityIndex < 50 or sum.loc > 10000" --template-title="My Report" /path/to/source

### Configuration file

You can customize configuration with the --config=<file> option.

The file should be a valid yaml file. For example:

# file <my-config.yml>
myconfig:
    # paths to explore
    path:
        extensions: php|inc
        exclude: Features|Tests|tests

    # report and violations files
    logging:
        report:
            xml:    ./log/phpmetrics.xml
            html:   ./log/phpmetrics.html
            csv:    ./log/phpmetrics.csv
        violations:
            xml:    ./log/violations.xml
        chart:
            bubbles: ./log/bubbles.svg

    # condition of failure
    failure: average.maintainabilityIndex < 50 or sum.loc > 10000

    # rules used for color ([ critical, warning, good ])
    rules:
      cyclomaticComplexity: [ 10, 6, 2 ]
      maintainabilityIndex: [ 0, 69, 85 ]
      [...]

Each rule is composed from three values.

If A < B < C : A: min, B: yellow limit, C: max
If A > B > C : A: max, B: yellow limit, C: min

You can save the configuration in a .phpmetrics.yml file in the root directory of your project. PhpMetrics will look for it and use it.

Contribute

In order to run unit tests, please install the dev dependencies:

curl -sS https://getcomposer.org/installer | php
php composer.phar install
gem install semver

Then, in order to run the test suite:

./vendor/bin/phpunit

Finally, build the phar:

make build

# Author

Jean-François Lépine <www.lepine.pro>

# License

See the LICENSE file.