phpgraph

A knowledge graph of your PHP codebase, for AI coding agents.

Static analysis served over MCP to Sherpa , Claude Code, Codex, Cursor and any MCP client.

No LLM, no network, no embeddings: deterministic facts, each with a confidence level.

English · Français

---

What it answers

An agent in a PHP project it does not know greps names and reads files. That works until the answer goes through something a search of names does not show: an interface, the container configuration, a bus, a route, another service. phpgraph parses the whole project once (with nikic/php-parser, docblocks with phpstan/phpdoc-parser) and answers from a graph, in one call:

• What breaks if I change this method? impact_of lists every dependent, nearest first, callers through the interface it implements included, the routes reaching it and the tests to run. Sylius, the 17 callers of OrderItemQuantityModifierInterface::modify(): phpgraph finds 17, codebase-memory-mcp 11 (2 false), graphify 0.
• How does this feature work? outline gives the classes, the routes running into them, the behaviour read in their bodies, the wiring and the tests in one answer, so the agent reads only the files with non-obvious logic. Claude Code on 6 explain tasks: −12 % tokens, −26 % time, −42 % tool calls.
• Which handler receives this message, which controller serves this route? Senders, messages and handlers are linked for Symfony Messenger, Laravel, Ecotone, PrestaShop CQRS, WordPress hooks and your own buses; routes to their controllers, HTTP calls to the routes they reach. Sylius: 206 Messenger handlers linked to their message; Kimai: 266 routes and 26 events with their subscribers; graphify links none. Claude Code wrote the exact class name in 18 of 18 runs with phpgraph, 15 of 18 without (the 3 misses: namespaces guessed from the path).
• Does the code respect its layers? phpgraph check fails the CI on a new dependency that breaks the layer rules (domain, application, infrastructure) or the project's own rules in phpgraph.yaml, with a baseline for today's violations.
• What crosses the service boundaries? Shared message classes, routing keys, HTTP routes, OpenAPI and protobuf schemas link services together: all 45 operations of StayHub's OpenAPI document and all 14 rpcs of ticket-booking are linked to their implementation; in art-gallery, phpgraph found a POST sent to a GET-only route.
• Who calls this, in a large or old codebase? Receivers are typed from return types, docblocks, generics, branches and the signatures of vendor/, and PHP 4 and 5 syntax is parsed: 92.9 to 99.1 % of method calls typed on the 7 main projects of the corpus. On Kimai, phpgraph finds the callers in 2,407 of the 2,408 files a grep finds for methods whose name is declared once, graphify in 902.

How it answers:

• Deterministic facts, not guesses. Every relation is EXTRACTED (read in the code), INFERRED (resolved from declared types) or AMBIGUOUS (a guess, labelled as such).
• It says what it does not know. Unresolved calls, missing vendor/, messages without handlers: the gaps are reported, so the agent knows when to read the code itself.
• Built for DDD and hexagonal architecture, then microservices, then PHP in general: Symfony, Laravel, Ecotone, PrestaShop, WordPress, or plain PHP.
• Private by design. Your code never leaves your machine, and phpgraph never executes it: it only parses it.

What it costs

The same agent with and without phpgraph, scored against answers derived from the code (method and every run):

On the Sherpa project, the ranges of the runs with and without phpgraph do not overlap; on the public tasks, the run-to-run variance is about 11 %, so a few percent on one task is noise.

Questions whose answer goes through an indirection (a custom command bus, the container configuration, an HTTP path in another service), 4 tasks run once per arm: Claude Code reached the full answer without phpgraph too, every time. The difference showed on the largest project, in the way there: the controllers of Akeneo reaching GetCategoryInterface::byCode() through its command bus cost 182 k tokens and 19 s with phpgraph, 382 k and 33 s without. One run each is a direction, not a measure; on the other three tasks, phpgraph cost more tokens.

Quick start

1. Install. A single executable, no PHP needed (Linux and macOS on x86_64 and ARM, Windows on x86_64):

curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh                  # latest release

curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh -s -- 0.2.0 # a given release curl -fsSL https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.sh | sh -s -- dev-main # the main branch

irm https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.ps1 | iex                       # Windows

$env:PHPGRAPH_VERSION = "dev-main"; irm https://raw.githubusercontent.com/hbenabdallah/phpgraph/main/install.ps1 | iex

The script downloads the binary, checks its SHA-256 and puts it in ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\phpgraph, added to the PATH); PHPGRAPH_INSTALL_DIR changes the directory. Run it again to update. dev-main is rebuilt on every push to main (the edge pre-release). The binary is a static PHP runtime with phpgraph inside, built with static-php-cli.

With PHP 8.5+ installed, or with Docker:

composer require --dev hbenabdallah/phpgraph       # or: composer global require hbenabdallah/phpgraph

curl -LO https://github.com/hbenabdallah/phpgraph/releases/latest/download/phpgraph.phar docker pull ghcr.io/hbenabdallah/phpgraph # nothing else to install

2. Connect your agent. mcp-config prints a ready-to-paste configuration with the paths filled in (vendor/bin/phpgraph when installed with Composer):

phpgraph mcp-config sherpa    # Sherpa: a `sherpa mcp add` command, one declaration for every project

phpgraph mcp-config claude # Claude Code: a claude mcp add command, or .mcp.json phpgraph mcp-config codex # Codex: ~/.codex/config.toml phpgraph mcp-config cursor # Cursor: .cursor/mcp.json, shareable with the team phpgraph mcp-config json # any other MCP client over stdio

Agents reach for grep first, even with phpgraph connected. mcp-config also prints a line for the instructions file of the project (CLAUDE.md, AGENTS.md) telling the agent to call phpgraph before grep or reading files; the MCP instructions of the server say it too.

With Sherpa, a terminal coding agent, one declaration serves every project: Sherpa starts its MCP servers from the project it runs in.

sherpa mcp add phpgraph -- ~/.local/bin/phpgraph serve

In a Sherpa session, /mcp add does the same, and the tools are there at once. Both write ~/.config/sherpa/mcp.json.

With Claude Code (absolute paths, as mcp-config prints them):

claude mcp add phpgraph -- /home/you/.local/bin/phpgraph serve /path/to/project

3. Ask your agent something like *"Give me an overview of this project"*, *"How does an order get placed?"* or *"What breaks if I change OrderRepository::save?"*. The graph is built on the first call, then kept up to date.

MCP tools

| get_node | Read one class, method, route or chann