README

PHP command-line dependency analyzer. Extracts and visualizes all class relationships in a project: inheritance, interfaces, traits, injections, instantiations, static calls, docblocks.

Installation

git clone <repo>
cd php-dep
composer install
chmod +x bin/php-dep

For global access:

ln -s /absolute/path/to/bin/php-dep /usr/local/bin/php-dep

Quick start

# Analyze the current directory
./bin/php-dep analyze

# Analyze a specific project
./bin/php-dep analyze /path/to/project/src

# JSON output (for scripts, CI, jq…)
./bin/php-dep analyze src/ --format=json -q

# Zoom in on a class
./bin/php-dep analyze src/ --class='App\Service\UserService'

analyze command

php-dep analyze [<path>] [options]

<path> is optional, defaults to .

Options

Exit codes

Examples

Project overview

./bin/php-dep analyze src/

Displays a table with, for each class: type, number of outgoing dependencies (what it uses), incoming dependencies (what uses it), and source file.

Find the most coupled classes

# Highest dependency consumers
./bin/php-dep analyze src/ --sort=deps --limit=10

# Most used by others (high fan-in)
./bin/php-dep analyze src/ --sort=fanin --limit=10

Inspect a class

./bin/php-dep analyze src/ --class='PhpDep\Parser\PhpFileParser' -v

Displays two tables: what the class uses (outgoing dependencies) and who uses it (incoming dependencies), with the relationship type and source line.

JSON pipeline with jq

# Count classes
./bin/php-dep analyze src/ -f json -q | jq '.meta.class_count'

# List all inheritance relationships
./bin/php-dep analyze src/ -f json -q | jq '[.edges[] | select(.type == "extends")]'

# Find classes with no dependants (leaves)
./bin/php-dep analyze src/ -f json -q | jq '[.classes[] | select(.dependants | length == 0) | .fqcn]'

# Find dependencies of a specific class
./bin/php-dep analyze src/ -f json -q | jq '.classes[] | select(.fqcn == "App\\Service\\UserService") | .dependencies'

Exclude directories

./bin/php-dep analyze . --exclude=tests --exclude=fixtures --exclude=migrations

Analysis without vendor

By default, vendor/ is excluded from the analysis but third-party classes appear as external nodes in the graph. No additional option is needed to ignore them entirely.

To analyze the vendor itself:

./bin/php-dep analyze . --include-vendor

JSON output structure

{
  "meta": {
    "version": "1.0",
    "generated_at": "2026-02-26T10:00:00+00:00",
    "analyzed_path": "/path/to/project",
    "file_count": 42,
    "class_count": 38,      // internal nodes only
    "node_count": 95,       // internal + external (vendor, built-in)
    "edge_count": 312,
    "warning_count": 2
  },
  "classes": [
    {
      "fqcn": "App\\Service\\UserService",
      "type": "class",      // class | interface | trait | enum
      "file": "/path/to/UserService.php",
      "line": 12,
      "dependencies": ["App\\Repository\\UserRepository", "Psr\\Log\\LoggerInterface"],
      "dependants":   ["App\\Controller\\UserController"]
    }
  ],
  "edges": [
    {
      "source":     "App\\Service\\UserService",
      "target":     "App\\Repository\\UserRepository",
      "type":       "param_type",   // see relationship types below
      "confidence": "certain",      // certain | high | medium | low
      "file":       "/path/to/UserService.php",
      "line":       23,
      "metadata":   {}
    }
  ],
  "warnings": [
    {
      "type":    "dynamic_instantiation",
      "file":    "/path/to/Factory.php",
      "line":    45,
      "message": "Dynamic instantiation: new $variable()"
    }
  ]
}

Relationship types (edge.type)

Tier 1 — Maximum certainty (AST)

Tier 2 — High confidence (docblocks)

Extracted from @param, @return, @var, @throws. Confidence: high.

Confidence levels

Warnings

Warnings are printed to stderr. The JSON output includes them in warnings[]. With -v, the text output lists them at the end of the report.

How it works

• Discovery: git ls-files if inside a git repository, otherwise RecursiveDirectoryIterator. The vendor/, node_modules/, and .git/ directories are excluded by default.
• Parsing: nikic/PHP-Parser v5. The NameResolver runs first in the traverser: all downstream names are resolved FQCNs.
• Docblocks: phpstan/phpdoc-parser for @param, @return, @var, @throws.
• Memory: each file's AST is freed immediately after extraction (streaming). Only one AST in memory at a time.
• Vendor: in boundary mode (default), vendor classes are external nodes (leaves) — their files are not analyzed.

Requirements

• PHP >= 8.2
• Composer