PHP 源码怎么读：从目录结构入手，理清程序的执行流程

拿到一个 PHP 项目，最容易遇到的困难不是看不懂某一行代码，而是不知道代码从哪里开始执行、一次请求会经过哪些文件，以及哪些目录值得优先阅读。若从文件列表第一页开始逐个打开，很快就会被配置、依赖和工具代码淹没。

更有效的做法是先画出项目边界，再找到运行入口，沿着“入口—路由—业务—数据或外部服务—响应”追踪一条具体路径。本文介绍这种阅读方法，并用一个可直接运行的小项目演示。它适用于维护旧项目、接手团队代码、定位请求行为，以及初步理解常见 PHP 应用；它不是对所有框架目录约定的硬性规定。

一、先确定你读的是什么程序

PHP 常用于 Web 应用，但 PHP 项目不一定由 HTTP 请求驱动。项目也可能是命令行工具、定时任务、队列消费者、Composer 库，或多个入口共用一套代码。因此第一步不是猜框架，而是确认运行方式。

• 查看项目根目录：有没有 composer.json、public/index.php、bin/、artisan、console 等线索。
• 查看 composer.json：关注 require、autoload、scripts，以及项目使用的 PHP 版本范围。
• 查看运行说明和部署配置：Nginx、Apache、Docker、CI 配置中，可能明确指出 Web 根目录、启动命令或任务入口。
• 确认实际运行环境：PHP CLI 与 PHP-FPM 可能使用不同的 PHP 版本和配置文件，不能只凭本机命令推断线上行为。

不要仅凭目录名认定架构。例如，项目有 app/ 不代表一定使用某个框架；有 public/ 也不意味着所有 PHP 文件都能被 Web 访问。以启动命令和部署配置为依据，再结合代码验证。

二、用目录结构建立地图

不同项目的目录约定并不统一，但常见内容大致可以分为几类：

• public/：Web 对外入口和静态文件。若服务器配置正确，Web 根目录通常指向这里，而不是整个项目根目录。
• src/、app/：应用代码，可能包含控制器、服务、领域对象等。具体分层要看项目自身约定。
• config/：应用配置、服务绑定、路由配置等。敏感凭据不应提交到公开仓库。
• routes/：路由定义。有些项目把路由写在控制器注解、配置文件或入口代码中，不一定有此目录。
• templates/、views/：服务端渲染模板。
• tests/：测试。测试用例常能直接说明输入、输出和边界条件。
• vendor/：Composer 安装的依赖。通常先读应用如何调用依赖，而不是从头阅读整个依赖源码。
• var/、storage/、logs/：缓存、日志、运行时文件等，名称和用途随项目变化。

先用文件清单获得全局视图，再挑关键文件阅读。以下命令在项目根目录执行：

find . -maxdepth 2 -type f | sort | head -200
cat composer.json

Windows 环境可以用 PowerShell 的 Get-ChildItem，或在编辑器中查看目录树。不要把 vendor/ 中的大量文件和应用源码混在一起阅读；也不要因为某个目录叫 cache 就假设里面的文件可以安全删除，先查生成逻辑和部署说明。

三、从入口追踪一次请求

对典型 Web 应用，可以先画出这样一条链路：

Web 服务器 → PHP-FPM 或其他 PHP 运行方式 → 入口脚本 → 引导与配置 → 路由 → 控制器 → 业务服务 → 数据库或外部服务 → 响应

这是一种阅读模型，不是 PHP 运行时保证的固定流程。轻量应用可能在一个文件里完成多个步骤；框架也可能通过中间件、事件、依赖注入和异常处理改变调用顺序。

1. 找到真正的入口

Web 项目常见入口是 public/index.php。它可能只负责加载自动加载器和启动应用，也可能包含较多早期初始化逻辑。CLI 项目则要找命令脚本和 Composer 的 bin 配置。一个仓库可以有多个入口，例如 Web 请求与队列消费者各有自己的启动流程。

不要把“文件存在”当成“程序一定从这里启动”。确认服务器配置、容器启动命令、任务调度配置和 Composer 脚本，才能判断哪些入口实际会运行。

2. 跟进自动加载和引导代码

若项目使用 Composer，入口通常会加载 vendor/autoload.php。自动加载使类名与文件路径建立映射，但映射规则由 composer.json 等配置决定，不应仅凭命名空间猜目录。运行 composer dump-autoload 可以重建自动加载文件，但它不会替代应用的启动逻辑。

继续追踪应用实例如何创建、配置何时载入、异常处理器何时注册。此处能回答很多关键问题：环境变量何时读取、数据库连接是否在启动时创建、日志写到哪里，以及配置错误如何反馈。

3. 从路由找到处理函数

