一个跑了三年的项目,入口文件开头有三十多行 require。每加一个功能,就要在末尾补一行;有一次上线漏传了 upload.php,直到用户点上传才 500。后来有人把 helpers.php 改名为 utils.php,忘了改某处的 require,整个后台白屏。最麻烦的是,谁也不敢删任何一个文件,因为不知道还有没有地方在用它。

这些问题的根源不是「没写自动加载」,而是项目没有边界。文件靠手写路径引入,类靠全局名字区分,入口文件同时负责配置、数据库、路由和渲染。项目小的时候都能跑,一大就变成一团。这篇讲两件事:PHP 的类是怎么被自动找到的,以及一个 Web 项目的目录该怎么分。

自动加载:PHP 找不到类时会问谁

PHP 执行到 new Product() 时,发现当前已加载的文件里没有这个类,就会触发「自动加载」机制,依次调用注册过的加载函数。加载函数负责把类名换算成文件路径,然后引入文件。

手写一个最小的加载器,能看清原理:

<?php
declare(strict_types=1);

spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }

    $relative = substr($class, strlen($prefix));
    $file = __DIR__ . '/src/' . str_replace('\\', '/', $relative) . '.php';

    if (is_file($file)) {
        require $file;
    }
});

$product = new App\Catalog\Product(); // 自动引入 src/Catalog/Product.php

这段代码把命名空间前缀 App\ 映射到 src/ 目录,把命名空间的分隔符换成目录分隔符,再拼上 .php。这就是 PSR-4 的全部核心规则,Composer 只是帮你把这个函数生成好,顺便处理多个前缀、缓存和优化。

实际项目不会自己写这个函数,而是用 Composer 生成:

{
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  }
}

写好之后执行 composer dump-autoload,然后在入口文件引入 vendor/autoload.php,所有 App\ 开头的类就能按需加载。新增类不需要再改任何 require。

加载链条全部走完还没人接手,PHP 才会抛出那句最熟悉的报错:PHP Fatal error: Uncaught Error: Class "App\Order\OrderService" not found in /var/www/app/src/Order/Checkout.php:42。它只给两样信息:类名,以及第一次用到这个类的文件和行号。它不会告诉你框架找过哪些路径,所以盯着报错本身猜没用,得自己验证。

比较省时间的查法是固定顺序,每一步排除一类原因。先看报错里的完整类名和文件顶部的 use 是否一致,App\Order\OrderService 对 use App\Orders\OrderService; 这种差一个字母的情况,问题在拼写,不在自动加载。接着在入口临时打印 get_included_files(),确认 vendor/autoload.php 被引入了,目标类文件也在列表里。再用 class_exists() 直接问加载器,它默认第二个参数为 true,会真的触发一次加载。最后重建映射、核对依赖。

$ php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\\Order\\OrderService'));"
bool(false)
$ composer dump-autoload -o
Generated optimized autoload files containing 12 classes
$ php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\\Order\\OrderService'));"
bool(true)

两次输出把问题切成了两半。一直是 bool(false),说明映射或路径不对,去看 composer.json 的 psr-4 前缀、类文件的真实位置、文件名大小写。变成 bool(true) 但页面还是报错,说明类能加载,问题在别处:可能 OPcache 里还是旧文件,也可能报错的是另一个名字相近的类。依赖本身缺失时,composer show 能看到实际装了哪些包和版本,composer why-not 包名 版本 能说清为什么装不上,比在 vendor 目录里翻文件快。

本机 PHP 8.3.36 + Composer 2 实测复现了这个顺序:在 composer.json 新增一个 PSR-4 前缀但不跑 dump,class_exists() 返回 bool(false);执行 dump-autoload -o 输出 12 classes,再查变成 bool(true)。类数随项目大小变化,不要照抄某个固定数字。

PSR-4 的三条硬规则

规则不多,但每一条都有实际后果:

  • 一个类一个文件:文件名必须与类名完全一致,包括大小写。Linux 区分大小写,OrderService.php 和 orderService.php 是两个文件。
  • 命名空间对应目录:App\Order\OrderService 对应 src/Order/OrderService.php,层级不能错。
  • 命名空间声明在文件最前面:namespace 之前只能有 <?php 和注释,不能有输出、不能有别的代码。
<?php
declare(strict_types=1);

namespace App\Order;

final class OrderService
{
    // ...
}

