[Contracts/Deprecation] don't use assert(), rename to trigger_deprecation()

nicolas-grekas · nicolas-grekas · commit 0032b2a2893d · 2020-02-08T14:27:18.000+01:00
diff --git a/src/Symfony/Contracts/Deprecation/README.md b/src/Symfony/Contracts/Deprecation/README.md
@@ -3,9 +3,10 @@ Symfony Deprecation Contracts
 
 A generic function and convention to trigger deprecation notices.
 
-This package provides a single global function named `deprecated()`.
-Its purpose is to trigger deprecations in a way that can be silenced on production environments
-by using the `zend.assertions` ini setting and that can be caught during development to generate reports.
+This package provides a single global function named `trigger_deprecation()` that triggers silenced deprecation notices.
+
+By using a custom PHP error handler such as the one provided by the Symfony ErrorHandler component,
+the triggered deprecations can be caught and logged for later discovery, both on dev and prod environments.
 
 The function requires at least 3 arguments:
  - the name of the Composer package that is triggering the deprecation
@@ -15,8 +16,11 @@ The function requires at least 3 arguments:
 
 Example:
 ```php
-deprecated('symfony/blockchain', 8.9, 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin');
+trigger_deprecation('symfony/blockchain', '8.9', 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin');
 ```
 
 This will generate the following message:
 `Since symfony/blockchain 8.9: Using "bitcoin" is deprecated, use "fabcoin" instead.`
+
+While not necessarily recommended, the deprecation notices can be completely ignored by declaring an empty
+`function trigger_deprecation() {}` in your application.
diff --git a/src/Symfony/Contracts/Deprecation/composer.json b/src/Symfony/Contracts/Deprecation/composer.json
@@ -15,11 +15,11 @@
         }
     ],
     "require": {
-        "php": "^7.0"
+        "php": "^7.1"
     },
     "autoload": {
         "files": [
-            "deprecated.php"
+            "function.php"
         ]
     },
     "minimum-stability": "dev",
diff --git a/src/Symfony/Contracts/Deprecation/deprecated.php b/src/Symfony/Contracts/Deprecation/deprecated.php
diff --git a/src/Symfony/Contracts/Deprecation/function.php b/src/Symfony/Contracts/Deprecation/function.php
@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+if (!function_exists('trigger_deprecation')) {
+    /**
+     * Triggers a silenced deprecation notice.
+     *
+     * @param string $package The name of the Composer package that is triggering the deprecation
+     * @param string $version The version of the package that introduced the deprecation
+     * @param string $message The message of the deprecation
+     * @param mixed  ...$args Values to insert in the message using printf() formatting
+     *
+     * @author Nicolas Grekas <p@tchwork.com>
+     */
+    function trigger_deprecation(string $package, string $version, string $message, ...$args): void
+    {
+        @trigger_error(($package || $version ? "Since $package $version: " : '').($args ? vsprintf($message, $args) : $message), E_USER_DEPRECATED);
+    }
+}
diff --git a/src/Symfony/Contracts/composer.json b/src/Symfony/Contracts/composer.json
@@ -41,7 +41,7 @@
     },
     "autoload": {
         "psr-4": { "Symfony\\Contracts\\": "" },
-        "files": [ "Deprecation/deprecated.php" ],
+        "files": [ "Deprecation/function.php" ],
         "exclude-from-classmap": [
             "**/Tests/"
         ]

Original file line number	Diff line number	Diff line change
`@@ -15,11 +15,11 @@`
`15`	`15`	`}`
`16`	`16`	`],`
`17`	`17`	`"require": {`
`18`		`- "php": "^7.0"`
	`18`	`+ "php": "^7.1"`
`19`	`19`	`},`
`20`	`20`	`"autoload": {`
`21`	`21`	`"files": [`
`22`		`- "deprecated.php"`
	`22`	`+ "function.php"`
`23`	`23`	`]`
`24`	`24`	`},`
`25`	`25`	`"minimum-stability": "dev",`
Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,7 @@`
`41`	`41`	`},`
`42`	`42`	`"autoload": {`
`43`	`43`	`"psr-4": { "Symfony\\Contracts\\": "" },`
`44`		`- "files": [ "Deprecation/deprecated.php" ],`
	`44`	`+ "files": [ "Deprecation/function.php" ],`
`45`	`45`	`"exclude-from-classmap": [`
`46`	`46`	`"**/Tests/"`
`47`	`47`	`]`