适配器模式在PHP中是解决旧代码（如.phar封装的LegacyLogger）与新接口（如PSR-3）不兼容的唯一可行方案，通过组合旧实例、手动转换参数实现即刻上线，不修改旧类、不妥协新标准。
PHP项目需要适配器模式，不是因为“设计模式很高级”，而是因为现实里你根本改不了旧代码——比如一个被封装在.phar里、没有源码、但还在生产环境跑着的LegacyLogger类，它只接受log($level, $msg, $context)，而新系统统一要求PSR-3 LoggerInterface::log($level, $message, array $context)。这时候，硬改调用方或重写旧类都不现实，适配器是唯一能当天上线的解法。
旧类不能动，新接口又必须满足：适配器是唯一出口
你遇到的不是“要不要用设计模式”的问题，是“不加一层中间转发就编译不过”的硬约束。常见触发场景包括：
- 第三方 SDK 升级后方法签名变了（比如
sendEmail($to, $subject, $body)→send(Message $msg)） - 框架升级强制依赖新标准（如从自定义日志类切到
LoggerInterface） - 并购项目里对方系统用的是完全不同的参数顺序/类型/返回值结构
关键点在于：适配器不解决“谁对谁错”，只解决“怎么让它们现在就能一起跑”。它不修改旧类，也不要求新系统妥协，只做最小转换。
适配器类必须显式持有被适配对象，不能靠“实现同一接口”蒙混过关
新手最常踩的坑是写完class LegacyLoggerAdapter implements LoggerInterface就以为完事了，结果运行时报Call to undefined method LegacyLogger::log()——因为旧类根本没log()方法，只有write()或output()。
立即学习“PHP免费学习笔记（深入）”；
正确做法是：
- 构造函数必须接收旧对象实例：
public function __construct(LegacyLogger $legacy) - 在
log()里手动调用$this->legacy->write(...)，并完成参数重组（比如把$context数组拆成单独参数） - 不要试图在适配器里补全旧类缺失的功能（如自动加时间戳），那已超出适配边界，属于业务逻辑迁移
示例片段：
class LegacyLoggerAdapter implements LoggerInterface
{
private $legacy;
public function __construct(LegacyLogger $legacy)
{
$this->legacy = $legacy;
}
public function log($level, $message, array $context = [])
{
// 旧类不支持数组 context，只接受字符串
$flatContext = json_encode($context);
$this->legacy->write($level, $message . ' | ' . $flatContext);
}
}
自动加载和类型安全必须手工对齐，否则注入就失败
即使代码逻辑写对了，如果 Composer 的autoload没配好，或者类型声明不严格，DI 容器会直接拒绝实例化适配器。典型问题有：
-
LegacyLogger类不在 PSR-4 命名空间下，require_once路径写错导致Class not found - 适配器构造函数声明
LegacyLogger $legacy，但传入的是LegacyLoggerV2，PHP 8+ 会报TypeError - 旧类是
final，但你在适配器里试图extends它（错误思路！适配器应compose而非inherit）
检查清单：
- 确认
composer.json中autoload.files包含旧类文件路径 - 用
php -l验证语法，再用phpstan扫一遍类型兼容性 - 在测试中用
assertInstanceOf(LoggerInterface::class, $adapter)确保接口契约成立
别把适配器写成胶水层：薄、快、无副作用
适配器一旦开始处理业务逻辑（比如在processPayment()里加风控校验）、或引入新依赖（如在日志适配器里偷偷连 Redis）、或做异步调度，它就不再是适配器，而是新模块——维护成本立刻翻倍，且违背“解耦”初衷。
判断是否过界，就看这一行代码：
- ✅ 只出现
$this->legacy->xxx(...)、return $result、throw new AdapterException(...) - ❌ 出现
new SomeService()、file_get_contents()、if ($level === 'error') { sendAlert() }
真正难的从来不是写适配器，而是守住那条线：它只是翻译官，不是决策者。
