Doctrine Deprecations

https://github.com/doctrine/deprecations
Admin
Doctrine Deprecations is a small layer on top of trigger_error(E_USER_DEPRECATED) or PSR-3 logging...
Tokens:26,416
Snippets:167
Trust Score:9.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Pristine counter setup example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Example `setUp()` method that disables and re-enables tracking to reset counters, ensuring a clean state for each test. Useful when a baseline-relative design is not sufficient.

```php
use Doctrine\Deprecations\Deprecation;
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    use VerifyDeprecations;

    protected function setUp(): void
    {
        Deprecation::disable();
        Deprecation::enableTrackingDeprecations();
    }
}
```

--------------------------------

### Trigger a deprecation with sprintf arguments

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

When variable arguments are provided at the end, they are used with sprintf on the message. This example shows how to pass format arguments.

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

--------------------------------

### Get Triggered Deprecations

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Retrieves all triggered deprecations and their counts. Tracking is enabled in all three modes.

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

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

--------------------------------

### Ignore Package Deprecations

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Disables all deprecations from a specific package.

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

--------------------------------

### Enable Tracking Only

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Enables deprecation tracking without logging or trigger_error. Equivalent to setting DOCTRINE_DEPRECATIONS to 'track'.

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

--------------------------------

### Disable Tracking

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Disables deprecation tracking again.

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

--------------------------------

### Complete test class using VerifyDeprecations trait

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Realistic example showing a PHPUnit test class that uses the VerifyDeprecations trait with both expectDeprecationWithIdentifier() and expectNoDeprecationWithIdentifier(). Demonstrates testing legacy and new endpoints.

```php
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use PHPUnit\Framework\TestCase;

final class MigrationTest extends TestCase
{
    use VerifyDeprecations;

    private const OLD_LINK = 'https://github.com/doctrine/orm/issues/77';

    public function testLegacyEndpointStillWarns(): void
    {
        $this->expectDeprecationWithIdentifier(self::OLD_LINK);

        (new LegacyEndpointController())->handle(); // triggers via Deprecation::trigger()
    }

    public function testNewEndpointIsClean(): void
    {
        $this->expectNoDeprecationWithIdentifier(self::OLD_LINK);

        (new NewEndpointController())->handle();
    }
}
```

--------------------------------

### Enable with PSR-3 Logger

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Sends deprecations to a PSR-3 logger instead of relying on the global error handler.

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

--------------------------------

### Example: enableWithPsrLogger with Monolog and triggered deprecations

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Recommended collection strategy from the README. Creates a Monolog logger, enables PSR-3 logging, runs the application, and prints triggered deprecation counts. The output shows a sample log record with context fields.

```php
use Doctrine\Deprecations\Deprecation;

$logger = new Monolog\Logger('deprecations', [new Monolog\Handler\StreamHandler('php://stderr')]);
Deprecation::enableWithPsrLogger($logger);

try {
    runApplication(); // any Doctrine deprecations become structured log records
} finally {
    foreach (Deprecation::getTriggeredDeprecations() as $identifier => $count) {
        echo $identifier . ' was triggered ' . $count . " times\n";
    }
}
// log record: { message: 'old thing', context: { file: '...', line: 42, package: 'doctrine/orm', link: 'https://...' }, level: notice }
```

--------------------------------

### Basic usage example: testExpectDeprecationWithIdentifier

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Shows a test class using the VerifyDeprecations trait and calling expectDeprecationWithIdentifier() to assert that a deprecation with the given identifier is triggered. The test passes only if the deprecation is triggered at least once.

```php
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use PHPUnit\Framework\TestCase;

class LegacyConsumerTest extends TestCase
{
    use VerifyDeprecations;

    public function testOldApiEmitsDeprecation(): void
    {
        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/1234');

        triggerTheCodeWithDeprecation(); // must emit the deprecation with that identifier
    }
}
```

--------------------------------

### VerifyDeprecations::expectDeprecationWithIdentifier

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

PHPUnit trait method to assert that a deprecation with a specific identifier occurs during a test.

```APIDOC
## VerifyDeprecations::expectDeprecationWithIdentifier

### Description
PHPUnit trait method to assert that a deprecation with a specific identifier occurs during a test.

### Method
Instance method (trait)

### Signature
```php
$this->expectDeprecationWithIdentifier(string $identifier): void
```

### Parameters
- **$identifier** (string) - Required - The deprecation identifier (e.g., the issue link).

### Example
```php
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;

class MyTest extends TestCase
{
    use VerifyDeprecations;

    public function testSomethingDeprecation()
    {
        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');

        triggerTheCodeWithDeprecation();
    }
}
```
```

--------------------------------

