Nicolas Grekas
Contributed by Nicolas Grekas in #16789 , #16937 and #18232

The PHPUnitBridge component is mostly used for its "deprecation helper" which detects the deprecated features used by your application. This is possible thanks to the @trigger_error() function call used by Symfony and many other PHP applications. Detecting deprecations is very important because you can't upgrade to Symfony 3 if your application uses any deprecated feature.

In Symfony 3.1, the deprecation helper has been improved to help you find and fix deprecations more easily. The deprecation helper now supports different working modes. All of them are enabled depending on the value of the SYMFONY_DEPRECATIONS_HELPER environment variable. The easiest way to configure this variable is in your phpunit.xml configuration file:

1
2
3
4
5
6
7
8
9
10
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.1/phpunit.xsd">

    <!-- ... -->

    <php>
        <server name="KERNEL_DIR" value="app/" />
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="..." />
    </php>
</phpunit>

Ignoring triggered deprecations

This mode is useful when you want to use some PHPUnitBridge features, such as clock mocking or network mocking, but don't care about the possible deprecations of your application.

Set the variable to disabled and PHPUnit won't list the deprecations and it won't make your test suite fail:

1
<env name="SYMFONY_DEPRECATIONS_HELPER" value="disabled" />

Showing the full stack trace of a specific deprecation

Some deprecations may be difficult to solve. That's why you can tell PHPUnitBridge to stop the test suite when some specific deprecation is triggered and to display its full stack trace.

In previous Symfony versions, this feature was already available, but the value of the SYMFONY_DEPRECATIONS_HELPER defined the class and method of the test you want to inspect. In Symfony 3.1, the value of the variable is matched as a regular expression against the deprecation message:

1
2
3
4
5
<!-- stopping at a specific deprecation -->
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/Passing callable strings .*/" />

<!-- stopping at several deprecations -->
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/Passing callable strings .*|Passing a boolean flag .*/" />

Limiting the number of triggered deprecations

If your application is large or if you are upgrading it from a very old Symfony version, fixing all the triggered deprecations can be a daunting task. In those cases it's recommended to fix deprecations step by step.

PHPUnitBridge can help you limiting the number of allowed deprecations. If the value of the environment variable is an integer, tests won't fail if the number of triggered exceptions is less than that limit:

1
2
<!-- tests will fail if 732 or more deprecations are triggered -->
<env name="SYMFONY_DEPRECATIONS_HELPER" value="732" />

The recommended way to proceed is as follows:

  1. Install the PHPUnitBridge in your application and run the test suite for the first time.
  2. Set the value of SYMFONY_DEPRECATIONS_HELPER to the number of deprecations reported by PHPUnit increased by 1.
  3. Now you can run the test suite again and it will only fail if you introduce new deprecations in your code.
  4. As soon as you fix some deprecations, lower the value of SYMFONY_DEPRECATIONS_HELPER variable accordingly.
  5. Keep repeating the previous step until you reach 0 deprecations.
Published in #Living on the edge