Context

We've recently upgraded PHPUnit to version 10.5, up from 9.6, and also made the decision to remove the symfony/phpunit-bridge dev dependency. This choice was influenced by the insights from the "PHPUnit 10 for Symfony Developers" talk presented at SymfonyCon Brussels/SymfonyOnline, which indicated that the bridge is no longer necessary for reporting deprecations.

Our development involves a closed-source Symfony project for a client, and we've traditionally relied on the symfony/phpunit-bridge for deprecation reports. Specifically, we focus on identifying self and direct deprecations, such as instances where we call a method in our src directory from a third-party library in the vendor directory that will be removed in the next major version. This proactive approach helps us stay ahead during upgrades and the planning of our development tasks.

Previous approach using symfony/phpunit-bridge

With symfony/phpunit-bridge, distinguishing between self, direct, and indirect deprecations was possible, see here and here. We utilized this to make tests fail on self and especially direct deprecations while "ignoring" indirect deprecations, as they cannot directly be addressed by us.

Current possibilites

With PHPUnit 10.5, it is already possible to get reports on deprecations using the following configuration (inspired by slide #66 from the conference's talk).

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
         bootstrap="tests/bootstrap.php"
         displayDetailsOnTestsThatTriggerDeprecations="true"
         failOnDeprecation="true">
    <!-- ... -->

    <source restrictDeprecations="true"
            ignoreSuppressionOfDeprecations="true">
        <include>
            <directory>src</directory>
            <file>vendor/symfony/deprecation-contracts/function.php</file>
        </include>
    </source>
</phpunit>

This will produce the following output when running tests that eventually trigger both direct and also indirect deprecations:

> XDEBUG_MODE=off vendor/bin/phpunit --testdox
PHPUnit 10.5.9 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.3.2
Configuration: /var/www/app/phpunit.xml.dist

DD                                                                  2 / 2 (100%)

Time: 00:00.294, Memory: 52.50 MB

Example (App\Tests\Functional\Example\Example)
 ⚠ Something
 ⚠ Something else

2 tests triggered 2 deprecations:

1) /var/www/app/vendor/symfony/deprecation-contracts/function.php:25
Since example/example 1.7.0: Direct deprecation triggered by calling a deprecated method located in vendor from the src directory

Triggered by:

* App\Tests\Functional\Example\ExampleTest::testSomething (3 times)
  /var/www/app/tests/Functional/Example/ExampleTest.php:14

* App\Tests\Functional\Example\ExampleTest::testSomethingElse (3 times)
  /var/www/app/tests/Functional/Example/ExampleTest.php:25

2) /var/www/app/vendor/symfony/deprecation-contracts/function.php:25
Since example2/example2 2.3.0: Indirect deprecation triggered by calling a deprecated method located in vendor library from a non-deprecated method located in another vendor library which is called by a method in the src directory

Triggered by:

* App\Tests\Functional\Example\ExampleTest::testSomething (3 times)
  /var/www/app/tests/Functional/Example/ExampleTest.php:14

* App\Tests\Functional\Example\ExampleTest::testSomethingElse (3 times)
  /var/www/app/tests/Functional/Example/ExampleTest.php:25

OK, but there were issues!
Tests: 2, Assertions: 8, Deprecations: 2.
Script XDEBUG_MODE=off vendor/bin/phpunit --testdox handling the test event returned with error code 1

Feature request

With PHPUnit's added functionalities througout 10.X, nearly all the functionalities of symfony/phpunit-bridge can be replaced. However, regardless of where the deprecation is triggered, it is reported as a deprecation and will, if configured, fail the respective test.

We propose adding the capability to distinguish whether a deprecation can be fixed by the project's maintainer (self & direct deprecations) or if a project is unable to do so because the deprecated code is called internally by a third-party library from another third-party library (indirect).

A possible configuration option could look like this:

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
         bootstrap="tests/bootstrap.php"
+        reportDeprecations="self,direct"
         displayDetailsOnTestsThatTriggerDeprecations="true"
         failOnDeprecation="true">
    <!-- ... -->
</phpunit>

Big thanks to everyone who's been part of improving PHPUnit! As we suggest this feature, fingers crossed we haven't missed a config trick or an ongoing discussion about it. If there's more we can share — examples, insights, you name it — we're glad to assist. Thanks! 🚀