### VerifyDeprecations::expectNoDeprecationWithIdentifier

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

PHPUnit trait method to assert that no deprecation with a specific identifier occurs during a test.

```APIDOC
## VerifyDeprecations::expectNoDeprecationWithIdentifier

### Description
PHPUnit trait method to assert that no deprecation with a specific identifier occurs during a test.

### Method
Instance method (trait)

### Signature
```php
$this->expectNoDeprecationWithIdentifier(string $identifier): void
```

### Parameters
- **$identifier** (string) - Required - The deprecation identifier (e.g., the issue link).

### Example
```php
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;

class MyTest extends TestCase
{
    use VerifyDeprecations;

    public function testSomethingDeprecationFixed()
    {
        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');

        triggerTheCodeWithoutDeprecation();
    }
}
```
```

--------------------------------

### Regression guard example using expectNoDeprecationWithIdentifier()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Test class that uses the `VerifyDeprecations` trait and calls `expectNoDeprecationWithIdentifier()` to ensure a specific deprecation is not triggered. Fails with an `AssertionFailedError` if the deprecation occurs.

```php
class LegacyConsumerTest extends TestCase
{
    use VerifyDeprecations;

    public function testNewApiIsSilent(): void
    {
        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/1234');

        triggerTheCodeWithoutDeprecation(); // must not emit that deprecation
    }
}
```

--------------------------------

### Use VerifyDeprecations trait in PHPUnit tests

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Use the VerifyDeprecations trait to make assertions on the occurrence of deprecations within a test. The example shows expectDeprecationWithIdentifier and expectNoDeprecationWithIdentifier methods.

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

--------------------------------

### enableDeprecationTracking(): void

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Runs automatically before each test via #[Before] (and @before for older PHPUnit) to activate deprecation tracking counters. It does not reset counters; callers who need clean state should call Deprecation::disable() in their own setUp().

```APIDOC
## enableDeprecationTracking(): void

### Description
Runs automatically before each test via #[Before] (and @before for older PHPUnit) to activate deprecation tracking counters. It does not reset counters; callers who need clean state should call Deprecation::disable() in their own setUp().

### Method
PHP method

### Endpoint
`enableDeprecationTracking(): void`

### Parameters
None

### Return
`void`

### Example
```php
use Doctrine\Deprecations\Deprecation;
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    use VerifyDeprecations;

    protected function setUp(): void
    {
        Deprecation::disable();
        Deprecation::enableTrackingDeprecations();
    }
}
```
```

--------------------------------

### Bootstrap file to disable deprecation deduplication

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

A bootstrap file that disables deduplication of deprecations. This is needed because there is no environment variable to disable deduplication. Reference this file in the PHPUnit configuration's bootstrap attribute.

```PHP
// tests/bootstrap.php
<?php

declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

use Doctrine\Deprecations\Deprecation;

Deprecation::withoutDeduplication();
```

--------------------------------

### Ignore Specific Deprecation

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Disables triggering for a specific deprecation identified by its URL.

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

--------------------------------

### PHPUnit configuration referencing the custom bootstrap file

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

PHPUnit configuration that uses the custom bootstrap file to disable deduplication. The ellipsis (...) indicates omitted parts of the configuration; the key change is setting bootstrap to 'tests/bootstrap.php'.

```XML
<phpunit …
        bootstrap="tests/bootstrap.php"
        …
    >
    …
</phpunit>
```

--------------------------------

### Trigger a deprecation unconditionally with Deprecation::trigger

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Use this when you want to trigger a deprecation regardless of the calling context. The first argument is the package name, the second is a link to the deprecation description, and the third is the message.

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

--------------------------------

### Deprecation::trigger

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Unconditionally triggers a deprecation with a package identifier, a link to deprecation details, and a message. Supports sprintf-style formatting with variable arguments.

```APIDOC
## Deprecation::trigger

### Description
Unconditionally triggers a deprecation with a package identifier, a link to deprecation details, and a message. Supports sprintf-style formatting with variable arguments.

### Method
Static method call

### Signature
```php
\Doctrine\Deprecations\Deprecation::trigger(
    string $package,
    string $link,
    string $message,
    mixed ...$args
): void
```

### Parameters
- **$package** (string) - Required - The package identifier (e.g., "doctrine/orm").
- **$link** (string) - Required - URL to the deprecation description.
- **$message** (string) - Required - The deprecation message, optionally with sprintf placeholders.
- **...$args** (mixed) - Optional - Variable arguments used with sprintf on the message.

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

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

### Notes
- Each deprecation message is triggered only once per request based on the issue link.
- A limited stacktrace is included in the deprecation message.
```

--------------------------------

