[Contracts/Deprecation] don't use assert(), rename to trigger_deprecation()
This commit is contained in:
parent
916ff106c5
commit
0032b2a289
@ -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.
|
||||
|
@ -15,11 +15,11 @@
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"php": "^7.0"
|
||||
"php": "^7.1"
|
||||
},
|
||||
"autoload": {
|
||||
"files": [
|
||||
"deprecated.php"
|
||||
"function.php"
|
||||
]
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
|
@ -1,35 +0,0 @@
|
||||
<?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.
|
||||
*/
|
||||
|
||||
/**
|
||||
* 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 <p@tchwork.com>
|
||||
*/
|
||||
function deprecated($package, $version, $message, ...$args)
|
||||
{
|
||||
assert(@trigger_error(
|
||||
($package || $version ? "Since $package $version: " : '')
|
||||
.($args ? vsprintf($message, $args) : $message),
|
||||
E_USER_DEPRECATED
|
||||
));
|
||||
}
|
27
src/Symfony/Contracts/Deprecation/function.php
Normal file
27
src/Symfony/Contracts/Deprecation/function.php
Normal file
@ -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);
|
||||
}
|
||||
}
|
@ -41,7 +41,7 @@
|
||||
},
|
||||
"autoload": {
|
||||
"psr-4": { "Symfony\\Contracts\\": "" },
|
||||
"files": [ "Deprecation/deprecated.php" ],
|
||||
"files": [ "Deprecation/function.php" ],
|
||||
"exclude-from-classmap": [
|
||||
"**/Tests/"
|
||||
]
|
||||
|
Reference in New Issue
Block a user