README

在 trigger_error(E_USER_DEPRECATED) 或 PSR-3 日志之上的一层小层（默认无副作用）。

• 默认无副作用，非常适合不知道它们运行在何种错误处理器下的库
• 使用 PSR-3 日志选项以避免依赖错误处理器的全局状态
• 去重弃用消息以避免过度触发并减少开销

我们建议使用 PSR 日志收集弃用，而不是依赖全局错误处理器。

从消费者角度的用法

启用 Doctrine 弃用以将其发送到 PSR3 日志

\Doctrine\Deprecations\Deprecation::enableWithPsrLogger($logger);

通过设置环境变量 DOCTRINE_DEPRECATIONS 为 trigger 来启用 Doctrine 弃用以将其作为 @trigger_error($message, E_USER_DEPRECATED) 消息发送。或者，调用

\Doctrine\Deprecations\Deprecation::enableWithTriggerError();

如果您只想启用弃用跟踪，而不进行日志记录或调用 trigger_error，则将环境变量 DOCTRINE_DEPRECATIONS 设置为 track。或者，调用

\Doctrine\Deprecations\Deprecation::enableTrackingDeprecations();

所有三种模式都启用了跟踪，并提供对所有已触发的弃用及其各自计数的访问

$deprecations = \Doctrine\Deprecations\Deprecation::getTriggeredDeprecations();

foreach ($deprecations as $identifier => $count) {
    echo $identifier . " was triggered " . $count . " times\n";
}

抑制特定弃用

禁用关于特定弃用的触发

\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",
    "message"
);

如果提供变量参数，则它们将用于消息的 sprintf。

\Doctrine\Deprecations\Deprecation::trigger(
    "doctrine/orm",
    "https://github.com/doctrine/orm/issue/1234",
    "message %s %d",
    "foo",
    1234
);

当您只想在从当前包之外的功能调用时触发弃用，而在包本身是原因时不触发时，则使用

\Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
    "doctrine/orm",
    "https://link/to/deprecations-description",
    "message"
);

基于问题链接，每个弃用消息在每个请求中只触发一次。

弃用消息中包含有限的堆栈跟踪以查找违规位置。

注意：生产者/库不应调用 Deprecation::enableWith 方法，并将处理弃用的决定留给应用程序和框架。

在 PHPUnit 测试中的用法

有一个 VerifyDeprecations 特性，您可以使用它来对测试中发生的弃用进行断言。

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();
    }
}

弃用标识符是什么？

弃用标识符只是任何资源的链接，通常是解释弃用及其潜在替代方案的 Github Issue 或 Pull Request。