企业官网建设流程全解析

• 开发工具

PHPStan 是一款在不运行代码的情况下发现 PHP 程序错误（bug）的静态分析工具，它让 PHP 在错误暴露层面更接近编译型语言。本篇文章以 PHPStan 官方发行仓库中的 CLAUDE.md 为核心脉络，逐层剖析该仓库的目录结构、PHAR 分发模型、PHP 版本支持策略、Bleeding Edge 实验特性机制、错误标识符体系以及整套 CI/CD 工作流，并结合 php-timer 项目（即 phpunit/php-timer 计时工具库）将其作为开发期静态分析工具的真实配置，帮助读者既看懂 PHPStan 发行仓库的内部组织方式，也掌握在自己项目中落地 PHPStan 的完整方法。

一、项目概览：PHPStan 是什么

PHPStan 的核心定位是静态分析工具：它不执行你的 PHP 代码，而是通过解析与类型推断在代码运行之前发现潜在错误，从而在测试写出之前就捕获一批 bug。这正是 CLAUDE.md 开头所描述的 "finds errors in PHP code without running it"（在不运行代码的情况下发现 PHP 代码中的错误），并因此"让 PHP 更接近编译型语言"。

需要特别强调的是：当前这份 CLAUDE.md 所在的仓库是一个distribution repository（发行仓库），它的职责是分发编译好的 PHAR 压缩包以及围绕该压缩包的一整套支撑基础设施（CLI 入口脚本、签名、校验和、E2E 测试、Docker 镜像、在线 Playground 等），PHPStan 的真实源码并不在这里，而是维护在独立的 phpstan-src 仓库中（内部源码要求 PHP 8.1+，在构建 PHAR 时降级编译以兼容旧版本）。因此，阅读本文时请记住一个关键区分："发行仓库"负责打包与分发，"源码仓库"负责功能实现。

在 php-timer 项目中，这份 CLAUDE.md 位于 tools/.phpstan/vendor/phpstan/phpstan/CLAUDE.md，它是通过 Composer 以require-dev方式安装到tools/子目录下的开发依赖文档，恰好为我们提供了一个"使用者视角"来对照理解下文所有概念。

二、发行仓库的目录结构与分发模型

2.1 仓库结构总览

CLAUDE.md 给出了发行仓库的完整目录布局，各组成部分职责如下：

2.2 PHAR 分发模型

整个仓库的核心分发单元是phpstan.phar这一预编译归档。其工作链路为：

1. 用户在命令行执行phpstan脚本；
2. 脚本负责加载phpstan.phar，并把执行委托给 PHAR 内置的二进制程序；
3. PHAR 的自动加载由bootstrap.php完成，其中内置了面向旧版 PHP 的 polyfill（向下兼容填充）；
4. .phar-checksum文件同时记录 MD5 与 SHA1 两种校验和，保障构建结果可复现、可验证。

这种"单一 PHAR 交付"的模式意味着：使用者无需关心 PHPStan 内部成千上万个类的加载细节，只需一个可执行文件即可完成分析。与之形成对照的是 php-timer 项目中的安装方式——通过 Composer 引入 PHPStan 后，tools/目录下会生成一个 tools/phpstan 的 bin 代理脚本，该脚本是 Composer 自动生成的 PHP 文件，内部通过phpvfscomposer://流包装器把执行委托给真实的phpstan/phpstan/phpstan入口，从而避免旧版 PHP 下 shebang 被意外输出。这从使用者侧印证了 CLAUDE.md 所述"脚本加载 PHAR 并委托执行"的分发模型。

2.3 关键运行前提

composer.json中定义的 PHP 版本要求为^7.4|^8.0，即该发行包本身可在 PHP 7.4 及所有 8.x 版本上运行。而 phpstan-src 源码仓库内部要求 PHP 8.1+，通过 PHAR 构建阶段的降级（downgrade）处理来兼顾上述旧版本兼容性。E2E 端到端测试实际运行于 PHP 7.4、8.0、8.1、8.2、8.3、8.4、8.5 共 7 个版本，覆盖 Linux 与 Windows 双平台，这是 CLAUDE.md 明确给出的版本支持事实。

三、Bleeding Edge：实验特性开关机制

PHPStan 有一个特色机制叫Bleeding Edge（前沿特性）：conf/bleedingEdge.neon配置档案中预先启用了一批"实验性 / 更严格"的检查规则，这些规则在尚未成为默认行为之前以 opt-in 方式提供给用户。使用者只需在自己的 NEON 配置文件中 include 该档案即可提前体验未来的严格检查。