### Enable with Trigger Error

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Sends deprecations as E_USER_DEPRECATED messages via trigger_error. Equivalent to setting DOCTRINE_DEPRECATIONS to 'trigger'.

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

--------------------------------

### Example: withoutDeduplication with trigger and count

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows how to disable deduplication and trigger the same deprecation three times. The output of getUniqueTriggeredDeprecationsCount() is 3 because deduplication is off.

```php
Deprecation::enableWithTriggerError();
Deprecation::withoutDeduplication();

for ($i = 0; $i < 3; $i++) {
    Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/5', 'boom');
}
echo Deprecation::getUniqueTriggeredDeprecationsCount(); // 3
```

--------------------------------

### enableTrackingDeprecations() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows how to enable tracking, trigger a deprecation, and later inspect the report. The report maps the deprecation identifier URL to the occurrence count, e.g., ['https://github.com/doctrine/orm/issues/1' => 1].

```php
use Doctrine\Deprecations\Deprecation;

Deprecation::enableTrackingDeprecations();

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/1', 'old thing');

// inspect later, e.g. at shutdown
$report = Deprecation::getTriggeredDeprecations();
// ['https://github.com/doctrine/orm/issues/1' => 1]
```

--------------------------------

### ignorePackage() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows how to suppress deprecation triggers for a package. After calling ignorePackage(), trigger() does not emit E_USER_DEPRECATED, but the deprecation is still counted in getUniqueTriggeredDeprecationsCount().

```php
Deprecation::enableWithTriggerError();
Deprecation::ignorePackage('doctrine/orm');

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/8', 'old api');
// no E_USER_DEPRECATED emitted, but:
echo Deprecation::getUniqueTriggeredDeprecationsCount(); // 1 (still counted)
```

--------------------------------

### enableWithTriggerError() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows how to enable error triggering, set a custom error handler to collect E_USER_DEPRECATED errors, trigger a deprecation, and restore the previous error handler.

```php
Deprecation::enableWithTriggerError();

set_error_handler(function (int $errno, string $errstr): bool {
    if ($errno === E_USER_DEPRECATED) {
        // collect $errstr
        return true;
    }
    return false;
});

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/9', 'deprecated!');
restore_error_handler();
```

--------------------------------

### PHPUnit configuration to display and fail on deprecations

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Configure PHPUnit to display deprecations and fail the test suite when they occur. Sets the DOCTRINE_DEPRECATIONS server variable to 'trigger' to use native PHP deprecations, and ignores suppression of deprecations via the @ operator. Use the #[IgnoreDeprecations] attribute to ignore deprecations in specific tests.

```XML
<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"
    >
    <!-- one attribute to display the deprecations, the other to fail the test suite -->

    <php>
        <!-- ensures native PHP deprecations are used -->
        <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
    </php>

    <!-- ensures the @ operator in @trigger_error is ignored -->
    <source ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>src</directory>
        </include>
    </source>
</phpunit>
```

--------------------------------

### Disable Deduplication

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Disables deduplication of deprecation messages, useful in PHPUnit or tools that collect multiple instances.

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

--------------------------------

### Tracking-only mode from an application

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Application-side example enabling tracking-only mode. After calling oldMethod() externally, the deprecation is emitted and the unique triggered deprecations count becomes 1.

```php
Deprecation::enableTrackingDeprecations();

$legacy = new LegacyFoo();
$legacy->oldMethod(); // external call: emitted

$count = Deprecation::getUniqueTriggeredDeprecationsCount(); // 1
```

--------------------------------

### Deprecation::triggerIfCalledFromOutside

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Triggers a deprecation only when called from outside the current package, not when the package itself is the cause. Useful for libraries to avoid triggering deprecations internally.

```APIDOC
## Deprecation::triggerIfCalledFromOutside

### Description
Triggers a deprecation only when called from outside the current package, not when the package itself is the cause. Useful for libraries to avoid triggering deprecations internally.

### Method
Static method call

### Signature
```php
\Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
    string $package,
    string $link,
    string $message,
    mixed ...$args
): void
```

### Parameters
- **$package** (string) - Required - The package identifier (e.g., "doctrine/orm").
- **$link** (string) - Required - URL to the deprecation description.
- **$message** (string) - Required - The deprecation message, optionally with sprintf placeholders.
- **...$args** (mixed) - Optional - Variable arguments used with sprintf on the message.

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

### Notes
- Each deprecation message is triggered only once per request based on the issue link.
- A limited stacktrace is included in the deprecation message.
```

--------------------------------

### Trigger a deprecation only when called from outside the package

Source: https://github.com/doctrine/deprecations/blob/1.1.x/README.md

