README

A tool to measure "Balanced Coupling" in PHP projects, inspired by 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

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)

Run without installing PHP locally:

docker run --rm -v $(pwd):/app ghcr.io/togishima/php-coupling:latest src

🛠 Installation

Requirements: PHP 8.1+

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)

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

# Standard analysis
php-coupling src

# For massive projects
php-coupling src --disk --workers=8

# Compact reporting (Abbreviated namespaces)
php-coupling src --short

Advanced Options

Flag	Description
`--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

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

The Balance Score (0.0 - 1.0) is calculated as: Balance = Alignment * VolatilityImpact

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

Same Namespace: Near (0.25)
Cross-Layer (Internal): Medium (0.75)
External Library: Far (1.00)

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

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

MIT

togishima / php-coupling

Maintainers

Package info

Statistics

Security