在实际项目中，php-timer 仓库的 phpstan.neon 正是这样做的：

includes: - phar://phpstan.phar/conf/bleedingEdge.neon

注意这里 include 的是PHAR 内部的路径phar://phpstan.phar/conf/bleedingEdge.neon，即引用了压缩归档内自带的conf/bleedingEdge.neon，与 CLAUDE.md 中列出的仓库文件conf/bleedingEdge.neon一一对应。这说明 Bleeding Edge 配置档案被打包进了 PHAR，用户无需单独下载。

同时，php-timer 的 phpstan.neon 还把分析级别拉到了最高档level: 10，并启用了checkTooWideReturnTypesInProtectedAndPublicMethods、reportAlwaysTrueInLastCondition、reportPossiblyNonexistentConstantArrayOffset、reportPossiblyNonexistentGeneralArrayOffset等高级检查项，同时设置treatPhpDocTypesAsCertain: false让 PHPDoc 类型不再被无条件信任。这些参数共同构成了一个"高严格度"的静态分析基线，与 CLAUDE.md 中"Bleeding Edge 在成为默认之前先以 opt-in 提供"的设计意图完全吻合。

四、错误标识符（Error Identifiers）体系

CLAUDE.md 指出：PHPStan 的每一个错误都拥有唯一的标识符（identifier），例如argument.type（参数类型不匹配）、deadCode.unreachable（不可达代码）等。这套标识符体系的价值在于：

• 让错误信息可被机器稳定识别、过滤与分类；
• 便于在 CI 中按标识符精细化地忽略或降级处理某些检查；
• 是官方文档站错误说明页面的数据基础。

支撑这套体系的工具是仓库中的identifier-extractor/：它扫描所有 PHPStan 相关仓库（包括主仓库与各类扩展仓库）的规则源码，把规则中定义的标识符批量提取出来，生成 JSON 数据，再交给网站侧自动生成对应文档。从 php-timer 的 phpstan.neon 可以看到这类标识符体系的实际落地形态：配置中的strictRules.*（如disallowedLooseComparison、disallowedEmpty、strictFunctionCalls等）与ergebnis.*（如final.enabled、privateInFinalClass.enabled）均为按规则名逐一开关的细粒度控制，每个开关都对应一条或多条可被标识符引用的具体检查规则。

五、CI/CD 工作流全景

发行仓库的.github/workflows/下维护着一整套自动化流水线，CLAUDE.md 逐一列出了各工作流的职责：

从中可以提炼出 PHPStan 质量保障的四个层次：单元/端到端测试（tests.yml）→ 周边库集成（other-tests.yml）→ 大型真实项目验证（integration-tests.yml）→ 第一方扩展兼容（extension-tests.yml）。发行仓库当前的主开发分支为2.2.x，这与 php-timer 在 tools/.phpstan/composer.json 中锁定的phpstan/phpstan: ^2.2.16版本约束相互印证。

六、网站、Playground 与 Docker 基础设施

6.1 官方网站（phpstan.org）

网站源码位于website/目录，技术栈为Eleventy（11ty）+ Vite + TailwindCSS，采用两阶段构建：先执行npm run build:11ty，再执行npm run build:vite。站点部署目标是 AWS S3 + CloudFront。网站中的错误说明文档（website/errors/）为自动生成内容，数据来源正是第四节介绍的 identifier-extractor 产物。

6.2 在线 Playground

phpstan.org 的在线试用功能由两个 AWS Lambda 服务协同完成：

• playground-api/：TypeScript 编写的 API 服务，负责编排跨多个 PHP 版本的分析请求；
• playground-runner/：基于 Bref 的 PHP Lambda 服务，真正对用户提交的代码执行 PHPStan 分析。

两者均通过 Serverless Framework 部署到 AWS 的 eu-west-1 区域。这套架构把"分析任务"与"执行环境"解耦：API 层统一调度，Runner 层按需拉起 PHP 执行环境，天然适合多版本并行分析场景。

6.3 Docker 镜像

docker/目录下的 Dockerfile 基于php:*-cli-alpine基础镜像，为 PHP 8.0–8.4 各版本构建镜像。镜像特性：

• 在镜像内通过 Composer 安装 PHPStan；
• 以phpstan命令作为容器 entrypoint；
• 发布到 ghcr.io，支持 arm64 + amd64 多架构。

这意味着在容器化 CI 中可以直接拉取对应 PHP 版本的 PHPStan 镜像，免去每次构建环境时重新安装依赖的开销。

