PHPackages                             doctrine/deprecations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. doctrine/deprecations

ActiveLibrary[Utility & Helpers](/categories/utility)

doctrine/deprecations
=====================

A small layer on top of trigger\_error(E\_USER\_DEPRECATED) or PSR-3 logging with options to disable all deprecations or selectively for packages.

1.1.6(3mo ago)1.8k473.4M—4.3%20[6 issues](https://github.com/doctrine/deprecations/issues)[1 PRs](https://github.com/doctrine/deprecations/pulls)20MITPHPPHP ^7.1 || ^8.0CI passing

Since Dec 30Pushed 1mo ago9 watchersCompare

[ Source](https://github.com/doctrine/deprecations)[ Packagist](https://packagist.org/packages/doctrine/deprecations)[ Docs](https://www.doctrine-project.org/)[ RSS](/packages/doctrine-deprecations/feed)WikiDiscussions 1.1.x Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (26)Used By (20)

Doctrine Deprecations
=====================

[](#doctrine-deprecations)

A small (side-effect free by default) layer on top of `trigger_error(E_USER_DEPRECATED)` or PSR-3 logging.

- no side-effects by default, making it a perfect fit for libraries that don't know how the error handler works they operate under
- options to avoid having to rely on error handlers global state by using PSR-3 logging
- deduplicate deprecation messages to avoid excessive triggering and reduce overhead

We recommend to collect Deprecations using a PSR logger instead of relying on the global error handler.

Usage from consumer perspective:
--------------------------------

[](#usage-from-consumer-perspective)

Enable Doctrine deprecations to be sent to a PSR3 logger:

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

Enable Doctrine deprecations to be sent as `@trigger_error($message, E_USER_DEPRECATED)`messages by setting the `DOCTRINE_DEPRECATIONS` environment variable to `trigger`. Alternatively, call:

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

If you only want to enable deprecation tracking, without logging or calling `trigger_error`then set the `DOCTRINE_DEPRECATIONS` environment variable to `track`. Alternatively, call:

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

Tracking is enabled with all three modes and provides access to all triggered deprecations and their individual count:

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

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

### Suppressing Specific Deprecations

[](#suppressing-specific-deprecations)

Disable triggering about specific deprecations:

```
\Doctrine\Deprecations\Deprecation::ignoreDeprecations("https://link/to/deprecations-description-identifier");
```

Disable all deprecations from a package

```
\Doctrine\Deprecations\Deprecation::ignorePackage("doctrine/orm");
```

### Other Operations

[](#other-operations)

When used within PHPUnit or other tools that could collect multiple instances of the same deprecations the deduplication can be disabled:

```
\Doctrine\Deprecations\Deprecation::withoutDeduplication();
```

Disable deprecation tracking again:

```
\Doctrine\Deprecations\Deprecation::disable();
```

Usage from a library/producer perspective:
------------------------------------------

[](#usage-from-a-libraryproducer-perspective)

When you want to unconditionally trigger a deprecation even when called from the library itself then the `trigger` method is the way to go:

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

If variable arguments are provided at the end, they are used with `sprintf` on the message.

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

When you want to trigger a deprecation only when it is called by a function outside of the current package, but not trigger when the package itself is the cause, then use:

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

Based on the issue link each deprecation message is only triggered once per request.

A limited stacktrace is included in the deprecation message to find the offending location.

Note: A producer/library should never call `Deprecation::enableWith` methods and leave the decision how to handle deprecations to application and frameworks.

Usage in PHPUnit tests
----------------------

[](#usage-in-phpunit-tests)

There is a `VerifyDeprecations` trait that you can use to make assertions on the occurrence of deprecations within a test.

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

Displaying deprecations after running a PHPUnit test suite
----------------------------------------------------------

[](#displaying-deprecations-after-running-a-phpunit-test-suite)

It is possible to integrate this library with PHPUnit to display all deprecations triggered during the test suite execution.

```

            src

```

Note that you can still trigger Deprecations in your code, provided you use the `#[IgnoreDeprecations]` to ignore them for tests that call it.

At the moment, it is not possible to disable deduplication with an environment variable, but you can use a bootstrap file to achieve that:

```
// tests/bootstrap.php