04.4 阶段 3:Composer、PSR 与工程化
本页目录
一、阶段定位
前两个阶段解决"写得对、类型准"。本阶段解决"在团队里怎么组织代码、怎么引入第三方包、怎么让测试和检查一条命令跑完"。PHP 生态的工程化几乎全部围绕 Composer 与 PSR 展开:composer.json 是项目的身份证,PSR-4 决定类怎么被找到,PHPUnit 决定代码怎么被验证,PHPStan 决定 bug 怎么被提前发现。
与前后阶段的衔接:往上是 04.3 阶段 2 类型系统与现代特性,本阶段的 PHPStan 静态分析就是建立在类型声明之上;往下接 04.5 阶段 4 框架主线 Laravel,Laravel 本身就是一个 Composer 包,artisan 命令、服务容器、门面全靠 PSR-4 与 PSR-11 组织。跳过本阶段直接学 Laravel,会在"为什么 composer require laravel/framework 之后类就能用""vendor/ 目录要不要提交""为什么线上要 composer install --no-dev"这些问题上反复返工。
原始卡点展开成可判断的现象依据:
- 自动加载找不到类:判断标准是
new App\Service\UserService()报Class "App\Service\UserService" not found,但文件确实存在——说明命名空间与目录映射、或composer dump-autoload没跑。 - 版本约束过宽导致依赖冲突:判断标准是
composer require时报Your requirements could not be resolved to an installable set of packages,两个包要求同一依赖的不同版本。 - 静态分析一上来拉满级别:判断标准是 PHPStan level 9 一跑几百条错误,团队直接放弃——正确做法是从 level 5 起步、用基线治理存量。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
能读懂并手写 composer.json 的 require/autoload/scripts |
新建一个包,composer install 干净环境可复现 |
| 能解释 PSR-4 命名空间到目录的映射规则 | 故意改错一个目录名,复现 Class not found 后修复 |
| 能写 PHPUnit 单元测试、数据提供器与 Mock | ./vendor/bin/phpunit 通过,覆盖率报告生成 |
| 能在项目里接入 PHPStan 并从 level 5 起步 | phpstan analyse 无错误输出 |
| 能接入 PHP-CS-Fixer 自动格式化 | CI 里跑 php-cs-fixer fix --dry-run 无差异 |
| 能用 Xdebug 在 CLI 与 FPM 下打断点 | 命中断点,查看变量与调用栈 |
建议学时:
- 全职(每天 4–6 小时):2 周,约 50 小时。
- 在职(每天 2 小时、周末补 3 小时):4 周,约 50 小时。
学时分配:composer.json 与版本约束 20%、PSR-4 自动加载 15%、PHPUnit 20%、PHPStan 15%、代码规范 10%、调试与日志 10%、私有仓库与 scripts 10%。PHPUnit 与 PHPStan 是日常最高频,时间给够。
三、先修自检
| 先修项 | 合格标准 | 不合格时回到 |
|---|---|---|
| PHP 8.x 可用 | php -v 输出 8.x |
04.1 阶段 0 环境与工程基础 |
| 命名空间与类 | 能写 namespace 与 class | 04.2 阶段 1 语言核心 |
| 类型声明 | 函数与类属性有类型 | 04.3 阶段 2 类型系统与现代特性 |
| Git | 能 commit、push | 04.1 阶段 0 环境与工程基础 |
经验判断:写过 Node.js 的人会把 Composer 类比 npm,但 Composer 的 vendor/ 目录通常提交到仓库(PHP 没有统一运行时环境,vendor 是依赖快照);写过 Java Maven 的人会发现 Composer 的 PSR-4 比 Maven 的 classpath 更简单直接。
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| composer.json | require、require-dev、autoload、scripts、config、minimum-stability |
能讲清原理 | 06.1 通用后端工程 |
| 版本约束 | ^、~、*、精确版本、dev-master、|| 与 , |
会用 | 06.1 通用后端工程 |
| PSR-4 自动加载 | 命名空间前缀→目录映射、classmap、files、dump-autoload -o |
能讲清原理 | 06.1 通用后端工程 |
| composer.lock | 锁文件作用、install 与 update 区别、--no-dev |
能讲清原理 | 06.1 通用后端工程 |
| PSR 规范 | PSR-1/12 风格、PSR-3 日志、PSR-7 HTTP、PSR-11 容器、PSR-15 中间件 | 了解 | 06.1 通用后端工程 |
| PHPUnit | 断言、数据提供器、Mock、extends TestCase、vendor/bin/phpunit |
会用 | 06.1 通用后端工程 |
| PHPStan | level 0–9、baseline 基线、ignoreErrors、扩展 |
会用 | 06.1 通用后端工程 |
| 代码规范 | PHP-CS-Fixer、PHP_CodeSniffer、--dry-run |
会用 | 06.1 通用后端工程 |
| 调试与日志 | Xdebug 断点、var_dump/dump、PSR-3 日志级别 |
会用 | 06.1 通用后端工程 |
进度管理建议:PSR-4 映射规则与 composer.lock 作用能口述清楚再进阶段 4。全量清单见 04.10 知识点全清单。
五、分模块精讲
5.1 composer.json 结构与版本约束
为什么需要它:composer.json 是项目的依赖清单与工程配置。版本约束写错,要么装不到安全补丁,要么与其他包冲突。
核心机制:
- 关键字段:
name(vendor/package)、description、type(library/project)、require(生产依赖)、require-dev(开发依赖)、autoload(自动加载)、autoload-dev(测试自动加载)、scripts(自定义命令)、config(如platform.php指定 PHP 版本)。 - 版本约束符号:
^7.4:>=7.4.0 <8.0.0(兼容次版本与补丁);~7.4.5:>=7.4.5 <7.5.0(只兼容补丁);7.4.*:>=7.4.0 <7.5.0;7.4.5:精确版本;dev-master:开发分支;,表示且,||表示或。
minimum-stability:stable(默认)、RC、beta、alpha、dev;prefer-stable: true优先稳定版。
最小可运行示例:
{
"name": "ann/order-service",
"type": "project",
"require": {
"php": "^8.2",
"ext-pdo": "*",
"ext-redis": "*",
"monolog/monolog": "^3.0"
},
"require-dev": {
"phpunit/phpunit": "^11.0",
"phpstan/phpstan": "^1.10",
"friendsofphp/php-cs-fixer": "^3.0"
},
"autoload": {
"psr-4": { "App\\": "src/" }
},
"autoload-dev": {
"psr-4": { "Tests\\": "tests/" }
},
"scripts": {
"test": "phpunit",
"phpstan": "phpstan analyse src --level=5",
"cs": "php-cs-fixer fix --dry-run"
}
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
composer require 报依赖冲突 |
两个包要求同一依赖不同版本 | 放宽或收紧约束,看 composer why-not |
| 装到了非稳定版 | minimum-stability 太低 |
设 stable,个别包单独标 @dev |
ext-* 提示缺失 |
当前 PHP 没装该扩展 | 装扩展,或在 config.platform 里模拟 |
面试考法:"^ 与 ~ 区别""require 与 require-dev 区别"。答到:^ 锁定主版本,~ 锁定次版本;require 是生产必需,require-dev 只在开发/测试环境安装,线上 --no-dev 不装。
5.2 PSR-4 自动加载与 composer.lock
为什么需要它:PHP 没有内建的"按类名找文件"机制。PSR-4 约定命名空间前缀映射到目录,Composer 在运行时生成自动加载器,new App\Service\UserService() 才会自动 include src/Service/UserService.php。
核心机制:
- PSR-4 规则:命名空间前缀
App\映射到目录src/;类名App\Service\UserService去掉前缀后剩余Service\UserService,对应文件src/Service/UserService.php。 - 自动加载方式:
psr-4(按前缀映射,最常用)、classmap(扫描目录生成类名→文件映射)、files(总是加载的文件,如 helpers)。 composer dump-autoload重新生成vendor/autoload.php;加-o生成优化版(classmap 权威映射,生产用)。composer.lock:记录每个依赖的精确版本与哈希;composer install按 lock 安装,composer update更新 lock。生产环境只跑install,不跑update。
最小可运行示例:
# 新建包
composer init
composer require monolog/monolog
composer install --no-dev --optimize-autoloader # 生产环境
composer dump-autoload -o # 优化自动加载
<?php
// 任何入口文件第一行
require __DIR__ . '/vendor/autoload.php';
use App\Service\UserService;
$svc = new UserService(); // 自动加载 src/Service/UserService.php
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
Class "App\Service\UserService" not found |
目录与命名空间不对应,或没 dump-autoload | 核对 src/Service/UserService.php 的 namespace 是 App\Service |
| 新增类找不到 | 改了 autoload 配置没重新 dump | 跑 composer dump-autoload |
| 线上与本地版本不一致 | 线上跑了 composer update |
线上只跑 composer install --no-dev |
| 生产自动加载慢 | 没优化 | 加 -o,或用 classmap-authoritative |
面试考法:"PSR-4 与 PSR-0 区别""composer install 与 update 区别"。答到:PSR-4 类名后缀直接映射目录,不再强制目录与命名空间完全一致;install 按 lock 装,update 重新解析约束并写新 lock。
5.3 Composer 命令、scripts 与私有仓库
为什么需要它:团队私有包(内部 SDK、公共组件)需要通过 Composer 安装,而不是复制粘贴。scripts 把"测试、检查、格式化"串成一条命令。
核心机制:
- 常用命令:
composer require、composer remove、composer update、composer install、composer dump-autoload、composer outdated、composer show、composer why vendor/package。 - scripts:在
composer.json的scripts里定义,用composer test这样的短命令调用;支持事件(pre-install-cmd、post-autoload-dump)。 - 私有仓库:在
repositories里配vcs(Git 仓库)或path(本地路径);凭据存在auth.json,不提交到仓库。
最小可运行示例:
{
"repositories": [
{ "type": "vcs", "url": "git@gitlab.example.com:ops/common-sdk.git" },
{ "type": "path", "url": "../local-package" }
],
"config": {
"allow-plugins": { "phpstan/extension-installer": true }
}
}
composer require ann/common-sdk:^1.0
composer test # 等价于 composer.json scripts.test
composer phpstan # 自定义命令
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 私有包凭据进了仓库 | auth.json 被提交 |
加进 .gitignore,用环境变量注入 |
composer install 在 CI 上失败 |
私有仓库无凭据 | CI 里配 auth.json 或 SSH key |
| 插件被禁用 | allow-plugins 没配 |
在 config 里显式允许 |
面试考法:"Composer 怎么接私有 Git 仓库"。答到:在 repositories 里加 vcs 类型,配 SSH key 或 token,凭据放 auth.json 不提交。
5.4 PSR 编码与互操作规范
为什么需要它:PSR 是 PHP 框架互操作的基础。不懂 PSR-11 容器、PSR-15 中间件,就读不懂 Laravel/Symfony 的源码。
核心机制:
- PSR-1:基础编码规范(文件声明、类名大驼峰、常量大写)。
- PSR-12:扩展 PSR-2 的风格规范(缩进 4 空格、行宽控制)。
- PSR-3:日志接口(
LoggerInterface,8 个级别:emergency/alert/critical/error/warning/notice/info/debug)。 - PSR-7:HTTP 消息接口(Request/Response/Uri)。
- PSR-11:容器接口(
ContainerInterface,只有get($id)与has($id)两个方法)。 - PSR-15:中间件接口(
MiddlewareInterface::process(Request, RequestHandler): Response)。
最小可运行示例:
<?php
use Psr\Container\ContainerInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Log\LoggerInterface;
class AuditMiddleware implements MiddlewareInterface {
public function __construct(private LoggerInterface $logger) {}
public function process(
ServerRequestInterface $request,
RequestHandlerInterface $handler
): ResponseInterface {
$this->logger->info('访问:' . $request->getUri()->getPath());
return $handler->handle($request);
}
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 不同框架的日志器不兼容 | 没依赖 PSR-3 接口 | 类型提示用 LoggerInterface |
容器 get 抛 NotFoundExceptionInterface |
键未注册 | 先 has() 判断 |
面试考法:"PSR-11 为什么只有两个方法"。答到:容器接口越小,越容易在不同框架间移植;实现细节(自动装配、注解)由各框架自己扩展。
5.5 PHPUnit 单元测试与 Mock
为什么需要它:没有测试的代码重构靠勇气。PHPUnit 是 PHP 事实标准,掌握它是进入任何团队的底线。
核心机制:
- 测试类
extends TestCase,测试方法public function testXxx()或带#[Test]属性。 - 断言:
assertEquals、assertSame(严格相等)、assertNull、assertThrows(PHPUnit 10+)、assertCount。 - 数据提供器
#[DataProvider]:同一段测试逻辑跑多组输入。 - Mock:
$this->createMock(UserRepository::class),替换外部依赖,测试只测当前类。 - 测试应隔离:不依赖数据库、网络、文件系统;这些用 Mock 替换。
最小可运行示例:
<?php
use PHPUnit\Framework\TestCase;
class OrderServiceTest extends TestCase {
/**
* @dataProvider priceProvider
*/
public function testTotal(int $price, int $qty, int $expected): void {
$svc = new OrderService();
$this->assertSame($expected, $svc->total($price, $qty));
}
public function priceProvider(): array {
return [
[10, 2, 20],
[0, 5, 0],
[100, 0, 0],
];
}
public function testUserNotFoundThrows(): void {
$repo = $this->createMock(UserRepository::class);
$repo->method('find')->willReturn(null);
$svc = new UserService($repo);
$this->expectException(UserNotFoundException::class);
$svc->findOrFail(999);
}
}
./vendor/bin/phpunit tests/OrderServiceTest.php
./vendor/bin/phpunit --coverage-html coverage/
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
assertEquals(1, "1") 通过 |
弱比较 | 用 assertSame 严格比较 |
| 测试依赖数据库导致慢且不稳定 | 没隔离 | Mock Repository,只测 Service |
| 数据提供器没跑 | 方法名拼错或注解格式错 | 用 #[DataProvider] 属性 |
面试考法:"单元测试为什么要 Mock 外部依赖""assertEquals 与 assertSame 区别"。答到:单元测试只测当前类,外部依赖用 Mock 替换保证隔离;assertEquals 松散比较,assertSame 严格比较(类型与值都相同)。
5.6 PHPStan 静态分析与基线
为什么需要它:PHP 是解释型语言,很多 bug 要运行时才暴露。PHPStan 在不运行代码的情况下推断类型,提前发现"可能 null""未定义方法"等问题。
核心机制:
- 级别 0–9:0 最宽松,9 最严格;新项目从 5 起步,存量项目用基线治理。
- baseline(基线):
phpstan analyse --generate-baseline把现有错误固化到phpstan-baseline.neon,新代码不再允许新增同类错误。 - 常用配置:
paths、level、ignoreErrors、bootstrap。 - 框架扩展:Laravel 用
larastan,Symfony 用phpstan-symfony,让 PHPStan 理解 Facade、Eloquent 魔术方法。
最小可运行示例:
# phpstan.neon
parameters:
level: 5
paths:
- src
ignoreErrors:
- '#Access to an undefined property#'
bootstrap:
- vendor/autoload.php
./vendor/bin/phpstan analyse src --level=5
./vendor/bin/phpstan analyse src --generate-baseline # 生成基线
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 一上来 level 9 几百条错误 | 没渐进治理 | 从 5 起步,用基线 |
| Eloquent 魔术方法报错 | PHPStan 不理解模型动态属性 | 装 larastan,或写 @property 注解 |
| 基线越用越大 | 只加不删 | 每次新代码必须 0 新增 |
面试考法:"PHPStan 与 Psalm 区别""为什么要基线"。答到:PHPStan 规则更严格、生态更广;Psalm 类型推导更强、可自动修复;基线让存量项目在不中断的前提下渐进提升。
5.7 PHP-CS-Fixer 与 PHP_CodeSniffer
为什么需要它:团队风格争论(空格还是 Tab、一行多长)毫无意义,工具自动格式化是唯一解。
核心机制:
- PHP-CS-Fixer:自动修复风格,配置
.php-cs-fixer.dist.php;php-cs-fixer fix直接改文件,--dry-run只检查。 - PHP_CodeSniffer(phpcs):检查风格,
phpcbf自动修复;配置用ruleset.xml。 - 两者二选一即可,团队统一用一个。
最小可运行示例:
// .php-cs-fixer.dist.php
return (new PhpCsFixer\Config())
->setRules([
'@PSR12' => true,
'array_syntax' => ['syntax' => 'short'],
'declare_strict_types' => true,
])
->inDir(__DIR__ . '/src');
./vendor/bin/php-cs-fixer fix --dry-run --diff # CI 检查
./vendor/bin/php-cs-fixer fix # 本地修复
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| CI 里风格检查失败 | 本地没跑 fix | 提交前跑一次,或装 git hook |
| 两套工具冲突 | 同时用了 fixer 与 phpcs | 团队只保留一个 |
面试考法:"为什么要在 CI 里做风格门禁"。答到:避免 review 时争论空格,让 review 聚焦逻辑;本地自动修复,CI 只检查。
5.8 Xdebug 调试与错误日志分级
为什么需要它:var_dump 打日志是最低效的调试方式。Xdebug 能在断点处看变量、调用栈、单步执行;日志分级让生产问题可检索。
核心机制:
- Xdebug 安装:
pecl install xdebug或发行版包;在 php.ini 配zend_extension=xdebug、xdebug.mode=debug。 - CLI 调试:
php -dxdebug.mode=debug script.php;FPM 调试需 IDE(VS Code/PhpStorm)监听端口。 - 生产环境不要长期开 Xdebug,会显著拖慢性能;只在排查时临时开。
- 日志级别(PSR-3):
emergency(系统不可用)、alert(必须立即处理)、critical(紧急)、error(错误)、warning(警告)、notice(重要正常事件)、info(信息)、debug(调试)。
最小可运行示例:
<?php
use Psr\Log\LoggerInterface;
class PaymentService {
public function __construct(private LoggerInterface $logger) {}
public function pay(int $orderId, float $amount): void {
$this->logger->info('发起支付', ['order_id' => $orderId, 'amount' => $amount]);
try {
// ... 调用网关
} catch (GatewayException $e) {
$this->logger->error('支付失败', [
'order_id' => $orderId,
'error' => $e->getMessage(),
'trace' => $e->getTraceAsString(),
]);
throw $e;
}
}
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 线上慢 10 倍 | Xdebug 没关 | 生产关 xdebug.mode |
| 日志里有密码 | 上下文带了敏感字段 | 日志只记 ID 与结果,不记 payload |
var_dump 在 FPM 下看不到输出 |
输出被缓冲 | 用 Xdebug 断点或写日志 |
面试考法:"生产能不能开 Xdebug""日志里能不能写用户密码"。答到:不能长期开,性能损失大;日志严禁敏感字段,只记 ID 与结果。
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 新建 Composer 包 | 手写 composer.json,配 PSR-4 | composer install 后类可自动加载 |
1 小时 |
| PSR-4 改错复现 | 故意把目录名改对,复现 Class not found | 修复后能讲清映射规则 | 1 小时 |
| 写一个 PHPUnit 测试 | 对一个纯函数写 3 组数据提供器 | ./vendor/bin/phpunit 通过 |
1.5 小时 |
| 接 PHPStan | 从 level 5 起步 | phpstan analyse 无错误 |
1 小时 |
| 接 CS-Fixer | 配 PSR-12 规则 | --dry-run 无差异 |
0.5 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 把阶段 2 工具包成 Composer 项目 | 加 composer.json、tests、phpstan | 一条 composer test 跑完 |
3 小时 |
| 为存量代码生成基线 | 用 --generate-baseline |
新代码 0 错误,基线文件可提交 | 1 小时 |
| 用 Mock 替换数据库 | 把 OrderService 测试的 Repository Mock 掉 | 测试不连数据库仍通过 | 2 小时 |
| 配 scripts 一键命令 | 把 test/phpstan/cs 串成 composer check |
一条命令跑完所有检查 | 0.5 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 可复用的 Composer 包 | 抽一个工具类(如字符串处理)成独立包 | 其他项目 composer require 可装 |
4 小时 |
| CI 配置 | 在 GitLab CI/GitHub Actions 里跑 test+phpstan+cs | PR 不通过门禁不能合并 | 3 小时 |
| 日志规范 | 写一份项目日志分级与字段规范 | 所有 error 日志带 trace_id | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
Class "App\X" not found |
命名空间与目录不对应,或没 dump-autoload | 核对 namespace 与 PSR-4 前缀 | 跑 composer dump-autoload |
Your requirements could not be resolved |
版本约束冲突 | composer why-not vendor/pkg |
调整约束,或看冲突包版本 |
composer install 在 CI 失败 |
私有仓库无凭据 | 看 CI 日志 | 配 auth.json 或 SSH key |
PHPUnit assertEquals(1,"1") 误通过 |
弱比较 | 检查断言 | 改 assertSame |
| PHPStan level 9 几百条错误 | 直接拉满 | 看错误分类 | 从 5 起步,用基线 |
assertSame(1, "1") 失败 |
类型不同 | 看实际类型 | 修调用处或改期望类型 |
php-cs-fixer 改了一堆文件 |
本地没跑 fix | 看 git diff | 提交前跑 php-cs-fixer fix |
| 线上接口慢 10 倍 | Xdebug 没关 | php -m 看是否加载 xdebug |
生产关 xdebug.mode |
八、出口条件
全部勾选后进入 04.5 阶段 4 框架主线 Laravel。
- [ ] 能独立写出 composer.json,配 PSR-4 与 scripts,干净环境
composer install可复现 - [ ] 能口述 PSR-4 命名空间到目录的映射规则,Class not found 时一次定位
- [ ] 能区分
composer install与update,知道线上用--no-dev --optimize-autoloader - [ ] 能写 PHPUnit 测试、数据提供器与 Mock,测试不依赖外部服务
- [ ] 能接入 PHPStan 从 level 5 起步,用基线治理存量
- [ ] 能接入 CS-Fixer 并在 CI 做风格门禁
- [ ] 排障表随机抽三个现象,5 分钟内给出排查路径
自测题:
^7.4与~7.4.5分别允许什么版本?- 要点:
^7.4是>=7.4 <8.0;~7.4.5是>=7.4.5 <7.5。
- 要点:
- PSR-4 规则下,
App\Service\UserService映射到哪个文件?- 要点:若 PSR-4 前缀
App\映射到src/,则文件是src/Service/UserService.php。
- 要点:若 PSR-4 前缀
- 生产环境为什么跑
composer install --no-dev?- 要点:不装 require-dev(PHPUnit、PHPStan),减少攻击面与体积;按 lock 保证版本一致。
assertEquals与assertSame区别?- 要点:assertEquals 松散比较值;assertSame 严格比较值与类型。
- PHPStan 为什么建议从 level 5 起步?
- 要点:level 9 对存量项目错误过多,团队易放弃;基线让新代码 0 新增,逐步提级。
- PSR-11 容器接口有哪两个方法?
- 要点:
get(string $id)与has(string $id)。
- 要点:
- 生产环境为什么不能长期开 Xdebug?
- 要点:性能开销大(可达数倍),且可能泄露调试信息;只在排查时临时开。