php-dep

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

Option	Shortcut	Description
--format=text|json	-f	Output format (default: text)
--class=FQCN	-c	Focus on a class (full FQCN)
--sort=alpha|deps|fanin	-s	Table sort: alphabetical, number of outgoing dependencies, number of incoming dependencies (default: alpha)
--limit=N	-l	Limit output to N classes
--exclude=dir		Exclude a directory (can be used multiple times)
--include-vendor		Include the vendor/ directory in the analysis
--skip-docblocks		Ignore @param/@return/@throws annotations
--quiet	-q	Suppresses the progress bar and warnings (stdout preserved)
--verbose	-v	Show warning details

Exit codes

Code	Meaning
0	Success
1	Parsing error(s)
2	Internal error
3	Invalid arguments

---

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)

Type	Description
extends	Class or interface inheritance
implements	Interface implementation
uses_trait	Trait usage
param_type	Type hint on a method parameter
return_type	Method return type
property_type	Class property type
instantiates	new Foo()
static_call	Foo::method()
static_property	Foo::$prop
const_access	Foo::CONST
instanceof	$x instanceof Foo
catches	catch (FooException $e)

Tier 2 — High confidence (docblocks)

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

Type	Source
docblock_param	@param FooType $x
docblock_return	@return FooType
docblock_var	@var FooType
docblock_throws	@throws FooException

Confidence levels

Value	Meaning
certain	Structural relationship guaranteed by the AST
high	Docblock, highly probable
medium	Ambiguous pattern (instanceof)
low	Dynamic pattern

---

Warnings

Type	Trigger
dynamic_instantiation	new $variable() — class unknown at static analysis time
dynamic_call	Unresolvable dynamic call
parse_error	Invalid or unreadable PHP file

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