diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst
index 6424d807b5a..2bb5d7752da 100644
--- a/bundles/best_practices.rst
+++ b/bundles/best_practices.rst
@@ -197,9 +197,9 @@ of Symfony and the latest beta release:
include:
# Minimum supported dependencies with the latest and oldest PHP version
- php: 7.2
- env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
+ env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0"
- php: 7.0
- env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
+ env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0"
# Test the latest stable release
- php: 7.0
diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst
index b3946afa40d..cf5fdd3d029 100644
--- a/components/phpunit_bridge.rst
+++ b/components/phpunit_bridge.rst
@@ -180,7 +180,7 @@ message, enclosed with ``/``. For example, with:
-
+
@@ -190,39 +190,89 @@ 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.
-
-When you maintain a library, having the test suite fail as soon as a dependency
-introduces a new deprecation is not desirable, because it shifts the burden of
-fixing that deprecation to any contributor that happens to submit a pull
-request shortly after a new vendor release is made with that deprecation. To
-mitigate this, you can either use tighter requirements, in the hope that
-dependencies will not introduce deprecations in a patch version, or even commit
-the Composer lock file, which would create another class of issues. Libraries
-will often use ``SYMFONY_DEPRECATIONS_HELPER=weak`` because of this. This has
-the drawback of allowing contributions that introduce deprecations but:
+By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation
+notices will make tests fail. Alternatively, you can configure an
+arbitrary threshold by setting ``SYMFONY_DEPRECATIONS_HELPER`` to
+``max[total]=320`` for instance. It will make the tests fails only if a
+higher number of deprecation notices is reached (``0`` is the default
+value).
+
+You can even finer-grained control by using other keys of the ``max``
+array, which are ``internal``, ``direct``, and ``indirect``. The
+``SYMFONY_DEPRECATIONS_HELPER`` environment variable accept a
+url-encoded string, meaning you can combine thresholds and any other
+configuration setting, like this:
+``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[internal]=0&verbose=0``
+
+Internal deprecations
+.....................
+
+When you maintain a library, having the test suite fail as soon as a
+dependency introduces a new deprecation is not desirable, because it
+shifts the burden of fixing that deprecation to any contributor that
+happens to submit a pull request shortly after a new vendor release is
+made with that deprecation. To mitigate this, you can either use tighter
+requirements, in the hope that dependencies will not introduce
+deprecations in a patch version, or even commit the Composer lock file,
+which would create another class of issues. Libraries will often use
+``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999`` because of this. This
+has the drawback of allowing contributions that introduce deprecations
+but:
* forget to fix the deprecated calls if there are any;
* forget to mark appropriate tests with the ``@group legacy`` annotations.
-By using the ``"weak_vendors"`` value, deprecations that are triggered outside
-the ``vendors`` directory will make the test suite fail, while deprecations
-triggered from a library inside it will not, giving you the best of both
-worlds.
+By using ``SYMFONY_DEPRECATIONS_HELPER=max[internal]=0``,
+deprecations that are triggered outside the ``vendors`` directory will
+be accounted for seperately, while deprecations triggered from a library
+inside it will not (unless you reach 999999 of these), giving you
+the best of both worlds.
+
+Direct and indirect deprecations
+................................
+
+When working on a project, you might be more interested in
+``max[direct]``. Let's say you want to fix deprecations as soon as
+they appear. A problem many people experience is that some dependencies
+they have tend to lag behind their own dependencies, meaning they do not
+fix deprecations as soon as possible, which means there is nothing you
+can do to fix those (apart from a pull request on the outdated vendor).
+This key allows you to put a threshold on direct deprecations only,
+allowing you to notice when *your code* is using deprecated APIs, and to
+keep up with the changes. You can of course still use ``max[indirect]``
+if you want to keep indirect deprecations under a given threshold.
+
+Here is a summary that should help you pick the right configuration:
+
++------------------------+-----------------------------------------------------+
+| Value | Recommended situation |
++========================+=====================================================+
+| max[total]=0 | Recommended for actively maintained projects |
+| | with little to no dependencies |
++------------------------+-----------------------------------------------------+
+| max[direct]=0 | Recommended for projects with dependencies |
+| | that fail to keep up with new deprecations. |
++------------------------+-----------------------------------------------------+
+| max[internal]=0 | Recommended for libraries that use |
+| | the deprecation system themselves and |
+| | cannot afford to use one of the modes above. |
++------------------------+-----------------------------------------------------+
+
+Disabling the verbose output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the brige will display a detailed output with the number of
+deprecations and where they arise. If this is too much for you, you can
+use ``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output
+off.
Disabling the Deprecation Helper
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to ``disabled`` to
-completely disable the deprecation helper. This is useful to make use of the
-rest of features provided by this component without getting errors or messages
-related to deprecations.
+Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to
+``disabled=1`` to completely disable the deprecation helper. This is
+useful to make use of the rest of features provided by this component
+without getting errors or messages related to deprecations.
.. _write-assertions-about-deprecations:
@@ -289,7 +339,7 @@ Running the following command will display the full stack trace:
.. code-block:: terminal
- $ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
+ $ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
Time-sensitive Tests
--------------------
diff --git a/setup/bundles.rst b/setup/bundles.rst
index a83916898c7..53104c6c9ba 100644
--- a/setup/bundles.rst
+++ b/setup/bundles.rst
@@ -142,7 +142,7 @@ following recommended configuration as the starting point of your own configurat
matrix:
include:
- php: 5.3.3
- env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=weak
+ env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=max[total]=999999
- php: 5.6
env: SYMFONY_VERSION='2.7.*'
- php: 5.6
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
index fd746ffed2a..f52203a96ff 100644
--- a/setup/upgrade_major.rst
+++ b/setup/upgrade_major.rst
@@ -97,9 +97,9 @@ done!
Sometimes, you can't fix all deprecations (e.g. something was deprecated
in 3.4 and you still need to support 3.3). In these cases, you can still
- use the bridge to fix as many deprecations as possible and then switch
- to the weak test mode to make your tests pass again. You can do this by
- using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
+ use the bridge to fix as many deprecations as possible and then allow
+ more of them to make your tests pass again. You can do this by using the
+ ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
.. code-block:: xml
@@ -108,11 +108,11 @@ done!
-
+
- (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).
+ (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit``).
.. _upgrade-major-symfony-composer: