From 6702c1e3c144a77378b498039bb929cf80906b71 Mon Sep 17 00:00:00 2001 From: Laurent VOULLEMIER Date: Thu, 19 Mar 2020 21:08:07 +0100 Subject: [PATCH] Use trigger_deprecation instead of @trigger_error --- components/phpunit_bridge.rst | 16 ++++++---------- contributing/code/conventions.rst | 20 ++++++++------------ contributing/code/standards.rst | 6 +----- contributing/community/reviews.rst | 2 +- 4 files changed, 16 insertions(+), 28 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 2af0ce1ae63..5c77c21ce65 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -163,13 +163,9 @@ Trigger Deprecation Notices Deprecation notices can be triggered by using:: - @trigger_error('Your deprecation message', E_USER_DEPRECATED); + trigger_deprecation('vendor-name/package-name', '5.1', 'Your deprecation message'); -Without the `@-silencing operator`_, users would need to opt-out from deprecation -notices. Silencing by default swaps this behavior and allows users to opt-in -when they are ready to cope with them (by adding a custom error handler like the -one provided by this bridge). When not silenced, deprecation notices will appear -in the **Unsilenced** section of the deprecation report. +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. Mark Tests as Legacy -------------------- @@ -354,14 +350,14 @@ times (order matters):: public function testDeprecatedCode() { // test some code that triggers the following deprecation: - // @trigger_error('This "Foo" method is deprecated.', E_USER_DEPRECATED); - $this->expectDeprecation('This "%s" method is deprecated'); + // trigger_deprecation('vendor-name/package-name', '5.1', 'This "Foo" method is deprecated.'); + $this->expectDeprecation('Since vendor-name/package-name 5.1: This "%s" method is deprecated'); // ... // test some code that triggers the following deprecation: - // @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED); - $this->expectDeprecation('The second argument of the "%s" method is deprecated.'); + // trigger_deprecation('vendor-name/package-name', '4.4', 'The second argument of the "Bar" method is deprecated.'); + $this->expectDeprecation('Since vendor-name/package-name 4.4: The second argument of the "%s" method is deprecated.'); } } diff --git a/contributing/code/conventions.rst b/contributing/code/conventions.rst index 1d50e40c649..1f517ccc6e9 100644 --- a/contributing/code/conventions.rst +++ b/contributing/code/conventions.rst @@ -100,32 +100,30 @@ A feature is marked as deprecated by adding a ``@deprecated`` PHPDoc to relevant classes, methods, properties, ...:: /** - * @deprecated since Symfony 2.8. + * @deprecated since Symfony 5.1. */ The deprecation message must indicate the version in which the feature was deprecated, and whenever possible, how it was replaced:: /** - * @deprecated since Symfony 2.8, use Replacement instead. + * @deprecated since Symfony 5.1, use Replacement instead. */ When the replacement is in another namespace than the deprecated class, its FQCN must be used:: /** - * @deprecated since Symfony 2.8, use A\B\Replacement instead. + * @deprecated since Symfony 5.1, use A\B\Replacement instead. */ A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration:: - @trigger_error(sprintf('The "%s" class is deprecated since Symfony 2.8, use "%s" instead.', Deprecated::class, Replacement::class), E_USER_DEPRECATED); + trigger_deprecation('vendor-name/package-name', '5.1', 'The "%s" class is deprecated since Symfony 5.1, use "%s" instead.', Deprecated::class, Replacement::class); -Without the `@-silencing operator`_, users would need to opt-out from deprecation -notices. Silencing swaps this behavior and allows users to opt-in when they are -ready to cope with them (by adding a custom error handler like the one used by -the Web Debug Toolbar or by the PHPUnit bridge). +The ``trigger_deprecation`` function internally use the php function :phpfunction:`assert`. This means you should use `zend.assertions` to disable deprecations in production. -When deprecating a whole class the ``trigger_error()`` call should be placed + +When deprecating a whole class the ``trigger_deprecation()`` call should be placed between the namespace and the use declarations, like in this example from `ServiceRouterLoader`_:: @@ -133,7 +131,7 @@ between the namespace and the use declarations, like in this example from use Symfony\Component\Routing\Loader\ContainerLoader; - @trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class), E_USER_DEPRECATED); + trigger_deprecation('symfony/routing', '4.4', 'The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class); /** * @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead. @@ -182,5 +180,3 @@ of the impacted component:: * Removed the `Deprecated` class, use `Replacement` instead. This task is mandatory and must be done in the same pull request. - -.. _`@-silencing operator`: https://www.php.net/manual/en/language.operators.errorcontrol.php diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 586a868aae2..3603faa474e 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -72,7 +72,7 @@ short example containing most features described below:: */ public function someDeprecatedMethod() { - @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); + trigger_deprecation('vendor-name/package-name', '5.1', 'The %s() method is deprecated. Use Acme\Baz::someMethod() instead.', __METHOD__); return Baz::someMethod(); } @@ -187,10 +187,6 @@ Structure * Exception and error message strings must be concatenated using :phpfunction:`sprintf`; -* Calls to :phpfunction:`trigger_error` with type ``E_USER_DEPRECATED`` must be - switched to opt-in via ``@`` operator. - Read more at :ref:`contributing-code-conventions-deprecations`; - * Do not use ``else``, ``elseif``, ``break`` after ``if`` and ``case`` conditions which return or throw something; diff --git a/contributing/community/reviews.rst b/contributing/community/reviews.rst index 14d8b71a28d..342ba431201 100644 --- a/contributing/community/reviews.rst +++ b/contributing/community/reviews.rst @@ -150,7 +150,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps: * Does the code break backward compatibility? If yes, does the PR header say so? * Does the PR contain deprecations? If yes, does the PR header say so? Does - the code contain ``trigger_error()`` statements for all deprecated + the code contain ``trigger_deprecation()`` statements for all deprecated features? * Are all deprecations and backward compatibility breaks documented in the latest UPGRADE-X.X.md file? Do those explanations contain "Before"/"After" pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy