PHPackages                             jcvviljoen/php-stability-metrics - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. jcvviljoen/php-stability-metrics

ActiveLibrary[Utility & Helpers](/categories/utility)

jcvviljoen/php-stability-metrics
================================

PHP tool to calculate architecture stability metrics based on clean architecture principles

0.2.1(1mo ago)54.1k↑38.5%[2 issues](https://github.com/jcvviljoen/php-stability-metrics/issues)[5 PRs](https://github.com/jcvviljoen/php-stability-metrics/pulls)MITPHPPHP ^8.4CI passing

Since Aug 15Pushed 3w ago1 watchersCompare

[ Source](https://github.com/jcvviljoen/php-stability-metrics)[ Packagist](https://packagist.org/packages/jcvviljoen/php-stability-metrics)[ RSS](/packages/jcvviljoen-php-stability-metrics/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (10)Versions (30)Used By (0)

Stability
=========

[](#stability)

#### PHP Stable Dependency Metrics Analyser

[](#php-stable-dependency-metrics-analyser)

[![Project's current stability result](stability-result-2024-08-27.png)](stability-result-2024-08-27.png)

Overview
--------

[](#overview)

***Stability*** is a PHP-based tool designed to analyse and calculate the stability of software components in your architecture.

It leverages clean architecture principles and stable dependency metrics to provide insights into the maintainability and robustness of your codebase.

Stability is a nod to the [Stable Dependency Principle](CLEAN_ARCHITECTURE.md#2-stable-dependencies-principle-sdp)and the [Stable Dependency Metrics](#stable-dependency-metrics), where we are actually measuring ***Instability***.

The goal is to identify components that are either too abstract or too unstable.

### Why use Stability?

[](#why-use-stability)

Stability can help you identify components that are either overly complex (too abstract) or too tightly coupled (too unstable).

By monitoring the metrics of your components as your project continues to develop, you can detect areas in your codebase / architecture that may need refactoring early on.

This can help you improve the maintainability and robustness of your codebase, while also making it easier to understand. These metrics can also be used to guide your development process, and to convince stakeholders of the need for improvement.

Installation
------------

[](#installation)

To install the package, use Composer to include it as a dev-dependency:

```
composer require --dev jcvviljoen/stability
```

Usage
-----

[](#usage)

To calculate the stability of your components, run the following command:

```
php vendor/bin/stability
```

Various arguments are also supported (don't worry, any invalid setup will guide you through the process anyway):

- `-i, --init`: Initialize the configuration file
- `--config`: Specify a custom configuration file / path
- `--debug`: Enable debug output (exposes exception stack traces)

For example, you can specify a custom configuration file (as long as it is a supported format):

```
php vendor/bin/stability --config "path/to/config.php"
```

### Configuration fields

[](#configuration-fields)

There are various configuration fields that you can use to customise the analysis, all of which is explained in the [sample configuration file](stability.php.sample).

You can do the following:

- Specify the main application source to scan.
- Define the components within the application you want to analyse.
- For each component, you can also:
    - Exclude specific files / directories from being scanned.
    - Threshold for crossing into the zone of pain (*defaults to 0.7 when not specified*).
    - Threshold for crossing into the zone of uselessness (*defaults to 0.7 when not specified*).

### Be Creative

[](#be-creative)

You don't have to restrict yourself to only one application source. You can also analyse your project at a higher (or lower) level of granularity!

**For example**, let's consider a modular monolith. You can:

- Analyse the entire application to see how the modules interact;
- Analyse each module to see how the layers within the module interact; or
- Analyse a domain within a layer to see how the classes within the domain interact.

Should you find something interesting or would like to analyse something specific, please share or contribute!

Features
--------

[](#features)

- **Component Parsing**: Parses class and modules into components as specified by your configuration.
- **Stability Calculation**: Computes metrics such as abstractness, instability, and distance from the main sequence (DMS).
- **Output Results**: Outputs the calculated stability results for further ( *manual\** ) analysis.

\* See the [Roadmap](ROADMAP.md) for potential future features.

Stable Dependency Metrics
-------------------------

[](#stable-dependency-metrics)

Stability uses the following metrics to evaluate the stability of components:

**Abstractness (A)**

Measures the ratio of abstract classes and interfaces to the total number of classes. A higher value indicates more abstract components.

**Instability (I)**

Measures the ratio of outgoing dependencies to the total number of dependencies. A higher value indicates more unstable components (i.e. components that are hard to change due to their high number of dependencies).

**Distance from the Main Sequence (DMS)**

Combines abstractness and instability to determine how far a component is from the ideal balance of being abstract and stable.

You can read more about the principles being applied in the [CLEAN\_ARCHITECTURE](CLEAN_ARCHITECTURE.md) file.

Contributing
------------

[](#contributing)

Contributions are welcome!

Please see the [CONTRIBUTING](.github/CONTRIBUTING.md) file for more information.

License
-------

[](#license)

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

Credits & References
------------------------

[](#credits--references)

This project is largely inspired by the work of [Robert C. Martin](https://en.wikipedia.org/wiki/Robert_C._Martin), who introduced the concept of stable dependency metrics in his book "[Clean Architecture](https://www.google.nl/books/edition/Clean_Architecture/uGE1DwAAQBAJ?hl=en)".

Also, shout out to [Sergio Rodríguez](https://github.com/serodriguez68) for a good summary of the book that can be found [here](https://github.com/serodriguez68/clean-architecture).

And lastly, thanks to [Thiago Cordeiro](https://github.com/thiagocordeiro) for his mentorship and guidance in the development of this project.

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance85

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~58 days

Recently: every ~80 days

Total

12

Last Release

45d ago

PHP version history (3 changes)0.0.1PHP ^8.3

0.0.6PHP ^8.3|^8.4

0.1.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/9bb3590e59d4fe678786259394c86a83d1959eeb32dd771bfb2f6d5f0331b63b?d=identicon)[jcvviljoen](/maintainers/jcvviljoen)

---

Top Contributors

[![jcviljoen](https://avatars.githubusercontent.com/u/102794323?v=4)](https://github.com/jcviljoen "jcviljoen (102 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (62 commits)")[![jcvviljoen](https://avatars.githubusercontent.com/u/21276558?v=4)](https://github.com/jcvviljoen "jcvviljoen (52 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (17 commits)")

---

Tags

phpMetricscleanarchitecturestability

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jcvviljoen-php-stability-metrics/health.svg)

```
[![Health](https://phpackages.com/badges/jcvviljoen-php-stability-metrics/health.svg)](https://phpackages.com/packages/jcvviljoen-php-stability-metrics)
```

###  Alternatives

[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

103519.9k53](/packages/friendsoftypo3-content-blocks)[phel-lang/phel-lang

Phel is a functional programming language that compiles to PHP

5186.0k18](/packages/phel-lang-phel-lang)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)