先选择一个具体 URL 或命令，再搜索它对应的路由、控制器方法或命令类。相比抽象地通读所有控制器，沿着一个真实功能追踪，更容易识别参数从哪里来、在哪里校验、何时进入业务逻辑。

阅读时记录每一步的输入和输出。例如，HTTP 请求参数可能来自查询字符串、表单、JSON 请求体、路由参数或请求头；这些来源不等价。也不要把控制器里读取的参数直接视为可信数据。

4. 继续追到副作用和返回值

业务代码可能调用模型、仓储、邮件服务、支付接口、文件系统或队列。遇到接口或抽象类时，继续查实现绑定在哪里；在依赖注入项目中，实际实现可能由容器配置决定。最终再回到响应生成位置，确认状态码、响应头、序列化方式和异常处理。

所谓“副作用”，就是会改变程序外部状态的操作，例如写数据库、发送邮件、删除文件。读代码时特别标记这些位置，因为它们往往影响事务、重试、幂等和故障恢复。

四、一个最小可运行的 PHP 项目

下面的示例用最少代码展示入口、路由、控制器式处理和服务之间的关系。它需要 PHP 8.0 或更高版本，不依赖 Composer。创建以下目录和文件：

php-reading-demo/
├── public/
│   └── index.php
├── src/
│   ├── GreetingService.php
│   └── Router.php
└──

文件 src/GreetingService.php：

<?php

declare(strict_types=1);

final class GreetingService
{
    public function greet(string $name): string
    {
        return '你好，' . $name . '！';
    }
}

文件 src/Router.php：

<?php

declare(strict_types=1);

final class Router
{
    public function dispatch(string $method, string $path): string
    {
        if ($method === 'GET' && $path === '/hello') {
            $name = $_GET['name'] ?? '访客';

            if (!is_string($name)) {
                http_response_code(400);
                return '参数 name 必须是单个字符串';
            }

            $name = trim($name);

            if ($name === '' || strlen($name) > 80) {
                http_response_code(400);
                return '参数 name 不能为空，且 UTF-8 字节长度不能超过 80';
            }

            $service = new GreetingService();
            return $service->greet($name);
        }

        http_response_code(404);
        return 'Not Found';
    }
}

文件 public/index.php：

<?php

declare(strict_types=1);

require __DIR__ . '/../src/GreetingService.php';
require __DIR__ . '/../src/Router.php';

$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';
$path = parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH);

if (!is_string($path)) {
    http_response_code(400);
    exit('无效的请求路径');
}

$router = new Router();
$body = $router->dispatch($method, $path);

header('Content-Type: text/plain; charset=utf-8');
echo $body;

在项目根目录启动 PHP 内置开发服务器：

php -S 127.0.0.1:8000 -t public

浏览器打开 http://127.0.0.1:8000/hello?name=小明，应看到问候文本。试试不存在的路径，会得到 404；不传 name 则使用默认值。也可以用命令行请求：

curl 'http://127.0.0.1:8000/hello?name=%3Cscript%3Ealert(1)%3C%2Fscript%3E'

这个示例把路由参数交给服务，再由入口输出响应，便于观察调用链。它刻意没有实现通用路由、模板、数据库、依赖注入或完整的 HTTP 规范处理，不应直接作为生产框架使用。

五、示例中的参数限制与安全边界

示例检查了 name 是否为字符串、去除首尾空白后是否为空，以及其长度是否超过 80 个字节。这里使用 strlen()，计算的是字节数，不是用户看到的字符数。UTF-8 中文字符通常占多个字节，因此提示特意写成“字节长度”。如果需求是限制 Unicode 字符数量，应使用多字节字符串函数，并确认服务器启用了相应扩展，例如 mb_strlen()。

PHP 请求解析后的输入可能不是简单字符串。例如查询参数 ?name[]=a 会产生数组。因此示例先用 is_string() 检查，避免直接把数组传入要求字符串的服务方法。真实应用还需按业务定义校验规则：允许的字符、最大长度、格式、是否可为空，都应有明确依据，而不是随意复制一个固定上限。

示例返回的是 text/plain，并没有把输入作为 HTML 执行。若改为输出 HTML，就必须对输出位置进行正确的上下文转义；普通文本、HTML 属性、JavaScript 和 URL 的转义规则并不相同。用 htmlspecialchars() 可以处理常见 HTML 文本输出，但不能替代所有上下文的安全编码，也不能修复 SQL 注入、命令注入或路径穿越等其他问题。

输入校验不等于授权。即便参数格式合法，也要确认当前用户是否有权访问对应资源。安全还涉及认证、授权、CSRF 防护、SQL 参数绑定、上传文件处理、密钥管理和错误信息控制等多个方面。阅读源码时，应该分别寻找这些机制在哪一层实现，并验证具体路径是否确实经过它们。

