如何使用Doctrine Deprecations轻松管理PHP弃用消息
项目地址: https://gitcode.com/gh_mirrors/de/deprecations Doctrine Deprecations是一个轻量级PHP库，为trigger_error(E_USER_DEPRECATED)或PSR-3日志系统提供封装，帮助开发者轻松管理代码中的弃用消息。它默认无副作用，非常适合不知道运行环境错误处理机制的库使用，同时提供了避免依赖全局错误处理状态的选项，并能自动去重弃用消息以减少开销。
快速开始：安装与基础配置
一键安装步骤
使用Composer快速安装Doctrine Deprecations：
composer require doctrine/deprecations
该库要求PHP版本为^7.1或^8.0，兼容主流PHP环境。
三种启用模式
根据项目需求，Doctrine Deprecations提供三种主要启用方式：
1. 使用PSR-3日志记录弃用信息
如果你希望将弃用消息发送到PSR-3兼容的日志记录器：
\Doctrine\Deprecations\Deprecation::enableWithPsrLogger($logger);
2. 使用PHP原生错误触发
通过设置环境变量DOCTRINE_DEPRECATIONS为trigger，或直接调用：
\Doctrine\Deprecation::enableWithTriggerError();
这会将弃用消息作为E_USER_DEPRECATED错误触发。
3. 仅跟踪弃用信息
若只需跟踪弃用而不记录或触发错误，设置环境变量DOCTRINE_DEPRECATIONS为track，或调用：
\Doctrine\Deprecations\Deprecation::enableTrackingDeprecations();
从消费者角度使用：管理弃用消息
查看已触发的弃用信息
无论使用哪种模式，跟踪功能都会启用，你可以通过以下方式获取所有触发的弃用信息及其计数：
$deprecations = \Doctrine\Deprecations\Deprecation::getTriggeredDeprecations();
foreach ($deprecations as $identifier => $count) {
echo $identifier . " 被触发 " . $count . " 次\n";
}
选择性忽略弃用
忽略特定弃用
通过弃用标识符（通常是GitHub问题链接）忽略特定弃用：
\Doctrine\Deprecations\Deprecation::ignoreDeprecations("https://link/to/deprecations-description-identifier");
忽略整个包的弃用
如果你需要暂时忽略某个包的所有弃用：
\Doctrine\Deprecations\Deprecation::ignorePackage("doctrine/orm");
其他实用操作
禁用去重功能
在PHPUnit等工具中，可能需要收集同一弃用的多个实例，此时可以禁用去重：
\Doctrine\Deprecations\Deprecation::withoutDeduplication();
完全禁用弃用跟踪
需要时可以完全禁用弃用跟踪：
\Doctrine\Deprecations\Deprecation::disable();
从库/生产者角度使用：触发弃用消息
无条件触发弃用
当你希望无条件触发弃用时，使用trigger方法：
\Doctrine\Deprecations\Deprecation::trigger(
"doctrine/orm",
"https://link/to/deprecations-description",
"这是一条弃用消息"
);
如果需要格式化消息，可以传递额外参数：
\Doctrine\Deprecations\Deprecation::trigger(
"doctrine/orm",
"https://github.com/doctrine/orm/issue/1234",
"方法 %s 已弃用，请使用 %s 替代",
"oldMethod()",
"newMethod()"
);
仅在外部调用时触发弃用
当你希望仅在包外部代码调用时触发弃用，使用triggerIfCalledFromOutside方法：
\Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
"doctrine/orm",
"https://link/to/deprecations-description",
"此方法在外部调用时已弃用"
);
注意：库/生产者不应调用
Deprecation::enableWith系列方法，而应将如何处理弃用的决定权留给应用程序和框架。
在PHPUnit测试中使用
Doctrine Deprecations提供了VerifyDeprecations trait，帮助你在测试中对弃用进行断言。
基本用法
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
class MyTest extends TestCase
{
use VerifyDeprecations;
public function testSomethingDeprecation()
{
$this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
triggerTheCodeWithDeprecation();
}
public function testSomethingDeprecationFixed()
{
$this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
triggerTheCodeWithoutDeprecation();
}
}
配置PHPUnit显示弃用信息
在phpunit.xml.dist中配置，以显示测试套件执行期间触发的所有弃用：
<phpunit
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
colors="true"
bootstrap="vendor/autoload.php"
displayDetailsOnTestsThatTriggerDeprecations="true"
failOnDeprecation="true"
>
<php>
<!-- 确保使用原生PHP弃用 -->
<server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
</php>
<source ignoreSuppressionOfDeprecations="true">
<include>
<directory>src</directory>
</include>
</source>
</phpunit>
在测试引导文件中禁用去重
如果需要在测试中禁用弃用消息去重，可以在测试引导文件中添加：
// tests/bootstrap.php
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/vendor/autoload.php';
use Doctrine\Deprecations\Deprecation;
Deprecation::withoutDeduplication();
然后在phpunit.xml.dist中引用此引导文件：
<phpunit
...
bootstrap="tests/bootstrap.php"
...
>
...
</phpunit>
什么是弃用标识符？
弃用标识符只是指向任何资源的链接，通常是GitHub Issue或Pull Request，用于详细说明弃用及其替代方案。它还用于在请求期间对同一弃用的触发进行去重。
总结
Doctrine Deprecations为PHP开发者提供了一个灵活、高效的方式来管理代码中的弃用消息。无论是作为库开发者需要触发弃用，还是作为应用开发者需要处理弃用，它都提供了简单易用的API和丰富的功能。通过合理使用这个库，你可以确保代码平滑过渡，同时保持项目的可维护性。
要开始使用Doctrine Deprecations，只需克隆仓库并按照本文档的指南进行配置：
git clone https://gitcode.com/gh_mirrors/de/deprecations
探索src/Deprecation.php了解核心实现，或查看tests/VerifyDeprecationsTest.php获取更多测试用例。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