Use triggerIfCalledFromOutside to trigger a deprecation only when it is called by a function outside of the current package, but not when the package itself is the cause.

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

--------------------------------

### getUniqueTriggeredDeprecationsCount() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enables tracking, triggers three deprecations (one repeated), and prints the total count. The output is 3, demonstrating that repeated occurrences are counted.

```php
Deprecation::enableTrackingDeprecations();

Deprecation::trigger('a/pkg', 'https://example.com/1', 'm');
Deprecation::trigger('a/pkg', 'https://example.com/1', 'm'); // dedup: backend skipped, counter still incremented
Deprecation::trigger('a/pkg', 'https://example.com/2', 'm');

echo Deprecation::getUniqueTriggeredDeprecationsCount(); // 3
```

--------------------------------

### Library-side usage of triggerIfCalledFromOutside()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Producer perspective example showing how to trigger a deprecation from a library method. The internal call to oldMethod() from newMethod() does not emit a deprecation because it is inside the package.

```php
use Doctrine\Deprecations\Deprecation;

final class LegacyFoo
{
    public function oldMethod(): void
    {
        Deprecation::triggerIfCalledFromOutside(
            'doctrine/legacy-pkg',
            'https://github.com/doctrine/legacy-pkg/issues/42',
            'LegacyFoo::oldMethod() is deprecated, use LegacyFoo::newMethod() instead.'
        );
    }

    public function newMethod(): void
    {
        $this->oldMethod(); // internal call: no deprecation emitted
    }
}
```

--------------------------------

### disable() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Demonstrates calling disable() to make subsequent trigger() calls no-ops. After disable(), the triggered deprecation count for the identifier is reset to 0, as shown by var_export.

```php
Deprecation::enableWithTriggerError();
Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/2', 'gone');

Deprecation::disable();

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/2', 'gone'); // no-op
var_export(Deprecation::getTriggeredDeprecations()); // ['https://github.com/doctrine/orm/issues/2' => 0]
```

--------------------------------

### Doctrine\Deprecations\Deprecation::getUniqueTriggeredDeprecationsCount

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/index.md

Returns the count of unique triggered deprecations. This is a consumer-facing method to get the number of distinct deprecations.

```APIDOC
## [METHOD] getUniqueTriggeredDeprecationsCount

### Description
Returns the count of unique triggered deprecations. This is a consumer-facing method to get the number of distinct deprecations.

### Method
Static method

### Endpoint
`Doctrine\Deprecations\Deprecation::getUniqueTriggeredDeprecationsCount`

### Parameters
None.

### Response
Returns an integer count of unique deprecations.
```

--------------------------------

### ignoreDeprecations() usage example

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enables trigger error mode, ignores two deprecation identifiers, triggers a deprecation for one of them, and verifies that the triggered deprecations list is empty. The output is an empty array.

```php
Deprecation::enableWithTriggerError();
Deprecation::ignoreDeprecations(
    'https://github.com/doctrine/orm/issues/1',
    'https://github.com/doctrine/orm/issues/2',
);

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/1', 'supressed');
var_export(Deprecation::getTriggeredDeprecations()); // []
```

--------------------------------

### Deprecation::triggerIfCalledFromOutside()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Triggers a deprecation for the given package and identifier only when called from outside the package. It uses a caller-origin gate to skip deprecations from internal calls, while allowing calls from tests in root-package installs.

```APIDOC
## `Deprecation::triggerIfCalledFromOutside()`

### Description
Triggers a deprecation for the given package and identifier only when called from outside the package. It uses a caller-origin gate to skip deprecations from internal calls, while allowing calls from tests in root-package installs.

### Method
`triggerIfCalledFromOutside` (static method)

### Signature
```php
public static function triggerIfCalledFromOutside(string $package, string $link, string $message, ...$args): void
```

### Parameters
- `$package` (string) - Required - Exact Composer package name of the library emitting the deprecation (must match the `vendor/{package}` install path assumption)
- `$link` (string) - Required - Deprecation identifier URL; deduplication and tracking key
- `$message` (string) - Required - `sprintf`-formattable message
- `...$args` (float|int|string) - Optional - Variadic `sprintf` arguments

### Return Value
`void`

### Behavior
Same as `trigger()` after an extra caller-origin gate. The gate checks the backtrace frames: if frame 1 is in a `tests/` directory, the deprecation passes; otherwise, it only passes if frame 0 is inside `/vendor/{package}/` and frame 1 is not also inside that path.

### Example - Library-side usage (producer perspective)
```php
use Doctrine\Deprecations\Deprecation;

