phpgraph

phpgraph

AI コーディングエージェント向けの、PHP コードベースのナレッジグラフです。
MCP 経由の静的解析を、Sherpa、Claude Code、Codex、Cursor、その他すべての MCP クライアントに提供します。
LLM もネットワーク接続も埋め込みも不要です。各事実には信頼度が付与され、結果は決定的です。

英語 · フランス語

phpgraph を使う理由

見慣れない PHP プロジェクトに置かれた AI エージェントは、ファイルを一つずつ読み、名前を grep します。しかし、実際のコードベースで最も重要な点を見落とします。何が何を呼び出すのか、どのハンドラーがメッセージを受け取るのか、どのコントローラーがルートを処理するのか、メソッドを変更したら何が壊れるのか、どのレイヤーがどのレイヤーに依存しているのかです。

phpgraph は nikic/php-parser を使ってプロジェクト全体を一度解析し、グラフからこうした質問に答えます。

• 推測ではなく、決定的な事実です。 すべての関係は、EXTRACTED（コードから読み取ったもの）、INFERRED（宣言された型から解決したもの）、または AMBIGUOUS（推測であることを明示したもの）に分類されます。
• わからないことも明示します。 解決できない呼び出し、存在しない vendor/、ハンドラーのないメッセージなどの不足情報を報告するため、エージェントはコードを自分で読むべきタイミングがわかります。
• まず DDD とヘキサゴナルアーキテクチャ向けに、次にマイクロサービス向けに、そして PHP 全般向けに設計されています。 Symfony、Laravel、Ecotone、PrestaShop、WordPress、またはプレーンな PHP に対応します。
• プライバシーを前提に設計されています。 コードがマシンの外に出ることはなく、phpgraph がコードを実行することもありません。解析のみを行います。

機能

• 型推論に対応したコールグラフ：戻り値の型、連鎖呼び出し（$a->b()->c()）、ローカル変数、DocBlock（@return、@var）、vendor/ の依存関係のシグネチャに対応しているため、Doctrine、Symfony、Laravel の API をたどれます。
• アーキテクチャ：DDD とヘキサゴナルアーキテクチャのレイヤー、境界づけられたコンテキスト、CI でチェックされるレイヤールール（phpgraph check）、影響分析（impact_of）に対応しています。クラスやメソッドに依存しているものや、実行すべきテストを確認できます。
• メッセージとイベント：Symfony Messenger、Laravel のジョブとイベント、Ecotone、PrestaShop CQRS、WordPress のフック、ドメインイベント、独自のバスについて、属性、サービス設定（YAML、XML、PHP）、またはコードの形式から、送信元 → メッセージ → ハンドラーを追跡します。
• HTTP：ルート（Symfony の属性、YAML および PHP のルーティングファイル、API Platform のリソース、Laravel のルートファイル、コンテナのサービス ID を名前に持つコントローラー）をコントローラーに関連付け、HTTP 呼び出しを呼び出し先のルートに関連付けます。コントローラークラスがプロジェクトにも vendor/ にも存在しないルートは、ルーティングファイルとともに報告されます。
• 依存性注入：コンストラクターの型以外に Symfony コンテナ設定が注入するもの、タグに属するすべてのサービス（tagged_iterator、#[AutowireIterator]）、または ID で指定されたサービスを、PHP、YAML、XML の設定から特定します。リテラル引数を使って呼び出されるヘルパー（Wiring::wire($services, 'sales', ...)、評価されますが実行はされません）にも対応しています。たとえば、バリデーターは受け取るルールに関連付けられます。受け付けるものを宣言するルール（supports(object $input): bool { return $input instanceof CreateEstimateQuery; }。canHandle、accepts なども対象です）は、別の入力を共有パイプラインに渡すユースケースから除外されます。入力のプロパティが保持するクラスも含まれます。インターフェース型の入力については、それを実装するプロジェクト内のクラスと、その入力が渡される先のパラメーター型も対象になります（QueryInterface $query が setUp(CreateEstimateQueryInterface $query) に渡される場合は CreateEstimateQuery）。読み取れないガードや、一部のクラスに対してのみ実行されるルールは保持され、supports() not resolved とマークされます。
• マイクロサービス：サービスごとに個別の ID 空間を持ち、共有メッセージクラス、ルーティングキー、HTTP ルートを通じてサービス間のリンクを追跡します。
• API スキーマ：OpenAPI（Swagger）ドキュメントの操作を、それを実装するルートに関連付けます。別の API のドキュメントの場合は、そのクライアントの HTTP 呼び出しに関連付けます。protobuf サービスの RPC は、生成されたインターフェースを実装するクラスに関連付けます。ドキュメントに記載されているが実装されていないものや、どのドキュメントにも記載されていないルートを報告します。impact は変更の背後にある操作（クライアントが依存するコントラクト）を一覧表示し、outline は機能が対応する操作を一覧表示します。
• ゼロ設定の MCP サーバー：初回使用時に構築され、コードの変更時には差分のみを再構築します（8,400 ファイルのプロジェクトで編集あたり約 3 秒）。

