feature symfony#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

Author: wouterj

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.');
         }
     }
 

contributing/code/conventions.rst

@@ -100,40 +100,38 @@ 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`_::
 
     namespace Symfony\Component\Routing\Loader\DependencyInjection;
 
     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

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;
 

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"