final class LegacyFoo
{
    public function oldMethod(): void
    {
        Deprecation::triggerIfCalledFromOutside(
            'doctrine/legacy-pkg',
            'https://github.com/doctrine/legacy-pkg/issues/42',
            'LegacyFoo::oldMethod() is deprecated, use LegacyFoo::newMethod() instead.'
        );
    }

    public function newMethod(): void
    {
        $this->oldMethod(); // internal call: no deprecation emitted
    }
}
```

### Example - Tracking-only mode from an application
```php
Deprecation::enableTrackingDeprecations();

$legacy = new LegacyFoo();
$legacy->oldMethod(); // external call: emitted

$count = Deprecation::getUniqueTriggeredDeprecationsCount(); // 1
```
```

--------------------------------

### enableDeprecationTracking() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Hook method that runs automatically before each test via `#[Before]` and `@before` to enable deprecation tracking. It does not reset counters.

```php
/** @before */
#[Before]
public function enableDeprecationTracking(): void
```

--------------------------------

### Enabling deprecation tracking

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Calls `Deprecation::enableTrackingDeprecations()` to activate the counters so that occurrences during the test body are recorded for the `@after` assertions.

```php
Deprecation::enableTrackingDeprecations();
```

--------------------------------

### Recording baseline for expectNoDeprecationWithIdentifier()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Stores the current triggered deprecation count for the identifier into the `$doctrineNoDeprecationsExpectations` property. Verification passes only if the counter equals this baseline after the test body.

```php
$this->doctrineNoDeprecationsExpectations[$identifier] = Deprecation::getTriggeredDeprecations()[$identifier] ?? 0;
```

--------------------------------

### ignorePackage() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Declares the public static method that adds a Composer package name to the ignored packages list. It requires a string parameter and returns void.

```php
public static function ignorePackage(string $packageName): void
```

--------------------------------

### Method signature: expectDeprecationWithIdentifier()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Declares the public method signature for expecting a deprecation with a specific identifier. The identifier is the $link URL passed to Deprecation::trigger().

```php
public function expectDeprecationWithIdentifier(string $identifier): void
```

--------------------------------

### Deprecation context and logger notice call

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows the context array built for each deprecation and the subsequent call to $logger->notice(). The context includes file, line, package, and link from the backtrace.

```php
$context = [
    'file'    => $backtrace[0]['file'] ?? null,
    'line'    => $backtrace[0]['line'] ?? null,
    'package' => $package,
    'link'    => $link,
];

$logger->notice($message, $context);
```

--------------------------------

### Basic trigger with sprintf args

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enables trigger_error mode and triggers a deprecation with sprintf placeholders. Emits a suppressed E_USER_DEPRECATED error; the message gains a location/link/package suffix before dispatch.

```php
use Doctrine\Deprecations\Deprecation;

Deprecation::enableWithTriggerError();

Deprecation::trigger(
    'doctrine/orm',
    'https://github.com/doctrine/orm/issues/1234',
    'Foo::oldMethod() is deprecated, use %s instead.',
    'Foo::newMethod()'
);
// Emits a suppressed E_USER_DEPRECATED error; the message gains a
// location/link/package suffix before dispatch.
```

--------------------------------

### verifyDeprecationsAreTriggered()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Runs automatically after each test via the #[After] annotation. It asserts that all expected deprecations were triggered and that no unexpected deprecations were triggered, based on the expectations set by the trait's methods.

```APIDOC
## verifyDeprecationsAreTriggered()

### Description
Runs automatically after each test via the `#[After]` (and `@after`) annotation. It asserts that all expected deprecations were triggered and that no unexpected deprecations were triggered, based on the expectations set by the trait's methods.

### Method
`verifyDeprecationsAreTriggered()`

### Parameters
None.

### Return
`void`. May abort the test by failing an assertion.

### Behavior
- For every identifier in `$doctrineDeprecationsExpectations`, it asserts that the actual count of triggered deprecations is greater than the expectation.
- For every identifier in `$doctrineNoDeprecationsExpectations`, it asserts that the actual count equals the expectation (i.e., no additional deprecations were triggered).
- The actual count is obtained from `Deprecation::getTriggeredDeprecations()[$identifier] ?? 0`.

### Example
```php
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use PHPUnit\Framework\TestCase;

final class MigrationTest extends TestCase
{
    use VerifyDeprecations;

    private const OLD_LINK = 'https://github.com/doctrine/orm/issues/77';

    public function testLegacyEndpointStillWarns(): void
    {
        $this->expectDeprecationWithIdentifier(self::OLD_LINK);

        (new LegacyEndpointController())->handle(); // triggers via Deprecation::trigger()
    }

    public function testNewEndpointIsClean(): void
    {
        $this->expectNoDeprecationWithIdentifier(self::OLD_LINK);

        (new NewEndpointController())->handle();
    }
}
```

