phpgraph

phpgraph parses a PHP project (no LLM, no network) and serves its graph over MCP: what breaks if a method changes, how a feature works, which handler receives a message, which controller serves a route. Every fact carries a confidence level, and what it could not link is reported

Documentation

phpgraph

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

CI Packagist version PHP 8.5+ to run from source License: MIT

English · Français


A coding agent in a PHP project it does not know searches names with grep, reads file after file, and guesses when the answer goes through something a name search does not show: an interface, the service container, a message bus, a route. phpgraph parses the project once and gives the agent the answer from a graph, over MCP, in one call. In the benchmarks it paid off on the largest project measured, for a question about the impact of a change; on smaller projects the same kind of question cost more tokens with it.

Demo

demo

A 68-second video, the same question to Claude Code with and without phpgraph, one real run each: docs/assets/demo-video.mp4 (how it was made).

No LLM, no network, no embeddings: your code never leaves your machine, and phpgraph parses it without running it. Every fact says how sure it is (EXTRACTED, INFERRED or AMBIGUOUS), and what phpgraph could not link is reported.

Where it helps and where it doesn't

Akeneo PIM (8,416 PHP files), task: list every class that must change when GetCategoryInterface::byCode() takes a second parameter. Claude Code 2.1.323 with Sonnet, phpgraph 2.1.0 development branch, 3 runs with phpgraph and 3 without:

With phpgraphWithout
Correct answers3/33/3
Tokens per run, median86,174174,735
Tokens per run, range86,107 to 130,744172,998 to 175,220
Time per run12.8 to 17.5 s11.6 to 12.7 s

Where it helps: the same answer for 51 % fewer tokens (median) on the largest project. Where it doesn't: on the 5 other impact tasks, on smaller projects, phpgraph used 1 % to 56 % more tokens, and on this task time was not better. Every result, grouped by version, with the method: docs/BENCHMARKS.md.

Quick start

1. Install the executable (Linux, macOS; it carries its own PHP, none needed):

curl -fsSL https://raw.githubusercontent.com/alpine-ronin/phpgraph/main/install.sh | sh

It checks the SHA-256 and installs to ~/.local/bin. Windows, Composer, PHAR and Docker: docs/INSTALL.md.

2. Connect Claude Code. From your project directory:

phpgraph mcp-config claude

It prints a claude mcp add phpgraph -- ... command with the paths filled in (run it), an .mcp.json to share with the team instead, and a line for CLAUDE.md telling the agent to call phpgraph before grep. Codex, Cursor, Sherpa and other MCP clients: phpgraph mcp-config codex|cursor|sherpa|json.

3. Ask. The graph is built on the first call, then kept up to date as you edit.

What you can ask

  • 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.
  • 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.
  • Which handler receives this message, which controller serves this route? Senders, messages and handlers are linked for Symfony Messenger, Laravel, Ecotone, PrestaShop, WordPress hooks and your own buses; routes to their controllers, HTTP calls to the routes they reach.
  • 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.

What it is not

  • Not a runtime tool. It reads code and configuration, never runs them: services built at runtime (compiler passes, ids computed at runtime) and dynamic calls ($this->$name(), __call without @method) stay unresolved.
  • Not every framework. Symfony, Laravel, Ecotone, PrestaShop and WordPress conventions are recognised, plus generic ones (handler attributes, *Handler, *Bus); others get the call graph only. Only PHP files are read.
  • Better with vendor/. Without installed dependencies, call chains stop at the first one.
  • PHP versions. The project you analyse can be any PHP version, PHP 4 syntax included, and its PHP does not need to be installed. phpgraph itself needs no PHP as an executable or in Docker, and PHP 8.5 or newer with Composer or the PHAR.

The full list: docs/LIMITATIONS.md.

Documentation

License

MIT.