8000 Document changes in the deprecation error handler · symfony/symfony-docs@eb6e5e2 · GitHub
[go: up one dir, main page]
Skip to content

Commit eb6e5e2

Browse files
greg0ireOlena Kirichok
greg0ire
authored and
Olena Kirichok
committed
Document changes in the deprecation error handler
See symfony/symfony#29211 See symfony/symfony#28048
1 parent 98dfd5d commit eb6e5e2

File tree

4 files changed

+90
-35
lines changed

4 files changed

+90
-35
lines changed

‎bundles/best_practices.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -197,9 +197,9 @@ of Symfony and the latest beta release:
197197
include:
198198
# Minimum supported dependencies with the latest and oldest PHP version
199199
- php: 7.2
200-
env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
200+
env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0"
201201
- php: 7.0
202-
env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="weak_vendors"
202+
env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" SYMFONY_DEPRECATIONS_HELPER="max[internal]=0"
203203
204204
# Test the latest stable release
205205
- php: 7.0

‎components/phpunit_bridge.rst

Lines changed: 82 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Installation
3030
3131
$ composer require --dev "symfony/phpunit-bridge:*"
3232
33+
Alternatively, you can clone the `<https://github.com/symfony/phpunit-bridge>`_ repository.
34+
3335
.. include:: /components/require_autoload.rst.inc
3436

3537
.. note::
@@ -178,7 +180,7 @@ message, enclosed with ``/``. For example, with:
178180
179181
<php>
180182
<server name="KERNEL_CLASS" value="App\Kernel"/>
181-
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
183+
<env name="SYMFONY_DEPRECATIONS_HELPER" value="regex=/foobar/"/>
182184
</php>
183185
</phpunit>
184186
@@ -188,39 +190,89 @@ message contains the ``"foobar"`` string.
188190
Making Tests Fail
189191
~~~~~~~~~~~~~~~~~
190192

191-
By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation notices
192-
will make tests fail. Alternatively, setting ``SYMFONY_DEPRECATIONS_HELPER`` to
193-
an arbitrary value (ex: ``320``) will make the tests fails only if a higher
194-
number of deprecation notices is reached (``0`` is the default value). You can
195-
also set the value ``"weak"`` which will make the bridge ignore any deprecation
196-
notices. This is useful to projects that must use deprecated interfaces for
197-
backward compatibility reasons.
198-
199-
When you maintain a library, having the test suite fail as soon as a dependency
200-
introduces a new deprecation is not desirable, because it shifts the burden of
201-
fixing that deprecation to any contributor that happens to submit a pull
202-
request shortly after a new vendor release is made with that deprecation. To
203-
mitigate this, you can either use tighter requirements, in the hope that
204-
dependencies will not introduce deprecations in a patch version, or even commit
205-
the Composer lock file, which would create another class of issues. Libraries
206-
will often use ``SYMFONY_DEPRECATIONS_HELPER=weak`` because of this. This has
207-
the drawback of allowing contributions that introduce deprecations but:
193+
By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation
194+
notices will make tests fail. Alternatively, you can configure an
195+
arbitrary threshold by setting ``SYMFONY_DEPRECATIONS_HELPER`` to
196+
``max[total]=320`` for instance. It will make the tests fails only if a
197+
higher number of deprecation notices is reached (``0`` is the default
198+
value).
199+
200+
You can even finer-grained control by using other keys of the ``max``
201+
array, which are ``internal``, ``direct``, and ``indirect``. The
202+
``SYMFONY_DEPRECATIONS_HELPER`` environment variable accept a
203+
url-encoded string, meaning you can combine thresholds and any other
204+
configuration setting, like this:
205+
``SYMFONY_DEPRECATIONS_HELPER=max[total]=42&max[internal]=0&verbose=0``
206+
207+
Internal deprecations
208+
.....................
209+
210+
When you maintain a library, having the test suite fail as soon as a
211+
dependency introduces a new deprecation is not desirable, because it
212+
shifts the burden of fixing that deprecation to any contributor that
213+
happens to submit a pull request shortly after a new vendor release is
214+
made with that deprecation. To mitigate this, you can either use tighter
215+
requirements, in the hope that dependencies will not introduce
216+
deprecations in a patch version, or even commit the Composer lock file,
217+
which would create another class of issues. Libraries will often use
218+
``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999`` because of this. This
219+
has the drawback of allowing contributions that introduce deprecations
220+
but:
208221

209222
* forget to fix the deprecated calls if there are any;
210223
* forget to mark appropriate tests with the ``@group legacy`` annotations.
211224