### Caveats / Failure Semantics
- Assertions are baseline-relative: a deprecation triggered *before* the expectation call (or by a previous test, since counters are global) does not count toward failure — only occurrences beyond the baseline do.
- Identifiers ignored via `Deprecation::ignoreDeprecations()` never increment counters, so `expectDeprecationWithIdentifier()` for such an identifier always fails.
- Counters are never reset between tests by the trait itself; this is intentional so suites can rely on the diff. To assert absence across an entire suite, reset state in `setUp()` as shown above.
```

--------------------------------

### verifyDeprecationsAreTriggered() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Method signature for the PHPUnit after-test hook that verifies deprecation expectations. Runs automatically after each test via #[After] and @after, and may abort the test by failing an assertion.

```php
/** @after */
#[After]
public function verifyDeprecationsAreTriggered(): void
```

--------------------------------

### expectNoDeprecationWithIdentifier() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Declares a test method that records the current deprecation count for a given identifier and fails if any new occurrences are triggered during the test body.

```php
public function expectNoDeprecationWithIdentifier(string $identifier): void
```

--------------------------------

### enableWithPsrLogger() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Declares the public static method that enables PSR-3 logger-based deprecation handling. It sets the deprecation type, ORs in TYPE_PSR_LOGGER, and stores the logger. Each deprecation is sent via notice() with context.

```php
public static function enableWithPsrLogger(LoggerInterface $logger): void
```

--------------------------------

### enableWithPsrLogger(LoggerInterface $logger): void

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enables PSR-3 logger-based deprecation handling. Each emitted deprecation is sent to the provided logger via notice() with structured context including file, line, package, and link.

```APIDOC
## enableWithPsrLogger(LoggerInterface $logger): void

### Description
Enables PSR-3 logger-based deprecation handling. Each emitted deprecation is sent to the provided logger via notice() with structured context including file, line, package, and link.

### Method
PHP static method

### Signature
`public static function enableWithPsrLogger(LoggerInterface $logger): void`

### Parameters
- **$logger** (Psr\Log\LoggerInterface) - Required - PSR-3 logger that receives each deprecation via `notice()`

### Return
`void`

### Behavior
Sets `self::$type = self::$type ?? self::getTypeFromEnv();`, ORs in `TYPE_PSR_LOGGER`, and stores `$logger`. Each emitted deprecation produces:

```php
$context = [
    'file'    => $backtrace[0]['file'] ?? null,
    'line'    => $backtrace[0]['line'] ?? null,
    'package' => $package,
    'link'    => $link,
];

$logger->notice($message, $context);
```

### Example
```php
use Doctrine\Deprecations\Deprecation;

$logger = new Monolog\Logger('deprecations', [new Monolog\Handler\StreamHandler('php://stderr')]);
Deprecation::enableWithPsrLogger($logger);

try {
    runApplication(); // any Doctrine deprecations become structured log records
} finally {
    foreach (Deprecation::getTriggeredDeprecations() as $identifier => $count) {
        echo $identifier . ' was triggered ' . $count . " times\n";
    }
}
// log record: { message: 'old thing', context: { file: '...', line: 42, package: 'doctrine/orm', link: 'https://...' }, level: notice }
```
```

--------------------------------

### trigger() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Public static method to trigger a deprecation for a given package and identifier. The link serves as the deduplication key and should point to a GitHub issue or wiki entry. Accepts variadic sprintf arguments substituted into the message.

```php
/**
 * Trigger a deprecation for the given package and identfier.
 *
 * The link should point to a Github issue or Wiki entry detailing the
 * deprecation. It is additionally used to de-duplicate the trigger of the
 * same deprecation during a request.
 *
 * @param float|int|string $args
 */
public static function trigger(string $package, string $link, string $message, ...$args): void
```

--------------------------------

### DOCTRINE_DEPRECATIONS environment variable switch in Deprecation::getTypeFromEnv()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/configuration.md

Reads the DOCTRINE_DEPRECATIONS environment variable from $_SERVER first, then $_ENV, and sets the deprecation mode: 'trigger' enables trigger_error, 'track' enables counting, any other value or unset disables the library. This is the only runtime configuration input.

```php
switch ($_SERVER['DOCTRINE_DEPRECATIONS'] ?? $_ENV['DOCTRINE_DEPRECATIONS'] ?? null) {
    case 'trigger':
        self::$type = self::TYPE_TRIGGER_ERROR;
        break;

    case 'track':
        self::$type = self::TYPE_TRACK_DEPRECATIONS;
        break;

    default:
        self::$type = self::TYPE_NONE;
        break;
}