规则听着简单,错位无非两种。第一种是前缀和根目录没对齐:composer.json 写 "App\\": "src/",类里也写了 namespace App\Order;,文件却放在 app/Order/OrderService.php。加载器只会拼出 src/Order/OrderService.php,找不到就放弃,不会去猜 app/。第二种是多一层或少一层:"App\\": "src/App/" 时,App\Order\OrderService 应该落在 src/App/Order/OrderService.php,少写这一级 App 就永远对不上;反过来,命名空间是 App\Order\Service\OrderService,文件却只放到 src/Order/OrderService.php,结果一样。判断方法很土但有效:把类名按反斜杠切开,第一段对应 composer.json 的前缀,剩下的逐段对应目录,最后一段加 .php,拿这个路径去 ls,对得上就是对的。

历史上还有一个 __autoload() 函数,PHP 7.2 起废弃、8.0 移除。它的缺点是只能注册一个加载器,多个库同时用会互相覆盖。spl_autoload_register() 可以注册多个,按注册顺序依次尝试,这也是 Composer 能和别的加载器共存的原因。老代码里如果还留着 __autoload,升级到 8.x 会直接 fatal,这属于第 12 篇要清理的清单。

除了 PSR-4,Composer 还支持 classmap 和 files。classmap 是扫描目录生成「类名到文件」的静态表,适合不符合 PSR-4 的老代码;files 在每次启动时直接引入文件,适合放全局函数,但会拖慢启动,能不用就不用。

生产环境可以执行 composer dump-autoload -o,把 PSR-4 映射转成 classmap。这样加载类时不用做文件存在性检查,配合 OPcache 更快。类很多的大项目收益明显,小项目差别不大。

还有一个常被忽略的开关:在 composer.json 里设 "classmap-authoritative": true,加载器就只信映射表,不再回退到文件系统查找。好处是找不到类时立刻失败,不会每次都去 stat 一串不存在的路径;代价是映射表必须完整,少一个类就是直接 fatal。所以它适合构建产物固定的生产环境,不适合边写边跑的本地,本地新增文件后忘了 dump,会得到「文件明明在,就是找不到类」的怪现象。

想确认前缀究竟被解析到哪个目录,不用猜,直接看 Composer 生成的结果:vendor/composer/autoload_psr4.php 里是一张前缀到目录的数组,vendor/composer/autoload_classmap.php 是类名到文件的完整映射。排查「映射和预期不一致」时,打开这两个文件比反复改 composer.json 快得多。

目录怎么分:public、src、config

一个能被维护的 PHP Web 项目,最低限度要有这几块:

public/唯一对外的目录。里面放 index.php 入口和静态资源。Web 服务器的根目录指向这里,其他目录一律不可直接访问。
src/业务代码。按命名空间分目录,比如 Catalog、Order、User。类在这里,不在这里输出 HTML。
config/配置和密钥。放在 Web 根目录之外,代码里通过路径读取,绝不放在 public 下。
tests/ 与 vendor/测试代码和 Composer 安装的依赖。都不对外暴露,vendor 不进版本库。

典型结构可以对照下面这张表,重点是「谁对外」:

目录 / 文件放什么对外可访问
public/入口 index.php、样式、图片等静态资源是,Web 根目录只指向这里
src/业务类,按命名空间分目录否
config/配置数组、密钥读取逻辑否
tests/测试代码否
vendor/Composer 安装的依赖否
composer.json / composer.lock依赖声明与锁定结果否

目录不需要一次到位。一个只有几个页面的小站,先做到「入口在 public、配置不在 Web 根目录、业务代码有命名空间」就够了。等模块多到互相调用、测试开始难写,再拆 Repository、Service 这些层。结构是为了降低改动成本,不是为了符合某张架构图。

真要迁移,也分阶段做,别一个提交把目录全挪了。第一阶段只改 Web 根目录和入口:加 public/、把入口移进去、Nginx 的 root 改过去,其他文件原地不动,先保证访问正常。第二阶段把配置和数据库连接抽出来,去掉散落在页面里的密码。第三阶段才在 src/ 下按业务建目录、加命名空间、配 PSR-4,一个模块一个模块搬。每阶段都能独立上线、独立回滚。一次性大搬家的问题是,出事后你不知道是搬错了路径、漏了文件,还是 Nginx 配置没生效,排查范围一下变大好几倍。

入口文件只做三件事:引入自动加载、读取配置、把请求交给应用。它不应该出现 SQL、HTML、业务判断:

<?php
declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

$config = require dirname(__DIR__) . '/config/app.php';

$pdo = new PDO($config['dsn'], $config['db_user'], $config['db_pass'], [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES => false,
]);

$app = new App\Application($pdo, $config);
$app->handle($_SERVER['REQUEST_URI'] ?? '/');

这样拆分的好处,不只是「看起来整齐」。入口文件变成稳定的一小段,新增页面不用动它;业务类可以单独测试;配置集中,换环境只改一处;Web 根目录只有 public,源码和密钥不会被直接下载。

