Symfony
sponsored by SensioLabs
Menu
  • About
  • Documentation
  • Screencasts
  • Cloud
  • Certification
  • Community
  • Businesses
  • News
  • Download
  1. Home
  2. Documentation
  3. Components
  4. The PHPUnit Bridge
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud
Search by Algolia

Table of Contents

  • Installation
  • Usage
  • Trigger Deprecation Notices
  • Mark Tests as Legacy
  • Configuration
  • Making Tests Fail

The PHPUnit Bridge

Edit this page

Warning: You are browsing the documentation for Symfony 2.7, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

The PHPUnit Bridge

The PHPUnit Bridge provides utilities to report legacy tests and usage of deprecated code.

It comes with the following features:

  • Forces the tests to use a consistent locale (C);
  • Auto-register class_exists to load Doctrine annotations (when used);
  • It displays the whole list of deprecated features used in the application;
  • Displays the stack trace of a deprecation on-demand;

2.7

The PHPUnit Bridge was introduced in Symfony 2.7. It is however possible to install the bridge in any Symfony application (even 2.3).

Installation

1
$ composer require --dev "symfony/phpunit-bridge:*"

Alternatively, you can clone the https://github.com/symfony/phpunit-bridge repository.

Note

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

Note

The PHPUnit bridge is designed to work with all maintained versions of Symfony components, even across different major versions of them. You should always use its very latest stable major version to get the most accurate deprecation report.

Usage

Once the component is installed, a simple-phpunit script is created in the vendor/ directory to run tests. This script wraps the original PHPUnit binary to provide more features:

1
2
$ cd my-project/
$ ./vendor/bin/simple-phpunit

After running your PHPUnit tests, you will get a report similar to this one:

The summary includes:

Unsilenced
Reports deprecation notices that were triggered without the recommended @-silencing operator.
Legacy
Deprecation notices denote tests that explicitly test some legacy features.
Remaining/Other
Deprecation notices are all other (non-legacy) notices, grouped by message, test class and method.

Note

If you don't want to use the simple-phpunit script, register the following PHPUnit event listener in your PHPUnit configuration file to get the same report about deprecations (which is created by a PHP error handler called DeprecationErrorHandler):

1
2
3
4
5
<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
</listeners>

Trigger Deprecation Notices

Deprecation notices can be triggered by using:

1
@trigger_error('Your deprecation message', E_USER_DEPRECATED);

Without the @-silencing operator, users would need to opt-out from deprecation notices. Silencing by default swaps this behavior and allows users to opt-in when they are ready to cope with them (by adding a custom error handler like the one provided by this bridge). When not silenced, deprecation notices will appear in the Unsilenced section of the deprecation report.

Mark Tests as Legacy

There are three ways to mark a test as legacy:

  • (Recommended) Add the @group legacy annotation to its class or method;
  • Make its class name start with the Legacy prefix;
  • Make its method name start with testLegacy*() instead of test*().

Note

If your data provider calls code that would usually trigger a deprecation, you can prefix its name with provideLegacy or getLegacy to silent these deprecations. If your data provider does not execute deprecated code, it is not required to choose a special naming just because the test being fed by the data provider is marked as legacy.

Also be aware that choosing one of the two legacy prefixes will not mark tests as legacy that make use of this data provider. You still have to mark them as legacy tests explicitly.

Configuration

In case you need to inspect the stack trace of a particular deprecation triggered by your unit tests, you can set the SYMFONY_DEPRECATIONS_HELPER environment variable to a regular expression that matches this deprecation's message, enclosed with /. For example, with:

1
2
3
4
5
6
7
8
9
10
11
12
<!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
<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="/foobar/" />
    </php>
</phpunit>

PHPUnit will stop your test suite once a deprecation notice is triggered whose message contains the "foobar" string.

Making Tests Fail

By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation notices will make tests fail. Alternatively, setting SYMFONY_DEPRECATIONS_HELPER to an arbitrary value (ex: 320) will make the tests fails only if a higher number of deprecation notices is reached (0 is the default value). You can also set the value "weak" which will make the bridge ignore any deprecation notices. This is useful to projects that must use deprecated interfaces for backward compatibility reasons.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
We stand with Ukraine.
Version:
Become certified from home

Become certified from home

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

Avatar of Farid Jalilov, a Symfony contributor

Thanks Farid Jalilov for being a Symfony contributor

1 commit • 8 lines changed

View all contributors that help us make Symfony

Become a Symfony contributor

Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

Learn how to contribute

Symfony™ is a trademark of Symfony SAS. All rights reserved.

  • What is Symfony?
    • Symfony at a Glance
    • Symfony Components
    • Case Studies
    • Symfony Releases
    • Security Policy
    • Logo & Screenshots
    • Trademark & Licenses
    • symfony1 Legacy
  • Learn Symfony
    • Symfony Docs
    • Symfony Book
    • Reference
    • Bundles
    • Best Practices
    • Training
    • eLearning Platform
    • Certification
  • Screencasts
    • Learn Symfony
    • Learn PHP
    • Learn JavaScript
    • Learn Drupal
    • Learn RESTful APIs
  • Community
    • SymfonyConnect
    • Support
    • How to be Involved
    • Code of Conduct
    • Events & Meetups
    • Projects using Symfony
    • Downloads Stats
    • Contributors
    • Backers
  • Blog
    • Events & Meetups
    • A week of symfony
    • Case studies
    • Cloud
    • Community
    • Conferences
    • Diversity
    • Documentation
    • Living on the edge
    • Releases
    • Security Advisories
    • SymfonyInsight
    • Twig
    • SensioLabs
  • Services
    • SensioLabs services
    • Train developers
    • Manage your project quality
    • Improve your project performance
    • Host Symfony projects
    Deployed on
Follow Symfony
Search by Algolia