10000 minor #11323 Document changes in the deprecation error handler (greg0… · symfony/symfony-docs@48b5da1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 48b5da1

Browse files
javiereguiluzjaviereguiluz
committed
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
2 parents 87e78b4 + 64141fc commit 48b5da1

File tree

4 files changed

+95
-36
lines changed

4 files changed

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

‎components/phpunit_bridge.rst

Lines changed: 83 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,90 @@ 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 have even finer-grained control by using other keys of the ``max``
200+
array, which are ``self``, ``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[self]=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[self]=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 you should create a pull
238+
request on the outdated vendor, and ignore these deprecations until your
239+
pull request is merged. This key allows you to put a threshold on direct
240+
deprecations only,allowing you to notice when *your code* is using
241+
deprecated APIs, and to keep up with the changes. You can of course
242+
still use ``max[indirect]`` if you want to keep indirect deprecations
243+
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 robust/no dependencies |
252+
+------------------------+-----------------------------------------------------+
253+
| max[direct]=0 | Recommended for projects with dependencies |
254+
| | that fail to keep up with new deprecations. |
255+
+------------------------+-----------------------------------------------------+
256+
| max[self]=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 bridge 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.
217268

218269
Disabling the Deprecation Helper
219270
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220271

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.
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.
225276

226277
.. _write-assertions-about-deprecations:
227278

@@ -247,6 +298,10 @@ class autoloading time. This can be disabled with the ``debug-class-loader`` opt
247298
</listener>
248299
</listeners>
249300
301+
.. versionadded:: 4.2
302+
303+
The ``DebugClassLoader`` integration was introduced in Symfony 4.2.
304+
250305
Write Assertions about Deprecations
251306
-----------------------------------
252307

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

288343
.. code-block:: terminal
289344
290-
$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
345+
$ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
291346
292347
Time-sensitive Tests
293348
--------------------

‎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: 9 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,15 @@ 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:
116+
117+
.. code-block:: terminal
118+
119+
$ SYMFONY_DEPRECATIONS_HELPER=max[total]=999999 php ./bin/phpunit
116120
117121
.. _upgrade-major-symfony-composer:
118122

0 commit comments

Comments
 (0)
0