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"