Movatterモバイル変換

[0]ホーム
URL:

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

 Sign up
Appearance settings

Commit2a750ea

Browse files
greg0irejaviereguiluz
authored andcommitted
Document changes in the deprecation error handler
Seesymfony/symfony#29211Seesymfony/symfony#28048
1 parent87e78b4 commit2a750ea

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
<servername="KERNEL_CLASS"value="App\Kernel"/>
182-
<envname="SYMFONY_DEPRECATIONS_HELPER"value="/foobar/"/>
182+
<envname="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`` tocompletely disable the deprecation helper. This is
273+
useful to make use of therest of features provided by this component
274+
without getting errors or messagesrelated 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 thenswitch
101-
to the weak test modeto 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 thenallow
101+
more of themto 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-
<envname="SYMFONY_DEPRECATIONS_HELPER"value="weak"/>
111+
<envname="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)
[8]ページ先頭
©2009-2025 Movatter.jp