示例没有设置请求参数的全局大小限制，也没有声明适用于所有场景的参数上限。PHP 中与请求相关的限制可能来自 PHP 配置、Web 服务器、代理、框架和业务校验，彼此作用范围不同。例如，upload_max_filesize 约束单个上传文件大小，post_max_size 约束 POST 请求体大小；它们不能代替业务层的文件类型、权限和内容检查。具体值应查看目标环境的有效配置与部署链路，不能假定本机和线上一致。

六、实际读大型项目时的步骤

步骤一：记录运行条件

先记下 PHP 版本、扩展要求、启动方式、配置来源和环境差异。查看 composer.json 中的 PHP 版本约束，并运行 php -v、php -m 了解当前 CLI 环境。它们只能说明当前命令行环境；若项目运行在 PHP-FPM、容器或远程服务器上，还要核对对应环境。

步骤二：找到入口清单

列出 Web、CLI、队列、定时任务等入口，不要只追一个 index.php。查看部署配置和 Composer 脚本，弄清楚生产环境实际调用了什么命令。入口之间可能共享业务代码，但具有不同的初始化、权限和错误处理方式。

步骤三：选一条具体业务路径

挑一个输入明确、结果可观察的功能，比如登录、商品查询或生成报表。记录请求来源、路由、处理方法、调用的服务、数据存储和最终响应。可以把关键文件名和调用关系写成简短列表，避免在多个目录间来回跳转后忘记路径。

步骤四：查找配置与实现绑定

如果看到接口、抽象类、工厂或容器调用，继续查“谁创建它、谁注册它、运行时选哪个实现”。如果配置值来自环境变量或配置文件，就追到读取位置，并确认缺省值和覆盖顺序。不要只看到接口名称就断言系统一定使用某个实现。

步骤五：用测试和调试验证推断

测试用例是理解预期行为的高效入口，但测试通过不自动证明线上配置相同。可以运行相关测试、在本地发送请求，或在安全环境中添加日志和断点。日志中避免记录密码、访问令牌等敏感信息；调试输出也不应留在生产响应里。

需要搜索符号时，可用编辑器的“查找引用”、grep 或代码索引工具。搜索结果不一定覆盖动态调用、字符串形式的类名、生成代码或框架约定；发现只有配置或反射调用时，应扩大搜索范围，并结合测试验证。

七、容易踩的坑

• 从根目录开始逐个文件读。这样会把时间花在无关依赖和生成文件上。先识别入口和目标功能，再按调用关系深入。
• 看到目录名就套用框架经验。不同项目可能使用相同名字表达不同职责。以实际调用、配置和测试为准。
• 把路由、控制器和业务逻辑混为一谈。路由负责选择处理路径，控制器通常协调输入与输出，业务规则可能位于服务或领域对象中；这些只是常见划分，需按项目验证。
• 只看正常返回，不看异常路径。检查异常捕获、事务回滚、重试和错误响应。尤其注意发生数据库写入后，后续操作失败会留下什么状态。
• 假设请求参数一定是字符串。数组参数、缺失值和编码错误都可能出现。确认数据来源、类型和校验时机。
• 把静态搜索结果当成完整调用图。依赖注入、反射、魔术方法、自动发现和事件系统会让调用关系不直观，需要从容器配置、事件注册和运行测试补齐。
• 混淆 CLI 与 Web 环境。两者的 SAPI、配置、当前工作目录和可用扩展可能不同。相对路径尤其容易因此出错；项目通常更适合用基于 __DIR__ 的明确路径。
• 只靠代码推断生产行为。Web 服务器规则、反向代理、PHP-FPM 参数和环境变量也会影响行为。部署配置是程序边界的一部分。

八、如何判断已经理清执行流程

读完一个功能后，试着不看代码回答以下问题：从哪里启动？用户输入从哪里来？经过哪些校验和授权？哪个函数决定业务结果？哪些操作会改变数据库或外部状态？异常如何转换为响应？关键配置来自哪里？不同运行环境有哪些可能差异？

如果这些问题能用具体文件、函数和配置项回答，并能通过测试或本地请求验证，通常已经建立了足够可靠的执行模型。若只能描述“框架会自动处理”，却说不清由什么配置、哪段代码处理，就还需要继续追踪。

结语

读 PHP 源码的核心不是记住某个框架的目录模板，而是建立可验证的运行路径：确认程序入口，顺着真实输入找到处理逻辑，再追到数据、副作用和响应。先读少量关键文件，遇到不确定的行为就查配置、测试并动手验证，比一次性通读全仓库更快，也更不容易把惯例误当成事实。