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 c494084

Browse filesBrowse files
wouterjwouterj
committed
feature #13379 Use trigger_deprecation instead of @trigger_error (l-vo)
This PR was merged into the master branch. Discussion ---------- Use trigger_deprecation instead of @trigger_error Commits ------- 6702c1e Use trigger_deprecation instead of @trigger_error
2 parents 66bb9e8 + 6702c1e commit c494084
Copy full SHA for c494084

File tree

4 files changed

+16
-28
lines changed
Filter options

4 files changed

+16
-28
lines changed

‎components/phpunit_bridge.rst

Copy file name to clipboardExpand all lines: components/phpunit_bridge.rst
+6-10Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -163,13 +163,9 @@ Trigger Deprecation Notices
163163

164164
Deprecation notices can be triggered by using::
165165

166-
@trigger_error('Your deprecation message', E_USER_DEPRECATED);
166+
trigger_deprecation('vendor-name/package-name', '5.1', 'Your deprecation message');
167167

168-
Without the `@-silencing operator`_, users would need to opt-out from deprecation
169-
notices. Silencing by default swaps this behavior and allows users to opt-in
170-
when they are ready to cope with them (by adding a custom error handler like the
171-
one provided by this bridge). When not silenced, deprecation notices will appear
172-
in the **Unsilenced** section of the deprecation report.
168+
Where 5.1 is the version from which the deprecation starts. Note that the deprecation message can use the :phpfunction:`printf` format. In this case, you can pass placeholders as extra arguments after the deprecation message.
173169

174170
Mark Tests as Legacy
175171
--------------------
@@ -354,14 +350,14 @@ times (order matters)::
354350
public function testDeprecatedCode()
355351
{
356352
// test some code that triggers the following deprecation:
357-
// @trigger_error('This "Foo" method is deprecated.', E_USER_DEPRECATED);
358-
$this->expectDeprecation('This "%s" method is deprecated');
353+
// trigger_deprecation('vendor-name/package-name', '5.1', 'This "Foo" method is deprecated.');
354+
$this->expectDeprecation('Since vendor-name/package-name 5.1: This "%s" method is deprecated');
359355

360356
// ...
361357

362358
// test some code that triggers the following deprecation:
363-
// @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED);
364-
$this->expectDeprecation('The second argument of the "%s" method is deprecated.');
359+
// trigger_deprecation('vendor-name/package-name', '4.4', 'The second argument of the "Bar" method is deprecated.');
360+
$this->expectDeprecation('Since vendor-name/package-name 4.4: The second argument of the "%s" method is deprecated.');
365361
}
366362
}
367363

‎contributing/code/conventions.rst

Copy file name to clipboardExpand all lines: contributing/code/conventions.rst
+8-12Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -100,40 +100,38 @@ A feature is marked as deprecated by adding a ``@deprecated`` PHPDoc to
100100
relevant classes, methods, properties, ...::
101101

102102
/**
103-
* @deprecated since Symfony 2.8.
103+
* @deprecated since Symfony 5.1.
104104
*/
105105

106106
The deprecation message must indicate the version in which the feature was deprecated,
107107
and whenever possible, how it was replaced::
108108

109109
/**
110-
* @deprecated since Symfony 2.8, use Replacement instead.
110+
* @deprecated since Symfony 5.1, use Replacement instead.
111111
*/
112112

113113
When the replacement is in another namespace than the deprecated class, its FQCN must be used::
114114

115115
/**
116-
* @deprecated since Symfony 2.8, use A\B\Replacement instead.
116+
* @deprecated since Symfony 5.1, use A\B\Replacement instead.
117117
*/
118118

119119
A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration::
120120

121-
@trigger_error(sprintf('The "%s" class is deprecated since Symfony 2.8, use "%s" instead.', Deprecated::class, Replacement::class), E_USER_DEPRECATED);
121+
trigger_deprecation('vendor-name/package-name', '5.1', 'The "%s" class is deprecated since Symfony 5.1, use "%s" instead.', Deprecated::class, Replacement::class);
122122

123-
Without the `@-silencing operator`_, users would need to opt-out from deprecation
124-
notices. Silencing swaps this behavior and allows users to opt-in when they are
125-
ready to cope with them (by adding a custom error handler like the one used by
126-
the Web Debug Toolbar or by the PHPUnit bridge).
123+
The ``trigger_deprecation`` function internally use the php function :phpfunction:`assert`. This means you should use `zend.assertions` to disable deprecations in production.
127124

128-
When deprecating a whole class the ``trigger_error()`` call should be placed
125+
126+
When deprecating a whole class the ``trigger_deprecation()`` call should be placed
129127
between the namespace and the use declarations, like in this example from
130128
`ServiceRouterLoader`_::
131129

132130
namespace Symfony\Component\Routing\Loader\DependencyInjection;
133131

134132
use Symfony\Component\Routing\Loader\ContainerLoader;
135133

136-
@trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class), E_USER_DEPRECATED);
134+
trigger_deprecation('symfony/routing', '4.4', 'The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class);
137135

138136
/**
139137
* @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead.
@@ -182,5 +180,3 @@ of the impacted component::
182180
* Removed the `Deprecated` class, use `Replacement` instead.
183181

184182
This task is mandatory and must be done in the same pull request.
185-
186-
.. _`@-silencing operator`: https://www.php.net/manual/en/language.operators.errorcontrol.php

‎contributing/code/standards.rst

Copy file name to clipboardExpand all lines: contributing/code/standards.rst
+1-5Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ short example containing most features described below::
7272
*/
7373
public function someDeprecatedMethod()
7474
{
75-
@trigger_error(sprintf('The %s() method is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. Use Acme\Baz::someMethod() instead.', __METHOD__), E_USER_DEPRECATED);
75+
trigger_deprecation('vendor-name/package-name', '5.1', 'The %s() method is deprecated. Use Acme\Baz::someMethod() instead.', __METHOD__);
7676

7777
return Baz::someMethod();
7878
}
@@ -187,10 +187,6 @@ Structure
187187

188188
* Exception and error message strings must be concatenated using :phpfunction:`sprintf`;
189189

190-
* Calls to :phpfunction:`trigger_error` with type ``E_USER_DEPRECATED`` must be
191-
switched to opt-in via ``@`` operator.
192-
Read more at :ref:`contributing-code-conventions-deprecations`;
193-
194190
* Do not use ``else``, ``elseif``, ``break`` after ``if`` and ``case`` conditions
195191
which return or throw something;
196192

‎contributing/community/reviews.rst

Copy file name to clipboardExpand all lines: contributing/community/reviews.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
150150
* Does the code break backward compatibility? If yes, does the PR header say
151151
so?
152152
* Does the PR contain deprecations? If yes, does the PR header say so? Does
153-
the code contain ``trigger_error()`` statements for all deprecated
153+
the code contain ``trigger_deprecation()`` statements for all deprecated
154154
features?
155155
* Are all deprecations and backward compatibility breaks documented in the
156156
latest UPGRADE-X.X.md file? Do those explanations contain "Before"/"After"

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.