クイックスタート

1. インストールします。 PHP は不要で、単一の実行ファイルです（x86_64 と ARM の Linux および macOS、x86_64 の Windows に対応）：

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

このスクリプトはバイナリをダウンロードし、SHA-256 を検証して、~/.local/bin に配置します（Windows の場合は %LOCALAPPDATA%\Programs\phpgraph に配置し、PATH に追加します）。PHPGRAPH_INSTALL_DIR を設定すると、配置先を変更できます。更新するには、もう一度実行してください。dev-main は main へのプッシュごとに再ビルドされます（edge のプレリリースです）。このバイナリは、static-php-cli でビルドされた、phpgraph を内蔵する静的 PHP ランタイムです。

PHP 8.2 以降がインストールされている場合、または 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. エージェントを接続します。 mcp-config は、パスを埋め込んだすぐに貼り付けられる設定を出力します（Composer でインストールした場合は vendor/bin/phpgraph）：

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

phpgraph に接続していても、エージェントはまず grep を使いがちです。mcp-config は、プロジェクトの指示ファイル（CLAUDE.md、AGENTS.md）に追加する一文も出力します。これは、grep やファイルの読み取りより先に phpgraph を呼び出すようエージェントに指示するもので、サーバーの MCP 指示にも同じ内容が記載されています。

ターミナルのコーディングエージェントである Sherpa では、宣言を 1 つ追加するだけで、すべてのプロジェクトで使えます。Sherpa は、実行されているプロジェクトから MCP サーバーを起動します。

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

Sherpa のセッションでは、/mcp add でも同じことができ、ツールをすぐに利用できます。どちらの方法でも ~/.config/sherpa/mcp.json に書き込みます。

Claude Code の場合（mcp-config が出力する絶対パスを使用します）：

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

3. エージェントに 「このプロジェクトの概要を教えてください」、「注文はどのように処理されますか？」、「OrderRepository::save を変更すると、何が壊れますか？」 のような質問をしてみましょう。最初の呼び出し時にグラフが構築され、その後は最新の状態に保たれます。

MCP ツール

サーバーは、エージェントに最初に overview を呼び出すよう指示します。エージェントから見たパスの例（php-ddd-example）：

Shortest path (4 hops):
  PUT /courses/{id} --handled_by--> CoursesPutController::__invoke()
    --dispatches--> CreateCourseCommand --handled_by--> CreateCourseCommandHandler::__invoke()
    --calls--> CourseCreator::__invoke()

コマンドライン

phpgraph build [path]                        # phpgraph-out/graph.json and GRAPH_REPORT.md
phpgraph overview                            # stack, structure and gaps
phpgraph impact "OrderRepository::save"      # what depends on it, and the tests to run (--all, --section tests, --format json)
phpgraph check                               # layer rules, for CI: exit code 1 on a new violation
phpgraph explain "PlaceOrderHandler"         # a node and its relations (-d in|out)
phpgraph path "StockChecker" "DbalOrderRepository"
phpgraph query "how is stock checked"
phpgraph outline "notification validation"   # the outline of a feature (--section flow, --format json)
phpgraph serve [path]                        # the MCP server, over stdio
phpgraph mcp-config claude|codex|cursor|json [--docker image]

build のオプション：パスを除外する -e（複数回指定可能）、依存関係を読み込まない --no-vendor、すべてのファイルを再度解析する --no-cache。vendor、node_modules、var、.git と、プロジェクト独自の .gitignore ファイルで無視されるファイルはスキップされます。プロジェクトより上位にある Git リポジトリのルールは適用されないため、無視対象のディレクトリにコピーされたプロジェクトも読み込まれます。ディレクトリに PHP ファイルが含まれていても、すべて除外されている場合は、build は失敗してその旨を示します。また、空のグラフを提供する代わりに、すべての MCP の回答の冒頭に警告が表示されます。デフォルトではメモリ制限はありません。PHPGRAPH_MEMORY_LIMIT=2G で上限を設定できます。PHP がインストールされている場合、opcache とその JIT によりビルドが約20％速くなります：php -d opcache.enable_cli=1 -d opcache.jit=tracing -d opcache.jit_buffer_size=128M vendor/bin/phpgraph build（Docker イメージと mcp-config が出力するコマンドでは、すでにこれらが使用されています）。

グラフに含まれる内容

すべての関係には信頼度レベルがあります。

