PHPackages togishima/php-coupling - 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. [Testing & Quality](/categories/testing) 4. / 5. togishima/php-coupling ActiveLibrary[Testing & Quality](/categories/testing) togishima/php-coupling ====================== A tool to visualize design quality in PHP projects by analyzing coupling strength and distance. 22PHPCI passing Since Dec 21Pushed 6mo agoCompare [ Source](https://github.com/togishima/php-coupling)[ Packagist](https://packagist.org/packages/togishima/php-coupling)[ RSS](/packages/togishima-php-coupling/feed)WikiDiscussions main Synced today READMEChangelog (1)DependenciesVersions (1)Used By (0) php-coupling βš–οΈ =============== [](#php-coupling-️) [![Packagist](https://camo.githubusercontent.com/072ad4f539f68f482ef728b582fe5fdfaadbd366531ff477a7e4ea46a1911a6c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f67697368696d612f7068702d636f75706c696e673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/072ad4f539f68f482ef728b582fe5fdfaadbd366531ff477a7e4ea46a1911a6c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746f67697368696d612f7068702d636f75706c696e673f7374796c653d666c61742d737175617265)[![CI](https://github.com/togishima/php-coupling/actions/workflows/ci.yml/badge.svg)](https://github.com/togishima/php-coupling/actions/workflows/ci.yml/badge.svg) A tool to measure **"Balanced Coupling"** in PHP projects, inspired by [cargo-coupling](https://github.com/nwiizo/cargo-coupling). This tool identifying problematic structural patterns by combining **Coupling Strength**, **Domain Distance**, and **Change Volatility** into a single, actionable **Balance Score**. πŸš€ Key Features -------------- [](#-key-features) - **High-Performance Parallel Engine**: Utilizes a worker pool architecture to parse thousands of files in parallel, delivering results in seconds. - **Scalable by Design**: Optional SQLite-backed persistence layer handles massive codebases (100k+ files) with a low memory footprint. - **Deep Scoring Logic**: - **Internal Awareness**: Distinguishes between intentional cross-layer dependencies (e.g., Application β†’ Domain) and external library leaks. - **Volatility Impact**: Integrates with Git to identify **active hotspots**. Recent changes weigh more heavily than historical technical debt. - **Premium CLI Experience**: Dashboard-like output with color-coded grades (A-F), progress bars, and issue categorization (Critical vs. Warning). - **Automation Ready**: First-class support for Markdown reporting and CI quality gates (exit codes based on custom thresholds). - **Clean Architecture**: Built following strict Clean Architecture principles, serving as a Grade-A example of its own methodology. 🐳 Docker Usage (Recommended) ---------------------------- [](#-docker-usage-recommended) Run without installing PHP locally: ``` docker run --rm -v $(pwd):/app ghcr.io/togishima/php-coupling:latest src ``` πŸ›  Installation -------------- [](#-installation) Requirements: **PHP 8.1+** ### Via Composer (Recommended for development) [](#via-composer-recommended-for-development) ``` composer require --dev togishima/php-coupling vendor/bin/php-coupling src ``` > **Note:** This tool is intended for development and CI use. Install with `--dev` to avoid including it in production dependencies. ### Via PHAR (Single Binary) [](#via-phar-single-binary) Download and run the latest PHAR: ``` curl -sSL https://github.com/togishima/php-coupling/releases/latest/download/php-coupling.phar -o php-coupling.phar chmod +x php-coupling.phar ./php-coupling.phar src ``` πŸ“Š Usage ------- [](#-usage) ``` # Standard analysis php-coupling src # For massive projects php-coupling src --disk --workers=8 # Compact reporting (Abbreviated namespaces) php-coupling src --short ``` ### Advanced Options [](#advanced-options) FlagDescription`--disk`Use SQLite Disk Repository for massive projects.`--workers=N`Customize the number of worker processes (default: 4).`--short`Enable intelligent namespace abbreviation (e.g., `P\I\ClassName`).`--format=markdown`Output report in Markdown format for PR comments or documentation.`--threshold=N`Set minimum required Overall Balance Score (0.0-1.0).`--fail-on-critical`Exit with error code if any Grade D or F issues are found.πŸ€– CI/CD Integration ------------------- [](#-cicd-integration) Enforce architectural standards in your automated pipelines: ``` # Fail if score < 0.8 or if any D/F grades exist docker run --rm -v $(pwd):/app ghcr.io/togishima/php-coupling:latest src --threshold=0.8 --fail-on-critical ``` 🧠 Understanding the Balance Score --------------------------------- [](#-understanding-the-balance-score) The **Balance Score (0.0 - 1.0)** is calculated as: `Balance = Alignment * VolatilityImpact` ### 1. Alignment (Distance vs. Strength) [](#1-alignment-distance-vs-strength) We follow the **Stable Dependencies Principle**: dependencies should follow the direction of stability. - **Good**: Strong coupling (Inheritance) between near classes; Weak coupling (Type hints) between distant classes. - **Bad**: Strong coupling (Inheritance) between distant layers (e.g., Domain extending Infrastructure). ### 2. Distance Normalization [](#2-distance-normalization) - **Same Namespace**: Near (0.25) - **Cross-Layer (Internal)**: Medium (0.75) - **External Library**: Far (1.00) ### 3. Volatility Impact [](#3-volatility-impact) A problematic coupling in a file that hasn't changed in years is "dead debt." We prioritize **active hotspots**β€”areas of the code that are both poorly aligned and frequently modified. πŸ— Architecture -------------- [](#-architecture) The project is a showcase of Clean Architecture: - **Domain**: Core scoring rules and level definitions. - **Application**: Use-case orchestration and parallel execution logic. - **Infrastructure**: Git providers, SQLite repositories, and AST visitors. - **Presentation**: Flexible `ReporterInterface` with Console and Markdown implementations. πŸ“œ License --------- [](#-license) MIT ### Health Score 17 β€” LowBetter than 6% of packages Maintenance47 Moderate activity, may be stable Popularity5 Limited adoption so far Community2 Small or concentrated contributor base Maturity13 Early-stage or recently created project 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. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/65173657?v=4)[Takashi Ogishima](/maintainers/togishima)[@togishima](https://github.com/togishima) ### Embed Badge ![Health badge](/badges/togishima-php-coupling/health.svg) ``` [![Health](https://phpackages.com/badges/togishima-php-coupling/health.svg)](https://phpackages.com/packages/togishima-php-coupling) ``` ### Alternatives [dms/phpunit-arraysubset-asserts This package provides ArraySubset and related asserts once deprecated in PHPUnit 8 14429.2M361](/packages/dms-phpunit-arraysubset-asserts) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)