DOCSEARCHbyAlgolia
Submit Docs

Doctrine Deprecations

repository·1.1.x·Indexed 23 days ago

https://github.com/doctrine/deprecations

A lightweight, side-effect-free layer for managing deprecations in PHP libraries and applications. It allows library producers to trigger deprecations using unconditional or conditional methods and enables consumers to handle them via PSR-3 logging, PHP's trigger_error, or tracking. Includes tools for suppressing specific packages, retrieving triggered deprecations, and asserting deprecations within PHPUnit tests using the VerifyDeprecations trait.

Tokens
2.1K
Snippets
4
Records
10
Agent score
34%

What's inside doctrine-deprecations

  1. Configure deprecation handling for consumers

    1.1.x

    As a consumer (application developer), you can choose how deprecations are handled using the extit{\Doctrine\Deprecations\Deprecation} class or the DOCTRINE_DEPRECATIONS environment variable.

    Modes of Operation

    1. PSR-3 Logging (Recommended): Sends deprecations to a PSR-3 compatible logger.
      • Method: \Doctrine\Deprecations\Deprecation::enableWithPsrLogger($logger)
    2. Trigger Error: Sends deprecations via trigger_error($message, E_USER_DEPRECATED).
      • Method: \Doctrine\Deprecations\Deprecation::enableWithTriggerError()
      • Environment Variable: DOCTRINE_DEPRECATIONS=trigger
    3. Tracking Only: Enables tracking of deprecations without logging or triggering errors. This allows you to inspect them later.
      • Method: \Doctrine\Deprecations\Deprecation::enableTrackingDeprecations()
      • Environment Variable: DOCTRINE_DEPRECATIONS=track

    All modes enable tracking, allowing you to retrieve the list of triggered deprecations.

  2. Trigger deprecations as a library producer

    1.1.x

    If you are developing a library, use these methods to signal deprecations to your users.

    Important: A library should never call enableWith... methods; leave the handling decision to the application/framework using your library.

    Unconditional Triggering

    Use trigger() to always signal a deprecation. The message supports sprintf style formatting if extra arguments are provided.

    Conditional Triggering

    Use triggerIfCalledFromOutside() to trigger a deprecation only when the call originates from outside your package. This prevents your own internal tests or logic from triggering the deprecation.

    Note: Each deprecation (based on its identifier) is only triggered once per request to reduce overhead.

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

// Trigger only if called from outside the package
\Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
    "doctrine/orm",
    "https://link/to/deprecations-description",
    "message"
);

  3. Configure PHPUnit to display and fail on deprecations

    1.1.x

    To integrate deprecation reporting into your PHPUnit test suite, update your phpunit.xml. You can use displayDetailsOnTestsThatTriggerDeprecations to show the deprecations and failOnDeprecation to fail the suite if any are found.

    To ensure native PHP deprecations are used, set the DOCTRINE_DEPRECATIONS environment variable to trigger within the <php> section. Also, ensure <source ignoreSuppressionOfDeprecations="true"> is configured to prevent the @ operator from hiding deprecations.

    <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>
        <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
    </php>

    <source ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>

  4. Enable deprecation logging mechanisms

    1.1.x

    The Doctrine\Deprecations\Deprecation class allows you to configure how deprecations are handled. By default, no deprecations are logged or tracked. You can enable one or more of the following mechanisms:

    • Tracking: Collects deprecations in memory so you can inspect them later using getTriggeredDeprecations().
    • Trigger Error: Uses PHP's @trigger_error with E_USER_DEPRECATED to emit standard PHP deprecation notices.
    • PSR-3 Logger: Sends deprecation messages to a provided Psr\Log\LoggerInterface implementation.

    You can also configure these via the DOCTRINE_DEPRECATIONS environment variable (or $_SERVER key) with values track or trigger.

  6. Assert deprecations in PHPUnit tests

    1.1.x

    Use the VerifyDeprecations trait in your test classes to assert that specific deprecations are (or are not) triggered during execution.

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

  7. Retrieve and inspect triggered deprecations

    1.1.x

    When deprecation tracking is enabled, you can retrieve an associative array where the keys are deprecation identifiers (usually URLs) and the values are the number of times each was triggered.

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

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

  8. Configure deprecation filtering and behavior

    1.1.x

    You can fine-tune how deprecations are handled using the following static methods on Doctrine\Deprecations\Deprecation:

    • ignorePackage(string $packageName): Prevents deprecations from a specific Composer package from being processed.
    • ignoreDeprecations(string ...$links): Prevents specific deprecations (identified by their $link URL) from being processed.
    • withoutDeduplication(): Disables the automatic de-duplication of the same deprecation link within a single request.
    • disable(): Resets the configuration, stops all logging/tracking, and clears ignored lists.

  9. Retrieve triggered deprecations

    1.1.x

    When using enableTrackingDeprecations(), you can inspect which deprecations were triggered during the request.

    • getTriggeredDeprecations(): Returns an associative array where keys are the deprecation $link URLs and values are the number of times that specific deprecation was triggered.
    • getUniqueTriggeredDeprecationsCount(): Returns the total count of all triggered deprecations.

  10. Trigger a deprecation in a library

    1.1.x

    If you are developing a package that uses Doctrine Deprecations, use the trigger() method to signal a deprecation.

    Required arguments:

    • $package: The exact Composer package name.
    • $link: A URL (e.g., to a GitHub issue or Wiki) providing details about the deprecation. This link is used for de-duplication so the same deprecation isn't reported multiple times in a single request.
    • $message: The deprecation message (supports sprintf style formatting).
    • $args: Optional arguments to be interpolated into the $message.

    To avoid reporting deprecations when the library is being used by its own internal tests, use triggerIfCalledFromOutside() instead. This method checks the call stack to ensure the caller is not within the $package's own directory structure.