把项目根目录直接设成 Web 根目录,是最常见也最危险的偷懒。这样 .env、composer.json、src/、数据库备份文件都可能被直接访问。Nginx 的 root 必须指向 public/。

这条不能只写在文档里,要实际请求验证。内置服务器启动时把文档根指定为 public,然后分别请求入口和一个不该暴露的文件:

php -S 127.0.0.1:8000 -t public
curl -i http://127.0.0.1:8000/index.php
HTTP/1.1 200 OK

curl -i http://127.0.0.1:8000/composer.json
HTTP/1.1 404 Not Found

第一条 200 说明入口正常,第二条 404 说明项目根目录的文件没有被暴露。换到 Nginx 上验证方式一样,只是把地址换成线上域名,curl -I https://example.com/config/app.php,头一行是 404 才算通过;如果返回 200 还能看到内容,就是 root 指错了,先改配置再谈别的。

命名空间:解决同名,也暴露边界

没有命名空间时,两个文件都定义 class Product 会直接致命错误。命名空间给类加上前缀,避免冲突,也让依赖关系看得见:看到 App\Catalog\Product,就知道它属于商品模块。

use 语句只是起别名,不加载文件。真正的加载发生在第一次使用这个类时:

<?php
namespace App\Order;

use App\Catalog\Product;
use App\Catalog\ProductRepository as CatalogRepo;

final class OrderService
{
    public function __construct(
        private CatalogRepo $products,
    ) {}
}

要记住 PSR-4 只管类。命名空间里的函数和常量不会被自动加载,use function App\Support\format_money; 只是省了写全名,文件没被引入照样报 Call to undefined function。所以项目里的全局函数要么放进 Composer 的 files 配置,要么干脆写成静态方法,别指望类加载器顺手把函数带进来。

还有一种常见问题:命名空间和文件名都对,但类里 use 了一个不存在的类,只有实际执行到那一行时才报错,不做静态检查很难提前发现。CI 里跑一遍静态分析工具,能在合并前拦住这类问题,比上线后翻日志便宜得多。

命名空间的划分应该跟着业务走,而不是跟着技术分层(Controllers、Models、Services)走。按业务分,改动一个功能时相关文件都在一个目录;按技术分,一个功能的类散落在四五个目录,改起来要来回跳。小项目尤其没必要上来就搞四层架构。

配置:别把密码写进代码

配置有两种常见形态:返回数组的 PHP 文件和 .env 环境变量文件。前者适合结构化配置,后者适合部署时注入的密钥。

<?php
// config/app.php
return [
    'dsn' => getenv('DB_DSN') ?: 'mysql:host=127.0.0.1;dbname=shop;charset=utf8mb4',
    'db_user' => getenv('DB_USER') ?: 'app',
    'db_pass' => getenv('DB_PASS') ?: '',
    'debug' => filter_var(getenv('APP_DEBUG') ?: 'false', FILTER_VALIDATE_BOOL),
];

密钥用环境变量注入,.env 只作为本地开发便利,必须加进 .gitignore。生产环境的 debug 必须关闭,否则错误页会把路径、SQL、甚至密钥显示给用户。

配置读取要有默认值,但默认值不能是「生产可用的弱密码」。宁可启动时报错,也不要悄悄用一个空密码连上数据库。

配置合并也要小心。array_merge() 让后者覆盖前者,但不会递归合并嵌套数组;外层键一覆盖,内层的默认值整块丢失。需要递归合并时用 array_replace_recursive(),并写一个测试确认默认值还在。这类问题通常只在某个环境缺配置时才出现,平时看不出来。

场景走查:把 800 行的 index.php 拆开

需求不是加功能,而是「让它还能改」。现状:index.php 八百行,开头连数据库、中间处理表单、下面输出 HTML,上传和留言都混在里面。

第一步先拆目录,不改逻辑:把入口移到 public/index.php,静态资源也挪进 public/,配置抽到 config/app.php,数据库连接和页面渲染各自抽成函数放进 src/。这一步就能解决「根目录被直接访问」的风险。

第二步引入 Composer,配置 PSR-4,把函数改成类:MessageRepository 负责查和写,MessageController 负责校验和响应,模板单独放 templates/。入口文件缩到二十行左右。

<?php
namespace App\Message;

final class MessageRepository
{
    public function __construct(private \PDO $pdo) {}

    /** @return array<int, array{id: int, name: string, text: string}> */
    public function latest(int $limit = 20): array
    {
        $stmt = $this->pdo->prepare(
            'SELECT id, name, text FROM messages ORDER BY id DESC LIMIT :limit'
        );
        $stmt->bindValue(':limit', $limit, \PDO::PARAM_INT);
        $stmt->execute();

        return $stmt->fetchAll();
    }
}

