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中必须注明仅为过渡方案，并附上最终修复计划的链接，让后续开发者明确方向。