Skip to content

Latest commit

 

History

History
231 lines (182 loc) · 18.9 KB

README.md

File metadata and controls

231 lines (182 loc) · 18.9 KB

Pdepend Summary Formatter

Pdepend Summary Formatter logo

Latest Stable Version Total Downloads PHP Version Require License

Pdepend Summary Formatter is a tool to show software code quality metrics, measured by PHP Depend (pdepend), in console for development and in CI/CD pipeline.

Table of contents

Installation

Pdepend Summary Formatter tool requires PHP >= 7.4, latest version of PHP Depend and Composer.

composer require --dev pdepend/pdepend:"^2.15"
composer require --dev andrey-tech/pdepend-summary-formatter-php

Generate a default config file pdepend-summary-formatter.yml.dist in current working directory:

./vendor/bin/pdepend-summary-formatter --init

Then run PHP Depend to scan your source PHP-code in directory src and generate an XML report in file summary.xml:

./vendor/bin/pdepend --summary-xml=summary.xml --suffix=php src

Then run Pdepend Summary Formatter tool to show code quality metrics, measured by PHP Depend, in console and to write results to specified text file summary.txt:

./vendor/bin/pdepend-summary-formatter summary.xml --output-file=summary.txt

Command line options

./vendor/bin/pdepend-summary-formatter <path to pdepend file summary.xml>

The Pdepend Summary Formatter tool command line interface also accepts the following optional arguments:

  • --init — Will generate a default config file pdepend-summary-formatter.yml.dist in current working directory.
  • --output-file= — Write results also to the specified text file.
  • --config-file= — The filepath to a custom config YAML file.
  • --ignore-red-metrics-on-exit — Will exit with a zero code, even "red" metrics exist.
  • --ignore-yellow-metrics-on-exit — Will exit with a zero code, even "yellow" metrics exist.
  • --no-colors — Disable colors in console.

An example command line of Pdepend Summary Formatter tool and PHP Depend tool:

./vendor/bin/pdepend --summary-xml=./var/summary.xml --suffix=php src,tests
./vendor/bin/pdepend-summary-formatter ./var/summary.xml --config-file=./pdepend-summary-formatter.yml --output-file=./var/summary.txt

An example of output text file summary.txt:

FILE: src/AndreyTech/Pdepend/Summary/Formatter/Colorizer.php
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
| CLASS                     | wmc | cbo | loc | cis | nom | npm | vars | dit | nocc |
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
| Colorizer                 | 15  | 0   | 117 | 4   | 8   | 4   | 3    | 0   | 0    |
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+
| METHOD                    | mi | ccn | ccn2 | crap0 | npath | loc | hb   | hd | hv  | he   | ht  | hi | hl  | hnd | hnt |
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+
| __construct               | 81 | 1   | 1    | 2     | 1     | 4   | 0.01 | 4  | 16  | 62   | 3   | 4  | 0.3 | 6   | 6   |
| getFgTagStats             | 82 | 1   | 1    | 2     | 1     | 4   | 0.01 | 8  | 12  | 93   | 5   | 1  | 0.1 | 5   | 5   |
| colorizeClassMetric       | 79 | 1   | 1    | 2     | 1     | 4   | 0.01 | 5  | 37  | 192  | 11  | 7  | 0.2 | 10  | 11  |
| colorizeMethodMetric      | 79 | 1   | 1    | 2     | 1     | 4   | 0.01 | 5  | 37  | 192  | 11  | 7  | 0.2 | 10  | 11  |
| colorize                  | 57 | 4   | 5    | 30    | 8     | 19  | 0.14 | 27 | 315 | 8517 | 473 | 12 | 0   | 32  | 63  |
| renderTemplate            | 59 | 3   | 3    | 12    | 4     | 17  | 0.09 | 14 | 320 | 4379 | 243 | 23 | 0.1 | 25  | 69  |
| updateFgTagStats          | 70 | 2   | 2    | 6     | 2     | 8   | 0.05 | 23 | 78  | 1813 | 101 | 3  | 0   | 13  | 21  |
| parseConfig               | 73 | 1   | 1    | 2     | 1     | 16  | 0.03 | 7  | 96  | 660  | 37  | 14 | 0.1 | 13  | 26  |
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+

+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+
| PROJECT             | min mi | avg mi | max mi | std mi | noc | nom | noi | nof | nop | loc  | lloc | ncloc |
+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+
| 2023-10-04T17:15:14 | 57     | 72     | 82     | 9      | 11  | 74  | 0   | 0   | 2   | 1376 | 501  | 1250  |
+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+

Software metrics

PHP Depend (pdepend) tool can generate a large set of software metrics from a given code base. These values can be used to measure the quality of a software project and they help to identify that parts of an application where a refactoring should be applied.

Pdepend Summary Formatter tool shows only the part of software metrics, measured by PHP Depend, and shows them in green, yellow and red colors in the console, according to boundaries for values, defined in configuration YAML file.

This table shows a list of the software metrics by Pdepend Summary Formatter tool for entire project, classes, traits, methods. The table also shows the default values for "red" boundaries of software metrics, based on PHP Mess Detector (PHPMD) tool.

Metric Description Project Class Trait Method
avg mi Average Maintainability Index 50
cbo Coupling Between Objects 13 13
ccn Cyclomatic Complexity Number 10
ccn2 Extended Cyclomatic Complexity Number 10
cis Class Interface Size 45 45
crap0 Change Risk Analysis and Predictions Index for 0% coverage 29
dit Depth of Inheritance Tree 6
hb Halstead Bugs
hd Halstead Difficulty
he Halstead Effort
hi Halstead Intelligence Content
hl Halstead Level
hnd Halstead Vocabulary
hnt Halstead Length
ht Halstead Programming Time
hv Halstead Volume
lloc Logical Lines Of Code
loc Lines Of Code 1000 100
max mi Maximum of Maintainability Index 50
mi Maintainability Index 50
min mi Minimum of Maintainability Index 50
nocc Number Of Child Classes 15
ncloc Non Comment Lines Of Code
noc Number Of Classes
nof Number Of Functions
noi Number Of Interfaces
nom Number Of Methods 25
npm Number of Public Methods 20 20
npath NPath Complexity 200
nop Number of Packages (namespaces)
std mi Standard deviation of Maintainability Index
vars Number of Properties 15 15
wmc Weighted Method Count 50 50

Note: ✓ — means there are no defined "red" color boundaries for this metric.

Configuration YAML file

By default Pdepend Summary Formatter tool is looking for following configuration YAML files is current working directory:

  • pdepend-summary-formatter.yml,
  • pdepend-summary-formatter.yml.dist.

Configuration YAML file allows to set color boundaries for values of software metrics.

Pdepend Summary Formatter tool currently defines three color boundaries:

Color Description
green Ok
yellow Warning
red Error

A white value means there are no defined color boundaries for this metric.

You can also add/set custom colors and styles. See How to Color and Style the Console Output in Symfony console.

Fragment of default configuration file:

  metrics:

    # Metrics of class
    class:

      # https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-class-coupling?view=vs-2022
      # https://phpmd.org/rules/design.html#couplingbetweenobjects
      # https://pdepend.org/documentation/software-metrics/coupling-between-objects.html
      cbo:
        green: [ 0, 13 ],
        red+bold: [ 14, null ]

    # Metrics of method
    method:

      # https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-cyclomatic-complexity?view=vs-2022
      # https://phpmd.org/rules/codesize.html#cyclomaticcomplexity
      ccn:
        green: [ 1, 7 ]
        yellow+bold: [ 8, 10 ]
        red+bold: [ 11, null ]

Exit codes

Pdepend Summary Formatter tool currently defines four different exit codes:

Code Description
0 This exit code indicates that everything worked as expected without "red" or "yellow" metrics.
1 This exit code indicates that an error/exception occurred which has interrupted tool during execution.
2 This exit code means that tool has processed the summary file without the occurrence of an error/exception with "red" metrics.
3 This exit code means that tool has processed the summary file without the occurrence of an error/exception with "yellow" metrics.

Authors and Maintainers

The author and maintainer of Pdepend Summary Formatter tool is andrey-tech.

License

This tool is licensed under the MIT license.