212-
By using the ``"weak_vendors"`` value, deprecations that are triggered outside
213-
the ``vendors`` directory will make the test suite fail, while deprecations
214-
triggered from a library inside it will not, giving you the best of both
215-
worlds.
225+
By using ``SYMFONY_DEPRECATIONS_HELPER=max[internal]=0``,
226+
deprecations that are triggered outside the ``vendors`` directory will
227+
be accounted for seperately, while deprecations triggered from a library
228+
inside it will not (unless you reach 999999 of these), giving you
229+
the best of both worlds.
230+
231+
Direct and indirect deprecations
232+
................................
233+
234+
When working on a project, you might be more interested in
235+
``max[direct]``. Let's say you want to fix deprecations as soon as
236+
they appear. A problem many people experience is that some dependencies
237+
they have tend to lag behind their own dependencies, meaning they do not
238+
fix deprecations as soon as possible, which means there is nothing you
239+
can do to fix those (apart from a pull request on the outdated vendor).
240+
This key allows you to put a threshold on direct deprecations only,
241+
allowing you to notice when *your code* is using deprecated APIs, and to
242+
keep up with the changes. You can of course still use ``max[indirect]``
243+
if you want to keep indirect deprecations under a given threshold.
244+
245+
Here is a summary that should help you pick the right configuration:
246+
247+
+------------------------+-----------------------------------------------------+
248+
| Value | Recommended situation |
249+
+========================+=====================================================+
250+
| max[total]=0 | Recommended for actively maintained projects |
251+
| | with little to no dependencies |
252+
+------------------------+-----------------------------------------------------+
253+
| max[direct]=0 | Recommended for projects with dependencies |
254+
| | that fail to keep up with new deprecations. |
255+
+------------------------+-----------------------------------------------------+
256+
| max[internal]=0 | Recommended for libraries that use |
257+
| | the deprecation system themselves and |
258+
| | cannot afford to use one of the modes above. |
259+
+------------------------+-----------------------------------------------------+
260+
261+
Disabling the verbose output
262+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263+
264+
By default, the brige will display a detailed output with the number of
265+
deprecations and where they arise. If this is too much for you, you can
266+
use ``SYMFONY_DEPRECATIONS_HELPER=verbose=0`` to turn the verbose output
267+
off.
216268

217269
Disabling the Deprecation Helper
218270
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219271

220-
Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to ``disabled`` to
221-
completely disable the deprecation helper. This is useful to make use of the
222-
rest of features provided by this component without getting errors or messages
223-
related to deprecations.
272+
Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to
273+
``disabled=1`` to completely disable the deprecation helper. This is
274+
useful to make use of the rest of features provided by this component
275+
without getting errors or messages related to deprecations.
224276

225277
.. _write-assertions-about-deprecations:
226278

@@ -246,6 +298,9 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt
246298
</listener>
247299
</listeners>
248300
301+
.. versionadded:: 4.2
302+
The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
303+
249304
Write Assertions about Deprecations
250305
-----------------------------------
251306

@@ -284,7 +339,7 @@ Running the following command will display the full stack trace:
284339

285340
.. code-block:: terminal
286341
287-
$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
342+
$ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
288343
289344
Time-sensitive Tests
290345
--------------------

‎setup/bundles.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ following recommended configuration as the starting point of your own configurat
142142
matrix:
143143
include:
144144
- php: 5.3.3
145-
env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=weak
145+
env: COMPOSER_FLAGS='--prefer-lowest --prefer-stable' SYMFONY_DEPRECATIONS_HELPER=max[total]=999999
146146
- php: 5.6
147147
env: SYMFONY_VERSION='2.7.*'
148148
- php: 5.6

‎setup/upgrade_major.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,9 @@ done!
9797

9898
Sometimes, you can't fix all deprecations (e.g. something was deprecated
9999
in 3.4 and you still need to support 3.3). In these cases, you can still
100-
use the bridge to fix as many deprecations as possible and then switch
101-
to the weak test mode to make your tests pass again. You can do this by
102-
using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
100+
use the bridge to fix as many deprecations as possible and then allow
101+
more of them to make your tests pass again. You can do this by using the
102+
``SYMFONY_DEPRECATIONS_HELPER`` env variable:
103103

104104
.. code-block:: xml
105105
@@ -108,11 +108,11 @@ done!
108108
<!-- ... -->
109109
110110
<php>
111-
<env name="SYMFONY_DEPRECATIONS_HELPER" value="weak"/>
111+
<env name="SYMFONY_DEPRECATIONS_HELPER" value="max[total]=999999"/>
112112
</php>
113113
</phpunit>
114114
115-
(you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).
115+
(you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 phpunit``).
116116

117117
.. _upgrade-major-symfony-composer:
118118

0 commit comments

Comments
 (0)
0