PHP注释添加方法之废弃标记：平滑过渡方案【兼容处理】

在PHP项目升级这条路上，给废弃功能打上清晰的注释标记，真不是随手写几行说明就完事。说白了，你要搭的是一座可维护、可追溯、可自动识别的兼容性桥梁。关键就三点：工具选对、位置写准、退路留好。

用PHPDoc标准标注废弃信息

PHP官方推荐、主流IDE和静态分析工具（比如PHPStan、Psalm）都能识别的方式是什么？没错，就是@deprecated标签。它必须放在函数、方法或类的PHPDoc块里，紧贴声明上方。

• 一定要注明废弃起始版本，例如@deprecated since 8.5，这样团队一眼就能判断当前版本是否已经越过了那条线。
• 建议顺手补上替代方案，比如@see DateTimeImmutable::createFromFormat()，或者直接扔一个迁移指南链接@see https://example.com/migration-guide。
• 要是这功能打算在某版本彻底拆除，可以加个@removed 9.0（虽然不是标准标签，但大家看了都懂）。

配合Doctrine Deprecations实现运行时控制

光靠注释只能提示，拦不住老代码继续跑。这时候就需要Doctrine Deprecations库出手，提供真正的干预能力：

• 在废弃方法内部调用trigger_deprecation('vendor/name', '8.5', 'Method %s is deprecated', __METHOD__);，就可以统一收集、过滤、甚至抑制警告。
• 通过配置SYMFONY_DEPRECATIONS_HELPER=weak_vendors，让CI环境对第三方包的废弃提示睁一只眼闭一只眼，集中精力修自家的坑。
• 支持按消息关键词屏蔽重复警告，避免日志刷屏，比如ignore: "mysql_connect"，谁用谁知道。

动态属性弃用的特殊处理方式

PHP 8.3+对未声明属性的赋值会触发Deprecated: Creation of dynamic property警告。这跟传统函数级废弃不一样，得用结构化的方式应对：

• 首选重构：显式声明所有属性，即使初始值是null。这是最安全、最IDE友好的做法，一劳永逸。
• 如果确实需要动态行为，给类加上#[AllowDynamicProperties]属性。注意这个注解本身不会触发警告，而且子类继承也有效。
• 千万别想着用__set()魔术方法偷偷把问题掩盖——这样做会让类型检查失效，也绕过了废弃警告机制，后患无穷。

与类型系统升级联动标注

PHP 8.5/8.7里很多废弃都源于类型严格化（比如create_function被移除、联合类型校验升级）。这时候注释要跟着类型契约一起变：

• 废弃旧签名时，在新方法的PHPDoc里明确写@param int|string $input，同时在旧方法注释里说明“原接受mixed，现要求明确类型”。
• 父类方法新增返回类型导致子类重写触发废弃警告（比如PHP 8.1 PDO场景），就在子类方法注释里加@deprecated use return type PDOStatement|false to match parent。
• 搭配#[ReturnTypeWillChange]属性时，PHPDoc里必须注明这只是过渡方案，并附上最终修复计划的链接，让后来人知道该往哪走。