From 0032b2a2893d3be592d4312b7b098fb9d71aca03 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Sat, 8 Feb 2020 13:26:33 +0100 Subject: [PATCH] [Contracts/Deprecation] don't use assert(), rename to trigger_deprecation() --- src/Symfony/Contracts/Deprecation/README.md | 12 ++++--- .../Contracts/Deprecation/composer.json | 4 +-- .../Contracts/Deprecation/deprecated.php | 35 ------------------- .../Contracts/Deprecation/function.php | 27 ++++++++++++++ src/Symfony/Contracts/composer.json | 2 +- 5 files changed, 38 insertions(+), 42 deletions(-) delete mode 100644 src/Symfony/Contracts/Deprecation/deprecated.php create mode 100644 src/Symfony/Contracts/Deprecation/function.php diff --git a/src/Symfony/Contracts/Deprecation/README.md b/src/Symfony/Contracts/Deprecation/README.md index d9738fe600..4957933a6c 100644 --- 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 index cb3929bcf1..de77c26ae8 100644 --- 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 deleted file mode 100644 index b2568a9e08..0000000000 --- a/src/Symfony/Contracts/Deprecation/deprecated.php +++ /dev/null @@ -1,35 +0,0 @@ - - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - -/** - * Triggers a deprecation. - * - * As recommended for prod, turn the "zend.assertions" ini setting to 0 or -1 to disable deprecation notices. - * Alternatively, provide your own implementation of the function and list "symfony/deprecation-contracts" - * in the "replace" section of your root composer.json if you need any custom behavior. - * - * The function doesn't use type hints to make it as fast as possible. - * - * @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 scalar ...$args Values to insert in the message using printf() formatting - * - * @author Nicolas Grekas - */ -function deprecated($package, $version, $message, ...$args) -{ - assert(@trigger_error( - ($package || $version ? "Since $package $version: " : '') - .($args ? vsprintf($message, $args) : $message), - E_USER_DEPRECATED - )); -} diff --git a/src/Symfony/Contracts/Deprecation/function.php b/src/Symfony/Contracts/Deprecation/function.php new file mode 100644 index 0000000000..0d3451f65e --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/function.php @@ -0,0 +1,27 @@ + + * + * 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 + */ + 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 index 36d5c7678a..5b3baaeb8f 100644 --- 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/" ]