minor #11323 Document changes in the deprecation error handler (greg0ire, llaakkkk)

This PR was submitted for the master branch but it was merged into the 4.3 branch instead (closes #11323).

Discussion
----------

Document changes in the deprecation error handler

See symfony/symfony#29211
See symfony/symfony#28048

Closes #10701

Commits
-------

64141fc fixup! Document changes in the deprecation error handler
dd7eb0b fixup! Document changes in the deprecation error handler
b2a7744 fixup! Document changes in the deprecation error handler
988badf fixup! Document changes in the deprecation error handler
2a750ea Document changes in the deprecation error handler

Author: javiereguiluz

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[self]=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[self]=0"
 
               # Test the latest stable release
             - php: 7.0

components/phpunit_bridge.rst

@@ -29,7 +29,7 @@ Installation
 
 .. code-block:: terminal
 
-    $ composer require --dev "symfony/phpunit-bridge:*"
+    $ composer require --dev symfony/phpunit-bridge
 
 .. include:: /components/require_autoload.rst.inc
 
@@ -179,7 +179,7 @@ message, enclosed with ``/``. For example, with:
 
         <php>
             <server name="KERNEL_CLASS" value="App\Kernel"/>
-            <env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
+            <env name="SYMFONY_DEPRECATIONS_HELPER" value="regex=/foobar/"/>
         </php>
     </phpunit>
 
@@ -189,39 +189,90 @@ 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 have even finer-grained control by using other keys of the ``max``
+array, which are ``self``, ``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[self]=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[self]=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 you should create a pull
+request on the outdated vendor, and ignore these deprecations until your
+pull request is merged. 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 robust/no dependencies                         |
++------------------------+-----------------------------------------------------+
+| max[direct]=0          | Recommended for projects with dependencies          |
+|                        | that fail to keep up with new deprecations.         |
++------------------------+-----------------------------------------------------+
+| max[self]=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 bridge 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:
 
@@ -247,6 +298,10 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt
         </listener>
     </listeners>
 
+.. versionadded:: 4.2
+
+    The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
+
 Write Assertions about Deprecations
 -----------------------------------
 
@@ -287,7 +342,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
 --------------------

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

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,15 @@ done!
             <!-- ... -->
 
             <php>
-                <env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
+                <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[total]=999999"/>
             </php>
         </phpunit>
 
-    (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).
+    You can also execute the command like:
+
+    .. code-block:: terminal
+
+        $ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 php ./bin/phpunit
 
 .. _upgrade-major-symfony-composer: