Document changes in the deprecation error handler

greg0ire · Olena Kirichok · commit 8f8bce1fede1 · 2019-04-06T21:09:48.000+02:00
See symfony/symfony#29211 See symfony/symfony#28048
diff --git 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
@@ -178,7 +178,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>
 
@@ -188,39 +188,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:
 
@@ -246,6 +296,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
 -----------------------------------
 
@@ -284,7 +338,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
@@ -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
@@ -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!
             <!-- ... -->
 
             <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 ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit``).
 
 .. _upgrade-major-symfony-composer:
 
