Skip to content

Commit 07e242c

Browse files
andrey-techandrey-tech
committed
Add README.md, fix errors
1 parent 73f4e05 commit 07e242c

File tree

4 files changed

+258
-26
lines changed

4 files changed

+258
-26
lines changed

‎README.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Pdepend Summary Formatter
2+
3+
![Pdepend Summary Formatter logo](./assets/pdepend-summary-formatter-logo.png)
4+
5+
[![Latest Stable Version](https://poser.pugx.org/andrey-tech/pdepend-summary-formatter-php/v)](https://packagist.org/packages/andrey-tech/pdepend-summary-formatter-php)
6+
[![PHP Version Require](http://poser.pugx.org/andrey-tech/pdepend-summary-formatter-php/require/php)](https://packagist.org/packages/andrey-tech/pdepend-summary-formatter-php)
7+
[![License](https://poser.pugx.org/andrey-tech/pdepend-summary-formatter-php/license)](https://packagist.org/packages/andrey-tech/pdepend-summary-formatter-php)
8+
9+
Pdepend Summary Formatter is a tool to show software code quality metrics, measured by
10+
[PHP Depend](https://github.com/pdepend/pdepend) (pdepend),
11+
in console for development and in CI/CD.
12+
13+
## Table of contents
14+
<!-- MarkdownTOC levels="1,2,3,4,5,6" autoanchor="true" autolink="true" -->
15+
16+
- [Installation](#installation)
17+
- [Command line options](#command-line-options)
18+
- [Software metrics](#software-metrics)
19+
- [Configuration YAML file](#configuration-yaml-file)
20+
- [Exit codes](#exit-codes)
21+
- [Authors and Maintainers](#authors-and-maintainers)
22+
- [License](#license)
23+
24+
<!-- /MarkdownTOC -->
25+
26+
<a id="installation"></a>
27+
## Installation
28+
29+
Pdepend Summary Formatter tool requires **PHP >= 7.4**,
30+
latest version of [PHP Depend](https://github.com/pdepend/pdepend)
31+
and [Composer](https://getcomposer.org/).
32+
33+
```shell
34+
composer require --dev pdepend/pdepend:"^2.15"
35+
composer require --dev andrey-tech/pdepend-summary-formatter-php
36+
```
37+
38+
Generate a default config file `pdepend-summary-formatter.yaml.dist` in current working directory:
39+
40+
```shell
41+
./vendor/bin/pdepend-summary-formatter --init
42+
```
43+
44+
Then run `PHP Depend` to scan your source PHP-code in directory `src` and generate an XML report in file `summary.xml`:
45+
46+
```shell
47+
./vendor/bin/pdepend --summary-xml=summary.xml --suffix=php src
48+
```
49+
50+
Then run Pdepend Summary Formatter tool to show code quality metrics,
51+
measured by PHP Depend, in console and write results to specified text file `summary.txt`:
52+
53+
```shell
54+
./vendor/bin/pdepend-summary-formatter summary.xml --output-file=summary.txt
55+
```
56+
57+
<a id="command-line-options"></a>
58+
## Command line options
59+
60+
```shell
61+
./vendor/bin/pdepend-summary-formatter <path to pdepend file summary.xml>
62+
```
63+
64+
The command line interface also accepts the following optional arguments:
65+
66+
- `--init` - Will generate a default config file `pdepend-summary-formatter.yaml.dist` in current working directory.
67+
- `--output-file=` - Write results also to the specified text file.
68+
- `--config-file=` - The filepath to a custom config YAML file.
69+
- `--no-colors` - Disable colors in console.
70+
71+
An example command line of Pdepend Summary Formatter tool and PHP Depend tool:
72+
73+
```shell
74+
./vendor/bin/pdepend --summary-xml=./var/summary.xml --suffix=php src,tests
75+
./vendor/bin/pdepend-summary-formatter ./var/summary.xml --config-file=./pdepend-sf.yaml --output-file=./var/summary.txt
76+
```
77+
78+
An example of output file `summary.txt`:
79+
80+
```text
81+
FILE: src/AndreyTech/Pdepend/Summary/Formatter/Colorizer.php
82+
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
83+
| CLASS | wmc | cbo | loc | cis | nom | npm | vars | dit | nocc |
84+
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
85+
| Colorizer | 15 | 0 | 117 | 4 | 8 | 4 | 3 | 0 | 0 |
86+
+---------------------------+-----+-----+-----+-----+-----+-----+------+-----+------+
87+
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+
88+
| METHOD | mi | ccn | ccn2 | crap0 | npath | loc | hb | hd | hv | he | ht | hi | hl | hnd | hnt |
89+
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+
90+
| __construct | 81 | 1 | 1 | 2 | 1 | 4 | 0.01 | 4 | 16 | 62 | 3 | 4 | 0.3 | 6 | 6 |
91+
| getFgTagStats | 82 | 1 | 1 | 2 | 1 | 4 | 0.01 | 8 | 12 | 93 | 5 | 1 | 0.1 | 5 | 5 |
92+
| colorizeClassMetric | 79 | 1 | 1 | 2 | 1 | 4 | 0.01 | 5 | 37 | 192 | 11 | 7 | 0.2 | 10 | 11 |
93+
| colorizeMethodMetric | 79 | 1 | 1 | 2 | 1 | 4 | 0.01 | 5 | 37 | 192 | 11 | 7 | 0.2 | 10 | 11 |
94+
| colorize | 57 | 4 | 5 | 30 | 8 | 19 | 0.14 | 27 | 315 | 8517 | 473 | 12 | 0 | 32 | 63 |
95+
| renderTemplate | 59 | 3 | 3 | 12 | 4 | 17 | 0.09 | 14 | 320 | 4379 | 243 | 23 | 0.1 | 25 | 69 |
96+
| updateFgTagStats | 70 | 2 | 2 | 6 | 2 | 8 | 0.05 | 23 | 78 | 1813 | 101 | 3 | 0 | 13 | 21 |
97+
| parseConfig | 73 | 1 | 1 | 2 | 1 | 16 | 0.03 | 7 | 96 | 660 | 37 | 14 | 0.1 | 13 | 26 |
98+
+---------------------------+----+-----+------+-------+-------+-----+------+----+-----+------+-----+----+-----+-----+-----+
99+
100+
+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+
101+
| PROJECT | min mi | avg mi | max mi | std mi | noc | nom | noi | nof | nop | loc | lloc | ncloc |
102+
+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+
103+
| 2023-10-04T17:15:14 | 57 | 72 | 82 | 9 | 11 | 74 | 0 | 0 | 2 | 1376 | 501 | 1250 |
104+
+---------------------+--------+--------+--------+--------+-----+-----+-----+-----+-----+------+------+-------+
105+
```
106+
107+
<a id="software-metrics"></a>
108+
## Software metrics
109+
110+
[PHP Depend](https://pdepend.org/) (pdepend) tool can generate a large set of [software metrics](https://pdepend.org/documentation/software-metrics/index.html)
111+
from a given code base, these values can be used to measure the quality of a software project
112+
and they help to identify that parts of an application where a refactoring should be applied.
113+
114+
Pdepend Summary Formatter tool shows only part of software metrics, measured by PHP Depend,
115+
and colors them (green, yellow, red) in the console according to boundaries for values,
116+
established in configuration YAML file.
117+
118+
This table give a list of the software metrics, shows by Depend Summary Formatter tool
119+
for entire project, classes, traits, methods,
120+
and default values for red boundaries, based on [PHP Mess Detector](https://phpmd.org/) (PHPMD) tool.
121+
122+
| Metric | Description | Project | Class | Trait | Method |
123+
|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-------|-------|--------|
124+
| avg mi | Average [Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning?view=vs-2022) | ✓ | | | |
125+
| cbo | [Coupling Between Objects](https://phpmd.org/rules/design.html#couplingbetweenobjects) | | 13 | 13 | |
126+
| ccn | [Cyclomatic Complexity Number](https://phpmd.org/rules/codesize.html#cyclomaticcomplexity) | | | | 10 |
127+
| ccn2 | [Extended Cyclomatic Complexity Number](https://stackoverflow.com/questions/27954015/cyclomatic-complexity-and-variants) | | | | 10 |
128+
| cis | [Class Interface Size](https://phpmd.org/rules/codesize.html#excessivepubliccount) | | 45 | 45 | |
129+
| crap0 | [Change Risk Analysis and Predictions Index](https://www.artima.com/weblogs/viewpost.jsp?thread=210575) for 0% coverage | | | | 29 |
130+
| dit | [Depth of Inheritance Tree](https://phpmd.org/rules/design.html#depthofinheritance) | | 6 | | |
131+
| hb | [Halstead Bugs](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | 0.19 |
132+
| hd | [Halstead Difficulty](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | 20 |
133+
| he | [Halstead Effort](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | 5000 |
134+
| hi | [Halstead Intelligence Content](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | ✓ |
135+
| hl | [Halstead Level](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | ✓ |
136+
| hnd | [Halstead Vocabulary](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | ✓ |
137+
| hnt | [Halstead Length](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | ✓ |
138+
| ht | [Halstead Programming Time](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | ✓ |
139+
| hv | [Halstead Volume](https://en.wikipedia.org/wiki/Halstead_complexity_measures) | | | | 500 |
140+
| lloc | Logical Lines Of Code | ✓ | | | |
141+
| loc | [Lines Of Code](https://phpmd.org/rules/codesize.html#excessivemethodlength) | | 1000 | | 100 |
142+
| max mi | Maximum of [Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning?view=vs-2022) | ✓ | | | |
143+
| mi | [Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning?view=vs-2022) | | | | 50 |
144+
| min mi | Minimum of [Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning?view=vs-2022) | ✓ | | | |
145+
| nocc | [Number Of Child Classes](https://phpmd.org/rules/design.html#numberofchildren) | | 15 | | |
146+
| ncloc | Non Comment Lines Of Code | ✓ | | | |
147+
| noc | Number Of Classes | ✓ | | | |
148+
| nof | Number Of Functions | ✓ | | | |
149+
| noi | Number Of Interfaces | ✓ | | | |
150+
| nom | [Number Of Methods](https://phpmd.org/rules/codesize.html#toomanymethods) | | 25 | | |
151+
| npm | [Number of Public Methods](https://phpmd.org/rules/codesize.html#toomanypublicmethods) | | 10 | 10 | |
152+
| npath | [NPath Complexity](https://phpmd.org/rules/codesize.html#npathcomplexity) | | | | 200 |
153+
| nop | Number of Packages (namespaces) | ✓ | | | |
154+
| std mi | [Standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of [Maintainability Index](https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-maintainability-index-range-and-meaning?view=vs-2022) | ✓ | | | |
155+
| vars | [Number of Properties](https://phpmd.org/rules/codesize.html#toomanyfields) | | 15 | 15 | |
156+
| wmc | [Weighted Method Count](https://phpmd.org/rules/codesize.html#excessiveclasscomplexity) | | 50 | 50 | |
157+
158+
Note: ✓ - means there are no defined color boundaries for this metric.
159+
160+
<a id="configuration-yaml-file"></a>
161+
## Configuration YAML file
162+
163+
By default Pdepend Summary Formatter search following configuration YAML files is current working directory:
164+
- `pdepend-summary-formatter.yaml`,
165+
- `pdepend-summary-formatter.yaml.dist`.
166+
167+
Configuration YAML file allow to set color boundaries for values of software metrics.
168+
169+
Pdepend Summary Formatter tool currently defines three color boundaries:
170+
171+
| Color | Description |
172+
|----------|-------------|
173+
| `green` | Ok |
174+
| `yellow` | Warning |
175+
| `red` | Error |
176+
177+
A white value means there are no defined color boundaries for this metric.
178+
179+
> You can also add/set custom colors and options.
180+
> See [How to Color and Style the Console Output](https://symfony.com/doc/current/console/coloring.html) in Symfony console.
181+
182+
Fragment of default configuration file:
183+
```yaml
184+
metrics:
185+
186+
# Metrics of class
187+
class:
188+
189+
# https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-class-coupling?view=vs-2022
190+
# https://phpmd.org/rules/design.html#couplingbetweenobjects
191+
# https://pdepend.org/documentation/software-metrics/coupling-between-objects.html
192+
cbo:
193+
green: [ 0, 13 ],
194+
red+bold: [ 14, null ]
195+
196+
# Metrics of method
197+
method:
198+
199+
# https://learn.microsoft.com/en-us/visualstudio/code-quality/code-metrics-cyclomatic-complexity?view=vs-2022
200+
# https://phpmd.org/rules/codesize.html#cyclomaticcomplexity
201+
ccn:
202+
green: [ 1, 7 ]
203+
yellow+bold: [ 8, 10 ]
204+
red+bold: [ 11, null ]
205+
```
206+
207+
<a id="exit-codes"></a>
208+
## Exit codes
209+
210+
Pdepend Summary Formatter tool currently defines four different exit codes:
211+
212+
| Code | Description |
213+
|------|-----------------------------------------------------------------------------------------------------------------------------------------|
214+
| 0 | This exit code indicates that everything worked as expected, no "red" or "yellow" metrics exist. |
215+
| 1 | This exit code indicates that an exception occurred which has interrupted tool during execution. |
216+
| 2 | This exit code means that tool has processed the summary file without the occurrence of an error/exception, but "red" metrics exist. |
217+
| 3 | This exit code means that tool has processed the summary file without the occurrence of an error/exception, but "yellow" metrics exist. |
218+
219+
<a id="authors-and-maintainers"></a>
220+
## Authors and Maintainers
221+
222+
The author and maintainer of Pdepend Summary Formatter tool is [andrey-tech](https://github.com/andrey-tech).
223+
224+
<a id="license"></a>
225+
## License
226+
227+
This tool is licensed under the [MIT license](./LICENSE).

‎assets/pdepend-summary-formatter-logo.png‎

53.4 KB
Loading

0 commit comments

Comments
 (0)