phpgraph check --generate-baseline   # accept today's violations in phpgraph-baseline.json
phpgraph check                       # fail on new ones only

services:
  - services/billing
  - services/shipping

actions:
  - file: Framework/jacActions.xml
    element: //action                                 # XPath of the action elements
    code: code                                        # their attributes (these are the defaults)
    controller: controller
    method: method
    controller_file: '{dir}/control/{name}CTRL.php'   # _Stock/Reservation → _Stock/control/ReservationCTRL.php
    target: target                                    # the action or template it goes on to
    forward: { element: forward, result: result, target: target }
    cited_in: [html, js]                              # the screens quoting the codes

実プロジェクトでの測定結果

phpgraph は、コミットに固定されたオープンソースプロジェクトのコーパスを対象に開発されており、すべての変更をその数値で評価しています（composer corpus:measure）。アプリケーションコードのみを対象としています。receiver typed は、phpgraph がレシーバーの型を判定できたメソッド呼び出しの割合です。

さらに、4 つのマイクロサービスプロジェクトがコーパスを構成しています。RabbitMQ を介して連携する 2 つの Laravel サービスは、4 つのメッセージコントラクトで結ばれています。HTTP を介して連携する 4 つの Laravel サービスでは、phpgraph が GET のみを受け付けるルートに送信された POST を検出しました。Spiral のチケット予約システムでは、.proto ファイルで宣言された gRPC サービスを通じてサービス同士が呼び出しを行います。また、StayHub は、OpenAPI ファイルで記述された API ゲートウェイの背後に 7 つの Laravel サービスを配置しています。最後の 2 つのプロジェクトでは、API スキーマをコントラクトとして測定しています。StayHub のドキュメントにある 45 個すべての操作と、ticket-booking の 14 個すべての RPC が、それぞれの実装と結び付けられています。約 26,600 ファイルで解析エラーはゼロでした。メッセージ、ルート、サービスなど、プロジェクトごとの詳細は corpus/RESULTS.md をご覧ください。

エージェントとの使用

非公開の 4,800 ファイルの Symfony/DDD プロジェクトで測定しました。各構成で 3 回実行し、同じエージェント（Sherpa）を phpgraph 1.0.2 ありとなしで比較しました。

phpgraph ありとなしの実行結果の範囲は重なりません。

他のコードグラフとの比較

Sylius（コーパスのコミット）、2026年10月時点、LLM なしでの比較です。同じマシン上の Docker で、phpgraph 1.0.2、codebase-memory-mcp 0.11.0、graphify 0.9.76（--code-only）を使用しました。呼び出しはサイトごと（ファイル、行、メソッド）に比較し、差分のサンプルをコードで確認しました。

• codebase-memory-mcp は、型から解決した呼び出しの99.7 %で phpgraph と一致します。残りのエッジはメソッド名から推測されています（信頼度0.04〜0.44）。両者が同じ呼び出しにリンクしている箇所では、9,400件のサイトで結果が異なり、追加された11,300件のエッジの大部分は、vendor/ 内の呼び出しを同名のプロジェクトメソッドに関連付けたものです（確認した20件中19件）。
• graphify は $this->other->foo() を現在のクラスの foo() にリンクします。$this->foo() では正しいものの、確認した差分10件中10件で誤っていました。
• phpgraph にはなく、他のツールにある機能：他の言語、全文検索とベクトル検索、Cypher クエリ（codebase-memory-mcp）、インタラクティブな可視化とグラフ内のドキュメント（graphify）。

FAQ

phpgraph は私のコードをどこかに送信しますか？ いいえ。ローカルで実行され、ネットワーク通信は行わず、LLM も使用しません。

コードを実行しますか？ いいえ。PHP ファイルを解析し、JSON、YAML、XML の設定を読み取ります。autoload_classmap.php や PHP のサービスコンフィギュレーターも、読み込まずに解析します。

どの PHP バージョンを解析できますか？ nikic/php-parser 5 で解析できるすべての構文です。PHP 7 と 8 の構文に加え、最新の文法では拒否されるファイルについては、削除済みの PHP 4 と 5 の構文（$s{0}、=& new、08 のような8進数リテラル）も解析できます。phpgraph 自体には PHP 8.2 以降が必要です。

どのエージェントで使えますか？ stdio 経由の MCP クライアントならどれでも使えます：Sherpa、Claude Code、Codex、Cursor、Claude Desktop などです。mcp-config は一般的なクライアント向けの設定を出力します。

どのくらいの規模のプロジェクトを処理できますか？ コーパス内で最大のプロジェクトである Akeneo は8,400ファイルです。全体のビルドには約10 s、500 MB、編集後の再ビルドには約3 sかかります。

制限事項

