Loheide-eu-mitarbeiterplatt.../vendor/doctrine/deprecations
Friederich Loheide 9c0f8de791
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 1m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 1m12s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 1m7s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 1m19s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 1m32s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 1m22s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 1m32s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 1m35s
CI / Build-Artefakte aktuell (pull_request) Failing after 1m7s
Phase 0: Fundament für Inhaus
- Laravel 13 mit Filament 5 (Admin), Inertia 3 + Vue 3 + Vuetify 4 (Material 3)
- Anmeldung über Fortify (Login, Passwort vergessen/ändern), keine Selbstregistrierung
- Profil mit Profilbild (WebP in festen Größen), Personenseiten, Header mit Avatar-Menü
- Material-3-Farbschema aus der Primärfarbe, hell/dunkel/System pro Person
- Basis-Branding (Portalname, Logo, Primärfarbe) im Admin unter „Erscheinungsbild“
- Benutzerverwaltung im Admin, Zugang vorläufig über is_admin
- vendor/ (ohne Dev-Pakete) und Frontend-Build mitversioniert, Dev-Pakete in vendor-dev/
- PHPUnit-Tests gegen MySQL/MariaDB, Forgejo-CI-Matrix, Docker-Entwicklungsumgebung
- VERSION, CHANGELOG.md und CONTRIBUTING.md mit Release-Ablauf

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 20:35:30 +00:00
..
src Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
composer.json Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
LICENSE Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00
README.md Phase 0: Fundament für Inhaus 2026-09-25 20:35:30 +00:00

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:

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

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

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:

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

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

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

<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>

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
<?php

declare(strict_types=1);

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

use Doctrine\Deprecations\Deprecation;

Deprecation::withoutDeduplication();

Then, reference that file in your PHPUnit configuration:

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

What is a deprecation identifier?

An identifier for deprecations is just a link to any resource, most often a Github Issue or Pull Request explaining the deprecation and potentially its alternative.