---
name: php-deptrac
description: Guidelines for analyzing, defining, and enforcing PHP architectural rules using Deptrac.
compatibility: opencode
---

# PHP Architecture Enforcement with Deptrac

This skill provides a workflow for maintaining clean architecture in PHP projects using Deptrac.

## Workflow

### 1. Setup & Installation
- Check if `deptrac/deptrac` is present in `composer.json`.
- If not installed, suggest: `composer require --dev deptrac/deptrac`.
- Ensure `vendor/bin/deptrac` is executable.

### 2. Configuration & Layer Definition
- **Initialization**: Use `vendor/bin/deptrac init` to generate a template if no config exists.
- **Config File**: Work with `deptrac.yaml` (or `deptrac.php`).
- **Defining Layers**: 
    - Identify logical layers (e.g., `Domain`, `Application`, `Infrastructure`, `UI`).
    - Use collectors to map namespaces or directories to these layers.
- **Defining Rules**:
    - Establish allowed dependencies (e.g., `Application` can depend on `Domain`, but `Domain` cannot depend on `Application`).
    - Forbid direct dependency between siblings if required.

### 3. Analysis & Violation Handling
- **Run Analysis**: Execute `vendor/bin/deptrac analyse`.
- **Interpret Results**:
    - Analyze the violation report to identify which class is breaking which rule.
    - Check the source code to determine if it's a legitimate architectural leak or a misconfiguration.
- **Correction**:
    - Refactor the code to remove the illegal dependency (Preferred).
    - Adjust the rules in `deptrac.yaml` if the architecture has evolved.
    - Use baselines (`deptrac.baseline.yaml`) for legacy code that cannot be fixed immediately.

### 4. Integration & Verification
- Ensure Deptrac is part of the CI pipeline or local linting process.
- Run `vendor/bin/deptrac` as a final check before completing architectural refactoring tasks.