第三步改 Nginx,把 root 指向 public,确认 /config/app.php、/src/... 访问不到。第四步在测试环境跑一遍所有页面,重点检查大小写、文件是否都提交、vendor 是否正确安装。

上线时踩了两个坑,报错都是同一句 Class "App\Message\MessageRepository" not found,原因却完全不同。第一个是文件名:本地 Windows 的文件系统不区分大小写,文件叫 messageRepository.php,类声明写的是 class MessageRepository,new 的时候照样能找到。传到 Linux 的 ext4 上,加载器拼出的路径是 src/Message/MessageRepository.php,目录里实际只有小写开头的那一个,于是直接 fatal。

确认方法是在服务器上按类名反推路径,再用 ls 看真实文件名:

$ ls src/Message/
messageRepository.php
$ grep -n '^class' src/Message/messageRepository.php
12:class MessageRepository
$ mv src/Message/messageRepository.php src/Message/MessageRepository.php

第二个是 vendor 没重建。部署脚本只 rsync 了 src/,没跑 composer dump-autoload,新类根本没进映射表。判断依据不是猜,而是看 Composer 生成的映射里有没有这个名字:执行 composer dump-autoload -o 后再 grep MessageRepository vendor/composer/autoload_classmap.php,有输出说明已收录,没有就是漏了。两个坑的共同教训是,部署脚本必须包含重建自动加载这一步,而且顺序要放在切换软链之前,否则新代码会有一小段时间指向旧映射。

本地想复现大小写问题,不能靠 Windows。用 Docker 挂载代码跑一个 Linux 容器,或者直接在服务器上执行 php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\\Message\\MessageRepository'));",输出 bool(true) 才算通过;输出 bool(false) 就继续按上面的顺序查路径和映射。

现象、原因与第一步

现象真实原因第一步查什么
Class not found自动加载没注册、命名空间与目录不匹配、文件没提交执行 composer dump-autoload,核对类名与路径
本地正常,Linux 上找不到类文件名大小写不一致逐字比对文件名与类名
改了文件名后全站白屏还有地方在硬编码 require 旧路径全局搜索旧文件名;改用自动加载
两个模块的类互相覆盖没有命名空间,类名全局唯一给每个模块加命名空间,检查 use
访问 /config/app.php 能看到密码Web 根目录指向了项目根目录检查 Nginx root 是否指向 public
namespace 声明报错声明前有输出、BOM 或别的代码确认 <?php 后第一件事就是 namespace
新增类不生效OPcache 或 autoload 缓存没刷新重启 FPM,执行 dump-autoload -o
生产环境报错页显示 SQL 和路径配置里 debug 为 true检查环境变量和配置合并逻辑

边界与代价

分层不是越多越好。一个只有五个页面的小站,拆成 Controller、Service、Repository、DTO 四层,改一个字段要动五个文件,维护成本远高于收益。结构应该跟着复杂度长,而不是一开始就按「大厂架构」搭。

自动加载不是没有成本。每个请求都会注册加载器,第一次用到类时做文件查找;类多、目录深时开销更明显。OPcache 和 dump-autoload -o 能把这个成本压到很低,但前提是部署时真的执行了这些步骤。

命名空间能避免冲突,但不能代替模块边界。两个模块互相 use 对方的内部类,说明边界没划清;命名空间只是让这种耦合更明显,不会自动消除它。

目录结构也没有唯一答案。有人喜欢按业务分,有人喜欢按层分;团队统一、能说清楚每个目录放什么,比照搬某个「最佳实践」更重要。

当天能自己验证的练习

  1. 不用 Composer,手写一个 spl_autoload_register,让 App\Demo\Hello 自动加载 src/Demo/Hello.php。
  2. 把类文件名改成小写,在 Linux 容器或区分大小写的环境里访问,观察报错;改回来确认恢复。
  3. 用 Composer 配置 PSR-4,新增一个类,不执行 dump-autoload 直接访问,看是否报错;执行后再试。
  4. 把项目根目录设为 Web 根目录,访问 /config/app.php 和 /composer.json,确认能看到内容;再改成 public 验证访问不到。
  5. 写一个只做三件事的入口文件:加载 autoload、读配置、调用应用类。把原来页面里的 SQL 和 HTML 全部移出去。

小结

三句话:自动加载解决「类怎么被找到」,PSR-4 把命名空间映射到目录,文件名必须和类名一致;Web 根目录只指向 public,源码和配置放在它外面;入口文件只负责引导,业务逻辑放进类里。

下一篇讲部署。结构分好了,代码也自动加载了,接下来要让它在一台真实的服务器上跑起来:Nginx 怎么把请求交给 FPM、进程数怎么算、OPcache 为什么让改动的代码不生效、线上 502 和 504 到底差在哪。下一篇从「本地好好的,一上线就 502」开始。