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

Commit 2a750ea

Browse files
greg0irejaviereguiluz
greg0ire
authored and
javiereguiluz
committed
Document changes in the deprecation error handler
See symfony/symfony#29211 See symfony/symfony#28048
1 parent 87e78b4 commit 2a750ea

File tree

4 files changed

+90
-36
lines changed

4 files changed

+90
-36
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 & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Installation
2929

3030
.. code-block:: terminal
3131
32-
$ composer require --dev "symfony/phpunit-bridge:*"
32+
$ composer require --dev symfony/phpunit-bridge
3333
3434
.. include:: /components/require_autoload.rst.inc
3535

@@ -179,7 +179,7 @@ message, enclosed with ``/``. For example, with:
179179
180180
<php>
181181
<server name="KERNEL_CLASS" value="App\Kernel"/>
182-
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
182+
<env name="SYMFONY_DEPRECATIONS_HELPER" value="regex=/foobar/"/>
183183
</php>
184184
</phpunit>
185185
@@ -189,39 +189,89 @@ message contains the ``"foobar"`` string.
189189
Making Tests Fail
190190
~~~~~~~~~~~~~~~~~
191191

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

210221
* forget to fix the deprecated calls if there are any;
211222
* forget to mark appropriate tests with the ``@group legacy`` annotations.
212223

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

218268
Disabling the Deprecation Helper
219269
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220270

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

226276
.. _write-assertions-about-deprecations:
227277

@@ -247,6 +297,10 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt
247297
</listener>
248298
</listeners>
249299
300+
.. versionadded:: 4.2
301+
302+
The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
303+
250304
Write Assertions about Deprecations
251305
-----------------------------------
252306

@@ -287,7 +341,7 @@ Running the following command will display the full stack trace:
287341

288342
.. code-block:: terminal
289343
290-
$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
344+
$ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
291345
292346
Time-sensitive Tests
293347
--------------------

‎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