Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 884c063

Browse filesBrowse 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 884c063
Copy full SHA for 884c063

File tree

Expand file treeCollapse file tree

4 files changed

+90
-36
lines changed
Filter options
Expand file treeCollapse file tree

4 files changed

+90
-36
lines changed

‎bundles/best_practices.rst

Copy file name to clipboardExpand all lines: bundles/best_practices.rst
+2-2Lines 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

Copy file name to clipboardExpand all lines: components/phpunit_bridge.rst
+82-28Lines changed: 82 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Installation
2828

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

@@ -178,7 +178,7 @@ message, enclosed with ``/``. For example, with:
178178
179179
<php>
180180
<server name="KERNEL_CLASS" value="App\Kernel"/>
181-
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
181+
<env name="SYMFONY_DEPRECATIONS_HELPER" value="regex=/foobar/"/>
182182
</php>
183183
</phpunit>
184184
@@ -188,39 +188,89 @@ message contains the ``"foobar"`` string.
188188
Making Tests Fail
189189
~~~~~~~~~~~~~~~~~
190190

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

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

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

217267
Disabling the Deprecation Helper
218268
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219269

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.
270+
Set the ``SYMFONY_DEPRECATIONS_HELPER`` environment variable to
271+
``disabled=1`` to completely disable the deprecation helper. This is
272+
useful to make use of the rest of features provided by this component
273+
without getting errors or messages related to deprecations.
224274

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

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

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

285339
.. code-block:: terminal
286340
287-
$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
341+
$ SYMFONY_DEPRECATIONS_HELPER='regex=/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit
288342
289343
Time-sensitive Tests
290344
--------------------

‎setup/bundles.rst

Copy file name to clipboardExpand all lines: setup/bundles.rst
+1-1Lines 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

Copy file name to clipboardExpand all lines: setup/upgrade_major.rst
+5-5Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.