PhpCodeArcheology/PhpCodeArcheology

# PhpCodeArcheology [](https://packagist.org/packages/php-code-archeology/php-code-archeology) [](https://packagist.org/packages/php-code-archeology/php-code-archeology) [](https://packagist.org/packages/php-code-archeology/php-code-archeology) [](https://glama.ai/mcp/servers/PhpCodeArcheology/PhpCodeArcheology) **PhpCodeArcheology** 是一款 PHP 静态分析工具，它通过 60 多项指标（包括圈复杂度、可维护性指数、耦合度和内聚性）来衡量代码质量。它可以为文件、类、方法和函数生成详尽的报告——检测代码异味，通过 git 变动分析识别热点，并跟踪质量趋势。 与 PHPStan 或 Psalm（侧重于类型安全和错误检测）不同，PhpCodeArcheology 专注于**架构和可维护性**——为您提供理解和改进代码库结构所需的洞察。可以将其视为 PHPMetrics 的替代方案，它具有更深入的 git 集成、基线管理和适配 AI 的输出。  ## 功能特性 - 针对每个文件、类和函数提供 **60 多项代码质量指标**——圈复杂度、认知复杂度、可维护性指数、LCOM、Halstead 度量、耦合度、不稳定度等 - 包含 14 条内置规则的**问题检测**——God Class（上帝类）、过于复杂、死代码、安全异味、违反 SOLID 原则、过深的继承、低类型覆盖率、未测试的复杂代码 - **测试分析**——自动检测 PHPUnit/Pest/Codeception，将测试文件映射到生产类，集成 Clover XML 以获取行级覆盖率，突出显示未测试的热点 - **Git 集成**——变动分析、热点检测（高变动率 + 高复杂度）、作者追踪 - **源代码展示**——直接在 HTML 报告中查看方法源代码，支持 PHP 语法高亮和嵌套深度热力图，让您能一眼揭示复杂度热点（[详见下文](#source-code-display)） - **多种报告格式**——交互式 HTML、Markdown、JSON、SARIF（用于 GitHub Code Scanning）、AI 摘要、知识图谱 (JSON) - **健康评分**——为您的整个项目提供单一的 0-100 分制以及 A-F 等级评定 - **技术债务评分**——按每 100 行逻辑代码标准化的加权问题评分 - **历史追踪**——跨多次分析运行的趋势图 - **基线管理**——仅追踪新问题，忽略现有问题（非常适合遗留项目） - **适配 CI/CD**——可配置的退出码，用于 GitHub Code Scanning 的 SARIF，用于自定义工具的 JSON - **快速模式**——仅输出到终端的快速分析，不生成报告 - **生成 CLAUDE.md**——为 AI 编程助手自动生成的项目概览 - **AI 集成**——为 Claude Code 等AI助手提供的原生 MCP server（[详见下文](#ai-integration-mcp-server)） ## 快速开始 ``` composer require --dev php-code-archeology/php-code-archeology ./vendor/bin/phpcodearcheology ``` 无需配置文件——该工具开箱即用。它会扫描您的 `src` 目录，并在 `tmp/report` 中创建一份 HTML 报告。在浏览器中打开 `tmp/report/index.html` 即可查看。 ## 目录 - [前置条件](#prerequisites) - [安装](#installation) - [使用 Composer 插件](#using-the-composer-plugin) - [CLI 选项](#cli-options) - [子命令](#subcommands) - [配置](#configuration) - [测试分析](#test-analysis) - [报告类型](#report-types) - [源代码展示](#source-code-display) - [知识图谱导出](#knowledge-graph-export) - [核心指标](#key-metrics) - [AI 集成 (MCP Server)](#ai-integration-mcp-server) - [理解健康评分](#understanding-the-health-score) - [内存与性能](#memory-and-performance) - [关于指标准确性的说明 (v2.7.0)](#a-note-on-metric-accuracy-v270) - [开发](#development) - [路线图](#roadmap) - [贡献](#contributing) ## 前置条件 - PHP 8.2 或更高版本（适用于 8.2、8.3、8.4、8.5） - Composer ## 安装 ``` composer require --dev php-code-archeology/php-code-archeology ``` ### 全局安装 ``` composer global require php-code-archeology/php-code-archeology ``` 确保 `~/.composer/vendor/bin`（或 `~/.config/composer/vendor/bin`）位于您的 `$PATH` 中。然后您可以在任何目录下运行： ``` phpcodearcheology /path/to/your/project ``` ### Docker ``` docker build -t phpcodearcheology https://github.com/PhpCodeArcheology/PhpCodeArcheology.git ``` 针对本地项目运行： ``` docker run --rm -v "$(pwd)":/project -v "$(pwd)/report":/output phpcodearcheology /project ``` 这会将您的项目挂载到容器中，并将 HTML 报告写入 `./report/`。 ### PHAR（适用于遗留代码库） 如果您的项目存在与 PhpCodeArcheology 要求的依赖冲突（例如较旧版本的 `nikic/php-parser`），请从 [Releases](https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases) 页面下载独立的 PHAR 文件。该 PHAR 捆绑了所有依赖项，无需更改您项目的 `composer.json` 即可运行。 ``` # 从最新 release 下载 PHAR 和校验和 curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar curl -LO https://github.com/PhpCodeArcheology/PhpCodeArcheology/releases/latest/download/phpcodearcheology.phar.sha256 # 验证 checksum shasum -a 256 -c phpcodearcheology.phar.sha256 # macOS sha256sum -c phpcodearcheology.phar.sha256 # Linux # 运行它 (PHP 8.2+) php phpcodearcheology.phar --quick src/ ``` 在以下情况请使用 PHAR：您项目的依赖与 PhpCodeArcheology 的依赖发生冲突，您希望在不执行 `composer require --dev` 的情况下配置 CI 步骤，或者您正在分析一个添加开发依赖有风险的遗留代码库。 ## 使用 Composer 插件 PhpCodeArcheology 将自身注册为 Composer 插件，因此您可以直接通过 Composer 运行分析： ``` composer codearch:analyze ``` 当未提供路径且不存在配置文件时，它会自动从 `composer.json` 检测您的 PSR-4 源目录。支持所有 CLI 选项： ``` composer codearch:analyze -- --quick composer codearch:analyze -- --report-type=json --coverage-file=clover.xml composer codearch:analyze -- src/ lib/ ``` 交互式创建配置文件： ``` ./vendor/bin/phpcodearcheology init ``` ## CLI 选项 ``` ./vendor/bin/phpcodearcheology [options] [path...] ``` | 选项 | 描述 | |--------|-------------| | `--report-type=TYPE` | 报告格式：`html`（默认）、`markdown`、`json`、`sarif`、`ai-summary`、`graph`。使用逗号分隔以输出多种格式：`html,json` | | `--report-dir=DIR` | 输出目录（默认：`tmp/report`） | | `--quick` | 快速分析，仅输出到终端，不生成报告 | | `--no-color` | 禁用彩色终端输出（同时支持 `NO_COLOR` 环境变量） | | `--fail-on=LEVEL` | 在遇到 `error` 或 `warning` 时以退出码 1 退出（用于 CI 流水线） | | `--generate-claude-md` | 生成 `CLAUDE.md` 项目概览 | | `--git-root=DIR` | Git 仓库根目录（默认：当前目录） | | `--extensions=EXT` | 要分析的文件扩展名（以逗号分隔，默认：`php`） | | `--exclude=DIR` | 要排除的目录（以逗号分隔） | | `--coverage-file=FILE` | 来自 PHPUnit/Pest 的 Clover XML 覆盖率文件，用于获取行级覆盖率数据 | | `--source-code` | 在 HTML 报告中包含带有语法高亮和嵌套热力图的源代码（[详见下文](#source-code-display)） | | `--version` | 显示版本号 | ## 子命令 ### `init` — 创建配置文件 ``` ./vendor/bin/phpcodearcheology init ``` 交互式创建具有合理默认值的 `php-codearch-config.yaml`。自动检测常见的源目录（`src`、`app`、`lib`）。 ### `compare` — 比较两份报告 ``` ./vendor/bin/phpcodearcheology compare report-before.json report-after.json ``` 显示指标、问题数量差异，并列出新增/已解决的问题。有助于回答：“我的重构真的起作用了吗？” ### `baseline` — 仅追踪新问题 ``` ./vendor/bin/phpcodearcheology baseline create src ./vendor/bin/phpcodearcheology baseline check src ``` `create` 将当前问题集保存为基线。`check` 运行全新的分析，仅报告与基线相比**新增**的问题。如果发现新错误则返回退出码 1——非常适合遗留项目的 CI 流水线。 ## 配置 在您的项目根目录下创建 `php-codearch-config.yaml`（或使用 `init` 命令）： ``` include: - "src" exclude: - "vendor" extensions: - "php" packageSize: 2 reportDir: "tmp/report" reportType: "html" git: enable: true since: "6 months ago" root: "." # Git repository root (useful for monorepos or subdirectory analysis) graph: methodCalls: true # Track cross-class method calls in the knowledge graph (default: true) php: version: "8.2" # Target PHP version for parsing (default: host PHP version) shortOpenTags: false # Treat