symfony · wouterj · Mar 21, 2020 · Mar 19, 2020
diff --git 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
@@ -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
diff --git 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
@@ -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"