七、扩展仓库生态

PHPStan 的价值很大程度来自其可扩展生态。CLAUDE.md 明确列出第一方扩展仓库，它们大多仍支持 PHP 7.4+，且部分扩展会对所分析的第三方库的多个版本同时提供兼容：

• phpstan-strict-rules：额外的严格检查规则集；
• phpstan-deprecation-rules：废弃（deprecation）检测；
• phpstan-doctrine：Doctrine ORM 集成；
• phpstan-symfony：Symfony 框架集成；
• phpstan-phpunit：PHPUnit 测试代码集成；
• phpstan-nette：Nette 框架集成；
• phpstan-webmozart-assert：Webmozart Assert 集成；
• phpdoc-parser：PHPDoc 解析库（PHPStan 的底层依赖之一）。

php-timer 项目正是这条生态链的典型使用者：其 tools/.phpstan/composer.json 中除了核心的phpstan/phpstan，还引入了phpstan/extension-installer（自动注册扩展的安装器）、phpstan/phpstan-strict-rules与ergebnis/phpstan-rules，并在config.allow-plugins中显式放行phpstan/extension-installer插件。这三个包的组合恰好对应上文 CLI/严格规则/代码风格三类扩展方向。

八、配置格式：NEON 说明

PHPStan 的配置文件采用NEON 格式（Nette Object Notation），这是一种与 YAML 相似的标记语言。它的显著特点是：

• 结构清晰、缩进敏感，适合表达嵌套配置；
• 支持 include 引用其他配置（如前述 Bleeding Edge 的引入方式）；
• 类型亲和性好，可直接表达布尔值、字符串、列表与嵌套映射。

php-timer 的 phpstan.neon 就是一份完整的 NEON 配置样例，其顶层结构分为parameters（分析参数）与includes（引入档案）两大块，是初学者理解 NEON 语法的极佳范本。

九、如何在自己的项目中落地 PHPStan

结合发行仓库 CLAUDE.md 的机制说明与 php-timer 的实际做法，一个完整落地路径如下：

第一步：以开发依赖安装 PHPStan 及其扩展

composer require --dev phpstan/phpstan phpstan/extension-installer phpstan/phpstan-strict-rules

若使用 phive 管理工具，也可以在tools/下通过 phive 安装独立 PHAR（php-timer 仓库的tools/目录中即并存了composer、phive、php-cs-fixer、phpstan四种工具入口）。

第二步：编写 NEON 配置文件

参考 php-timer 的 phpstan.neon，建议至少包含：

parameters: level: 10 paths: - src - tests includes: - phar://phpstan.phar/conf/bleedingEdge.neon

其中level控制检查强度（php-timer 使用最高档 10），paths指定被分析的目录，includes引入 Bleeding Edge 档案。

第三步：运行分析

tools/phpstan analyse

Composer 生成的 tools/phpstan 代理脚本会自动把执行委托给 PHAR 入口；若使用 Docker 方式，则直接以phpstan analyse作为容器命令。

十、对发行仓库的贡献边界（Making Changes）

CLAUDE.md 最后明确了"哪些改动属于本仓库、哪些不属于"：

• 源码级功能改动应提交到 phpstan-src 源码仓库，而非本发行仓库；
• 本仓库可维护的内容包括：e2e/目录下的端到端测试新增与修改、website/src/下的网站内容、website/errors/下的错误文档；
• 所有配置文件统一使用 NEON 格式。

对 php-timer 这类使用者项目而言，这条边界同样适用：tools/.phpstan/vendor/内的文件全部由 Composer 管理，属于依赖产物，不应手工改动；静态分析规则应当通过 phpstan.neon 这一用户侧配置来表达。

结语

从结构到机制，PHPStan 发行仓库向我们展示了一个成熟静态分析工具"打包—签名—校验—测试—分发"的完整工程样板：单一 PHAR 交付降低使用门槛，Bleeding Edge 提供渐进式严格化路径，错误标识符体系让错误处理可编程化，多层 CI 工作流保障跨版本跨平台质量，而扩展仓库生态则让 PHPStan 从"分析器"成长为可裁剪的分析平台。对普通 PHP 项目而言，最直接可复用的经验就是像 php-timer 一样：用 Composer 引入 PHPStan 与严格规则扩展，以level: 10+ Bleeding Edge 作为高严格度基线，并把分析纳入 CI，让静态检查成为团队质量的默认防线。

• 开发工具