Download the PHP package shimabox/psap without Composer

psap

psap (PHP SAP) is a CLI that statically analyzes PHP codebases and measures Clean Architecture's Stable Abstractions Principle metrics (Ca / Ce / I / A / D). It detects circular dependencies with file:line evidence and renders self-contained HTML / Mermaid / PlantUML reports. Analysis runs entirely locally — no code leaves your machine. Documentation is in Japanese.

psap（PHP SAP）は、PHP コードベースを解析して Clean Architecture（Robert C. Martin 著）第14章「安定度・抽象度等価の原則（SAP: Stable Abstractions Principle）」のメトリクス（Ca / Ce / I / A / D）を計測する CLI ツールです。

設計が変更しづらくなっている場所、依存が集中している場所、循環依存の原因を見つけるために使います。解析はローカルで完結し、外部サービスへソースコードを送りません。

psap自身を解析したポータルのデモを公開しています。

分かること

• 名前空間ごとの安定度と抽象度
• 依存が集中しているコンポーネント
• 循環依存を構成する具体的な経路
• 依存が発生した構文、ファイル、行番号
• 以前の解析から新しく増えた循環依存
• 指標に含まれない解析対象外への依存

おすすめの使い方

最も有効なのは、既存プロジェクトのMarkdownレポートを作り、コードへアクセスできる生成AIと一緒に設計上の問題を確認する使い方です。

1 インストール

GHCR (GitHub Container Registry) からイメージを取得します。

バージョンを固定したい場合はlatestの代わりにタグ（例: 0.1.2）を指定します。

PlantUML・Java・Graphvizを同梱した版は-plantumlサフィックス（例: latest-plantuml）で配布しています（使い方）。

インストールできたことを確認します。

PHP 8.3以降があれば、psap.pharでも導入できます。その場合は以降のdocker run --rm -v "$PWD":/workdir psapをpsap（pharはphp psap.phar）へ読み替えてください。

新しいバージョンに更新する場合は、docker pullで最新イメージを取得し、docker tagを実行し直します（docker tagはスナップショットのため、pullだけではローカルのpsapタグは更新されません）。

2 レポートを作る

解析したいPHPプロジェクトへ移動し、ソースディレクトリを指定します。

この例では、現在のプロジェクトをコンテナ内の/workdirへ割り当て、ホスト側のsrc/を解析して、プロジェクト直下へpsap-report.mdを出力します。任意の/path/to/dirを解析する方法や、結果を別のディレクトリへ出力する方法はDockerで解析対象と出力先を指定するを参照してください。

--depthはファイル探索の深さではなく、名前空間をコンポーネントに束ねる階層です。既定のautoは共通名前空間の直下を選ぶため、まずは指定せずに解析してください。
より深い名前空間に独立した責務があり、内部の依存関係まで確認したい場合は、--depthを1段ずつ増やして結果を比較します。深くしすぎると内部実装まで別コンポーネントになり、レポートの複雑さと計算量も増えるため、最大値を選べばよいわけではありません。

3 結果を確認する

レポートが作成されたことを確認します。

最初にReview Prioritiesを読み、次にCircular DependenciesとDependency Hotspotsを確認します。循環依存には、原因となるクラス、構文、ファイル、行番号が表示されます。

Analysis coverageには、発見、選択、解析、除外、スキップしたPHPファイル数が表示されます。スキップや解析上の注意がある場合は診断欄で、理由、ソース位置、推奨する次の対応を確認できます。
カバレッジ100%は選択したPHPファイルをすべて処理できたことを示しますが、動的参照や設定ファイルだけに書かれた依存まで検出したことを意味しません。

IとAの分布をブラウザで確認する場合は、自己完結HTMLも生成できます。

グラフの点へマウスを重ねると指標を確認でき、選択するとその名前空間コンポーネントに含まれるクラスを一覧できます。検索、ゾーン、最小Dによる絞り込みにも対応しています。

コンポーネント数が多いプロジェクトでは、まずHTMLで全体を俯瞰し、検索や指標で確認対象を絞る使い方が適しています。MermaidとPlantUMLは、解析対象や--depthを調整したうえで、関心のある範囲を静的な図として確認・共有する場合に向いています。

デフォルトの表示は英語です。HTML右上の言語セレクターから日本語へ切り替えられます。

HTMLは実際のゾーン判定を円弧で表示します。MermaidのquadrantChartは同じゾーンを象限として近似表示するため、形は異なりますが点の指標と座標は共通です。

サマリー、I/Aグラフ、図、循環詳細、図ソースを1ファイルにまとめたポータル（--format portal）も生成できます。

psap-portal.htmlをブラウザで開くと、Overview・Interactive I/A・Diagrams・Cycles・Sourcesのタブを切り替えられます。
DiagramsタブのquadrantChartと依存フローチャートは同梱したMermaidがブラウザ内で描画し、拡大・移動もできます。
SourcesタブからはMermaid（.mmd）・PlantUML（.puml）の図ソースとMarkdownレポート（psap-report.md）をコピー・ダウンロードできます。
解析結果もMermaidも1ファイルに収まるため外部通信は発生せず、出力サイズは+3.5MB前後になります。

依存フローチャートのエッジ数が500を超えると、ブラウザ内描画を省略してソース表示に切り替えます。

4 生成AIへ渡す

Claude Code, Codexなど、解析対象のコードを読める生成AIに次のように依頼してみましょう。

5 コードで確かめる

生成AIの提案と、レポートに記載されたファイル・行番号を照らし合わせます。循環依存が実際に不要か、名前空間の分け方が適切か、変更後の責務が明確になるかを確認してから修正します。

修正後に同じコマンドを再実行し、循環や依存が減ったことを確認します。継続して監視したい場合は、同じ解析条件をCIへ追加します。

CIで使う

Dが閾値を超えた場合や、循環依存が見つかった場合に終了コード1を返せます。

既存の循環をベースラインとして保存し、新しく増えた循環だけを検出することもできます。

ドキュメント

• 導入と基本操作
• 解析内容と出力形式
• CIでの利用
• 開発

PHP 8.3以降が必要です。Dockerを使う場合、ホスト側のPHPは不要です。

ライセンス

MIT License