[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.
|
A generic function and convention to trigger deprecation notices.
|
||||||
|
|
||||||
This package provides a single global function named `deprecated()`.
|
This package provides a single global function named `trigger_deprecation()` that triggers silenced deprecation notices.
|
||||||
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.
|
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 function requires at least 3 arguments:
|
||||||
- the name of the Composer package that is triggering the deprecation
|
- the name of the Composer package that is triggering the deprecation
|
||||||
@ -15,8 +16,11 @@ The function requires at least 3 arguments:
|
|||||||
|
|
||||||
Example:
|
Example:
|
||||||
```php
|
```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:
|
This will generate the following message:
|
||||||
`Since symfony/blockchain 8.9: Using "bitcoin" is deprecated, use "fabcoin" instead.`
|
`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": {
|
"require": {
|
||||||
"php": "^7.0"
|
"php": "^7.1"
|
||||||
},
|
},
|
||||||
"autoload": {
|
"autoload": {
|
||||||
"files": [
|
"files": [
|
||||||
"deprecated.php"
|
"function.php"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
"minimum-stability": "dev",
|
"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": {
|
"autoload": {
|
||||||
"psr-4": { "Symfony\\Contracts\\": "" },
|
"psr-4": { "Symfony\\Contracts\\": "" },
|
||||||
"files": [ "Deprecation/deprecated.php" ],
|
"files": [ "Deprecation/function.php" ],
|
||||||
"exclude-from-classmap": [
|
"exclude-from-classmap": [
|
||||||
"**/Tests/"
|
"**/Tests/"
|
||||||
]
|
]
|
||||||
|
Reference in New Issue
Block a user