return self::$type;
```

--------------------------------

### expectNoDeprecationWithIdentifier(string $identifier): void

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Records the current occurrence count for a given deprecation identifier as a baseline. Verification passes only if the counter is exactly equal to the baseline after the test body runs, failing with an AssertionFailedError if the deprecation is triggered.

```APIDOC
## expectNoDeprecationWithIdentifier(string $identifier): void

### Description
Records the current occurrence count for a given deprecation identifier as a baseline. Verification passes only if the counter is exactly equal to the baseline after the test body runs, failing with an AssertionFailedError if the deprecation is triggered.

### Method
PHP method

### Endpoint
`expectNoDeprecationWithIdentifier(string $identifier): void`

### Parameters
- **$identifier** (string) - Required - Deprecation identifier that code executed later in the test must **not** trigger

### Return
`void`

### Example
```php
class LegacyConsumerTest extends TestCase
{
    use VerifyDeprecations;

    public function testNewApiIsSilent(): void
    {
        $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/1234');

        triggerTheCodeWithoutDeprecation(); // must not emit that deprecation
    }
}
```

### Failure Condition
`assertTrue($actualCount === $expectation)` fails with message `Deprecation with identifier 'https://github.com/doctrine/orm/issues/1234' was triggered by code executed in test, but expected not to.` — a PHPUnit `AssertionFailedError`.
```

--------------------------------

### PHPUnit XML server variable for DOCTRINE_DEPRECATIONS

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/configuration.md

Shows how to set the DOCTRINE_DEPRECATIONS environment variable as a server variable in PHPUnit XML configuration, typically used to enable trigger mode during tests.

```xml
<php>
    <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
</php>
```

--------------------------------

### Deprecation::disable()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/configuration.md

Performs a full reset of the deprecation state: mask set to 0, logger set to null, deduplication enabled, ignored links cleared, and occurrence counts reset to 0 (keys kept).

```APIDOC
## Deprecation::disable()

### Description
Performs a full reset of the deprecation state: mask set to 0, logger set to null, deduplication enabled, ignored links cleared, and occurrence counts reset to 0 (keys kept).

### Method
Static method

### Signature
`Deprecation::disable()`

### Parameters
None

### Return Value
No return value specified.

### Notes
- Resets deduplication, ignored links, and occurrence counts.
- Does not clear `$ignoredPackages`.
```

--------------------------------

### Aggregate deprecation report using getTriggeredDeprecations()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enable tracking with enableTrackingDeprecations(), then iterate over the returned map to print each identifier and its trigger count. Useful for an aggregate report at the end of a request or test run.

```php
Deprecation::enableTrackingDeprecations();

// ... application code triggers deprecations ...

foreach (Deprecation::getTriggeredDeprecations() as $identifier => $count) {
    printf("%s was triggered %d times\n", $identifier, $count);
}
```

--------------------------------

### Deprecation::trigger()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Triggers a deprecation notice for a given package and identifier. It supports sprintf-style message formatting and deduplication, and can be suppressed via ignorePackage() or ignoreDeprecations().

```APIDOC
## `Deprecation::trigger()`

### Description
Triggers a deprecation notice for a given package and identifier. It supports sprintf-style message formatting and deduplication, and can be suppressed via ignorePackage() or ignoreDeprecations().

### Method
`trigger`

### Signature
`public static function trigger(string $package, string $link, string $message, ...$args): void`

### Parameters
- **$package** (string) - Required - Composer package name that owns the deprecation, e.g. `doctrine/orm`. Used for `ignorePackage()` matching and included in log context / error message suffix.
- **$link** (string) - Required - Deprecation identifier: a URL (GitHub issue/PR/wiki page) describing the deprecation and its alternative. Also the deduplication key.
- **$message** (string) - Required - Deprecation message, optionally containing `sprintf` placeholders, e.g. `%s %d`.
- **...$args** (float|int|string) - Optional - Variadic `sprintf` arguments substituted into `$message`.

### Return
`void` - Emits nothing when disabled or suppressed.

### Behavior
1. Resolves mode: `self::$type ?? self::getTypeFromEnv()`. Returns immediately when `TYPE_NONE`.
2. Returns early if `$link` is in `$ignoredLinks` (no counter increment).
3. Increments `$triggeredDeprecations[$link]` (first occurrence → `1`, else `++`).
4. Returns early if deduplication is on and the count is now `> 1` (backend not invoked).
5. Returns early if `$package` is in `$ignoredPackages`.
6. Applies `sprintf($message, ...$args)` and delegates to the active backends.

