feature #35526 [Contracts/Deprecation] Provide a generic function and convention to trigger deprecation notices (nicolas-grekas)
This PR was merged into the 5.1-dev branch.
Discussion
----------
[Contracts/Deprecation] Provide a generic function and convention to trigger deprecation notices
| Q | A
| ------------- | ---
| Branch? | master
| Bug fix? | no
| New feature? | yes
| Deprecations? | no
| Tickets | -
| License | MIT
| Doc PR | -
This PR results from a discussion we had yesterday with @alcaeus, @beberlei and others at the Symfony UG meetup in Berlin (thanks SensioLabs for bringing me there).
It provides a generic function and convention to trigger deprecation notices, which could be a better alternative to the `@trigger_error(..., E_USER_DEPRECATED)` calls that we use currently.
This proposed package would provide a single global function named `deprecated()`.
Its purpose is to trigger deprecations in a way that can be silenced on production environment
by using the `zend.assertions` ini setting and that can be caught during development to generate reports.
The function requires at least 3 arguments:
- the name of the package that is triggering the deprecation
- the version of the package that introduced the deprecation
- the message of the deprecation
- more arguments can be provided: they will be inserted in the message using `printf()` formatting
Example:
```php
deprecated('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.`
Check #35550 to see how using this function could look like on Symfony itself.
Commits
-------
f0f41cbfc5
[Contracts/Deprecation] Provide a generic function and convention to trigger deprecation notices
This commit is contained in:
commit
8c596bce30
3
src/Symfony/Contracts/Deprecation/.gitignore
vendored
Normal file
3
src/Symfony/Contracts/Deprecation/.gitignore
vendored
Normal file
@ -0,0 +1,3 @@
|
||||
vendor/
|
||||
composer.lock
|
||||
phpunit.xml
|
19
src/Symfony/Contracts/Deprecation/LICENSE
Normal file
19
src/Symfony/Contracts/Deprecation/LICENSE
Normal file
@ -0,0 +1,19 @@
|
||||
Copyright (c) 2020 Fabien Potencier
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is furnished
|
||||
to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
22
src/Symfony/Contracts/Deprecation/README.md
Normal file
22
src/Symfony/Contracts/Deprecation/README.md
Normal file
@ -0,0 +1,22 @@
|
||||
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.
|
||||
|
||||
The function requires at least 3 arguments:
|
||||
- the name of the Composer package that is triggering the deprecation
|
||||
- the version of the package that introduced the deprecation
|
||||
- the message of the deprecation
|
||||
- more arguments can be provided: they will be inserted in the message using `printf()` formatting
|
||||
|
||||
Example:
|
||||
```php
|
||||
deprecated('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.`
|
31
src/Symfony/Contracts/Deprecation/composer.json
Normal file
31
src/Symfony/Contracts/Deprecation/composer.json
Normal file
@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "symfony/deprecation-contracts",
|
||||
"type": "library",
|
||||
"description": "A generic function and convention to trigger deprecation notices",
|
||||
"homepage": "https://symfony.com",
|
||||
"license": "MIT",
|
||||
"authors": [
|
||||
{
|
||||
"name": "Nicolas Grekas",
|
||||
"email": "p@tchwork.com"
|
||||
},
|
||||
{
|
||||
"name": "Symfony Community",
|
||||
"homepage": "https://symfony.com/contributors"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"php": "^7.0"
|
||||
},
|
||||
"autoload": {
|
||||
"files": [
|
||||
"deprecated.php"
|
||||
]
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-master": "2.1-dev"
|
||||
}
|
||||
}
|
||||
}
|
35
src/Symfony/Contracts/Deprecation/deprecated.php
Normal file
35
src/Symfony/Contracts/Deprecation/deprecated.php
Normal file
@ -0,0 +1,35 @@
|
||||
<?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
|
||||
));
|
||||
}
|
@ -26,6 +26,7 @@
|
||||
},
|
||||
"replace": {
|
||||
"symfony/cache-contracts": "self.version",
|
||||
"symfony/deprecation-contracts": "self.version",
|
||||
"symfony/event-dispatcher-contracts": "self.version",
|
||||
"symfony/http-client-contracts": "self.version",
|
||||
"symfony/service-contracts": "self.version",
|
||||
@ -40,6 +41,7 @@
|
||||
},
|
||||
"autoload": {
|
||||
"psr-4": { "Symfony\\Contracts\\": "" },
|
||||
"file": [ "Deprecation/deprecated.php" ],
|
||||
"exclude-from-classmap": [
|
||||
"**/Tests/"
|
||||
]
|
||||
@ -47,7 +49,7 @@
|
||||
"minimum-stability": "dev",
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-master": "2.0-dev"
|
||||
"dev-master": "2.1-dev"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
Reference in New Issue
Block a user