• 読み取るのは PHP のみです。混在リポジトリの他の言語は overview に表示されますが、それらから PHP 部分への呼び出しはリンクされません。また、プロジェクトに PHP がまったく含まれていない場合は、MCP の指示にその旨が表示されます。
• グローバル関数への呼び出しはグラフのエッジになりませんが、関数の戻り値によって、その関数に続く呼び出しの型は決まります（now()->addDay()、response()->json()）。動的呼び出し（$this->$name()、__call）は、クラスがドキュメント化しているメソッド（@method、@mixin）を通じてのみ解決されます。
• ジェネリクスは、プロジェクトと vendor/ の docblock（@template、@extends Repository<Order>、@return Collection<int, Item>、ScalarNodeDefinition<$this>）から読み取られます。テンプレートは、レシーバーの型と、それを引き継ぐ親クラスによって束縛されます。また、foreach は型付きコレクションの要素を順に処理します。ユニオン型（ドキュメント化されているか宣言されている Response|ResponseFactory）は、メソッドを宣言しているメンバーに対して呼び出されます。メソッドを宣言しているメンバーがある場合に限ります。メソッドに渡されるクロージャには、そのメソッドが渡すとドキュメント化しているパラメーターが設定されます（@param callable($this): mixed、Laravel の when(fn ($query) => ...)）。トレイトの使用にある @use HasFactory<HotelFactory> は、そのテンプレートを束縛します。メソッドのテンプレートは、各呼び出しの引数によって束縛されます。具体的には、引数が示すクラス（@param class-string<T> を持つ getRepository(Order::class)）、値の型（@param T $value）、クロージャの戻り値（@param callable(): T、その戻り値の文やネイティブ型）です。@phpstan-return と @psalm-return は @return より先に読み取られます。引数から判定できない条件（TAsync is false ? Response : PromiseInterface）は、各分岐のユニオン型になります。@property および @property-read でドキュメント化されたマジックプロパティは、その後のチェーンにも型を引き継ぎます。Eloquent モデルでは、キャスト（'paid_at' => 'datetime' は Carbon、列挙型、キャストクラスの TGet）、タイムスタンプ、プロパティとして読み取られるリレーション（$page->book、book()->getResults() の戻り値）も同様です。戻り値の型を宣言していないメソッドは、オーバーライド元のメソッドが宣言している戻り値（@inheritDoc）を返します。型に関する条件（$id is array ? Collection : Model）は評価されず、mixed とドキュメント化されたファサードメソッド（DB::transaction()）は不明のままです。
• マジックメソッドや、使用可能な戻り値の型がない依存関係に到達すると、チェーンはそこで止まります。PHP 組み込みのクラス（DateTime、ArrayObject、SplObjectStorage、PDO など）は、1 回生成されるシグネチャ（tools/internal-classes.php）から認識されますが、intl および mysqli 拡張のクラスは認識されません。
• vendor/ がインストールされていない場合、呼び出しチェーンは最初の依存関係で止まります。
• 実行時に構築されるサービス（コンパイラーパス、バンドル拡張、実行時にしか判明しない値から計算される ID）、XML ルート（ただし、phpgraph.yaml でマッピングされたアクションファイルは除きます）、XML または YAML で宣言された API Platform リソース、OpenAPI と protobuf 以外の API スキーマ（GraphQL、AsyncAPI）は読み取られません。ゲートウェイによって書き換えられた OpenAPI パスは追跡されず、リンクできないインジェクションは overview に一覧表示されます。
• 同じ名前のメッセージクラスを宣言する 2 つのサービスは、同じクラスを共有しているものとして扱われます。

貢献

Issue とプルリクエストを歓迎します。CONTRIBUTING.md を参照してください。composer check が成功する必要があります（php-cs-fixer、PHPStan level max、PHPUnit）。分析に関する変更はコーパスに基づいて評価されます。PHP がインストールされていない場合は、bin/dev composer check ですべてを Docker 上で実行できます。

バージョンをまたいで安定しているもの（コマンド、MCP ツール、graph.json 形式）は docs/STABILITY.md に記載されています。変更点は変更履歴を参照してください。

リリースはバージョンタグをプッシュして公開します。リリースワークフローによって、PHAR、Linux、macOS、Windows 用の実行ファイル（tools/build-binary.sh）、Docker イメージ ghcr.io/hbenabdallah/phpgraph がビルドされます。

ライセンス

phpgraph は、PolyForm Shield License 1.0.0 に基づきソースコードを公開しています。phpgraph と競合しない目的であれば、企業内での利用を含め、使用、改変、再配布が可能です。このコードを使って競合製品を提供することは許可されていません。このライセンスは OSI 承認のオープンソースライセンスではありません。