### Backends
- **PSR mode**: calls `$logger->notice($message, $context)` with context `['file' => ..., 'line' => ..., 'package' => $package, 'link' => $link]`, where `file`/`line` come from `debug_backtrace()` frame 0 (`null`/`null` if absent; `assert(self::$logger !== null)` guards the call).
- **trigger_error mode**: appends a location suffix and emits a *suppressed* deprecation:

```php
$message .= sprintf(
    ' (%s:%d called by %s:%d, %s, package %s)',
    self::basename($backtrace[0]['file'] ?? 'native code'),
    $backtrace[0]['line'] ?? 0,
    self::basename($backtrace[1]['file'] ?? 'native code'),
    $backtrace[1]['line'] ?? 0,
    $link,
    $package
);

@trigger_error($message, E_USER_DEPRECATED);
```

`basename()` is a non-locale-aware basename using `DIRECTORY_SEPARATOR`. Missing frames are reported as `native code` with line `0`.

### Example — basic trigger with `sprintf` args
```php
use Doctrine\Deprecations\Deprecation;

Deprecation::enableWithTriggerError();

Deprecation::trigger(
    'doctrine/orm',
    'https://github.com/doctrine/orm/issues/1234',
    'Foo::oldMethod() is deprecated, use %s instead.',
    'Foo::newMethod()'
);
// Emits a suppressed E_USER_DEPRECATED error; the message gains a
// location/link/package suffix before dispatch.
```

### Example — untriggerable path (identifier ignored)
```php
Deprecation::ignoreDeprecations('https://github.com/doctrine/orm/issues/1234');

Deprecation::trigger(
    'doctrine/orm',
    'https://github.com/doctrine/orm/issues/1234',
    'Foo::oldMethod() is deprecated.'
); // returns early: no error emitted, no counter increment
```
```

--------------------------------

### enableWithTriggerError()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Enables triggering deprecations via the standard PHP error path. This method puts deprecations on the standard PHP error path via @trigger_error($message, E_USER_DEPRECATED), where the message carries the location suffix, identifier link, and package name.

```APIDOC
## enableWithTriggerError()

### Description
Enables triggering deprecations via the standard PHP error path. This method puts deprecations on the standard PHP error path via @trigger_error($message, E_USER_DEPRECATED), where the message carries the location suffix, identifier link, and package name.

### Method
`public static function enableWithTriggerError(): void`

### Parameters
No parameters.

### Return
`void`

### Example
```php
Deprecation::enableWithTriggerError();

set_error_handler(function (int $errno, string $errstr): bool {
    if ($errno === E_USER_DEPRECATED) {
        // collect $errstr
        return true;
    }
    return false;
});

Deprecation::trigger('doctrine/orm', 'https://github.com/doctrine/orm/issues/9', 'deprecated!');
restore_error_handler();
```
```

--------------------------------

### disable() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Declares the public static method that fully deactivates the library. It takes no parameters and returns void.

```php
public static function disable(): void
```

--------------------------------

### enableTrackingDeprecations() method signature

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Public static method that enables deprecation tracking. It sets the internal type mask to include TYPE_TRACK_DEPRECATIONS, equivalent to the env value 'track'. Calling it activates occurrence counting in trigger(), which getTriggeredDeprecations() reads. The VerifyDeprecations trait calls it automatically before each test.

```php
public static function enableTrackingDeprecations(): void
```

--------------------------------

### Per-test baseline diff with getTriggeredDeprecations()

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Capture the count before and after legacy code, then compare to detect whether the deprecation fired. This pattern is used by the VerifyDeprecations trait.

```php
$before = Deprecation::getTriggeredDeprecations()['https://example.com/issue/1'] ?? 0;

triggerLegacyCode();

$after = Deprecation::getTriggeredDeprecations()['https://example.com/issue/1'] ?? 0;
if ($after === $before) {
    echo "deprecation did not fire";
}
```

--------------------------------

### Recording occurrence count for identifier

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/verify-deprecations.md

Records the current occurrence count for the given identifier into $doctrineDeprecationsExpectations. This baseline is used during @after verification to ensure the counter strictly increases.

```php
$this->doctrineDeprecationsExpectations[$identifier] = Deprecation::getTriggeredDeprecations()[$identifier] ?? 0;
```

--------------------------------

### getUniqueTriggeredDeprecationsCount() internal implementation

Source: https://github.com/doctrine/deprecations/blob/1.1.x/_autodocs/api-reference/deprecation.md

Shows the method's return statement, which sums all occurrence counts using array_reduce. This confirms that the method returns total occurrences, including repeats when deduplication is off.

```php
return array_reduce(self::$triggeredDeprecations, static function (int $carry, int $count) {
    return $carry + $count;
}, 0);
```
Tokens:
Raw