8000 [Contracts/Deprecation] Provide a generic function and convention to … · symfony/symfony@f0f41cb · GitHub
[go: up one dir, main page]
Skip to content

Commit f0f41cb

Browse files
nicolas-grekasnicolas-grekas
committed
[Contracts/Deprecation] Provide a generic function and convention to trigger deprecation notices
1 parent f0fbdee commit f0f41cb

File tree

6 files changed

+113
-1
lines changed

6 files changed

+113
-1
lines changed

‎src/Symfony/Contracts/Deprecation/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
vendor/
2+
composer.lock
3+
phpunit.xml

‎src/Symfony/Contracts/Deprecation/LICENSE

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Copyright (c) 2020 Fabien Potencier
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to deal
5+
in the Software without restriction, including without limitation the rights
6+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
copies of the Software, and to permit persons to whom the Software is furnished
8+
to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19+
THE SOFTWARE.

‎src/Symfony/Contracts/Deprecation/README.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Symfony Deprecation Contracts
2+
=============================
3+
4+
A generic function and convention to trigger deprecation notices.
5+
6+
This package provides a single global function named `deprecated()`.
7+
Its purpose is to trigger deprecations in a way that can be silenced on production environments
8+
by using the `zend.assertions` ini setting and that can be caught during development to generate reports.
9+
10+
The function requires at least 3 arguments:
11+
- the name of the Composer package that is triggering the deprecation
12+
- the version of the package that introduced the deprecation
13+
- the message of the deprecation
14+
- more arguments can be provided: they will be inserted in the message using `printf()` formatting
15+
16+
Example:
17+
```php
18+
deprecated('symfony/blockchain', 8.9, 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin');
19+
```
20+
21+
This will generate the following message:
22+
`Since symfony/blockchain 8.9: Using "bitcoin" is deprecated, use "fabcoin" instead.`

‎src/Symfony/Contracts/Deprecation/composer.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "symfony/deprecation-contracts",
3+
"type": "library",
4+
"description": "A generic function and convention to trigger deprecation notices",
5+
"homepage": "https://symfony.com",
6+
"license": "MIT",
7+
"authors": [
8+
{
9+
"name": "Nicolas Grekas",
10+
"email": "p@tchwork.com"
11+
},
12+
{
13+
"name": "Symfony Community",
14+
"homepage": "https://symfony.com/contributors"
15+
}
16+
],
17+
"require": {
18+
"php": "^7.0"
19+
},
20+
"autoload": {
21+
"files": [
22+
"deprecated.php"
23+
]
24+
},
25+
"minimum-stability": "dev",
26+
"extra": {
27+
"branch-alias": {
28+
"dev-master": "2.1-dev"
29+
}
30+
}
31+
}

‎src/Symfony/Contracts/Deprecation/deprecated.php

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
/**
13+
* Triggers a deprecation.
14+
*
15+
* As recommended for prod, turn the "zend.assertions" ini setting to 0 or -1 to disable deprecation notices.
16+
* Alternatively, provide your own implementation of the function and list "symfony/deprecation-contracts"
17+
* in the "replace" section of your root composer.json if you need any custom behavior.
18+
*
19+
* The function doesn't use type hints to make it as fast as possible.
20+
*
21+
* @param string $package The name of the Composer package that is triggering the deprecation
22+
* @param string $version The version of the package that introduced the deprecation
23+
* @param string $message The message of the deprecation
24+
* @param scalar ...$args Values to insert in the message using printf() formatting
25+
*
26+
* @author Nicolas Grekas <p@tchwork.com>
27+
*/
28+
function deprecated($package, $version, $message, ...$args)
29+
{
30+
assert(@trigger_error(
31+
($package || $version ? "Since $package $version: " : '')
32+
.($args ? vsprintf($message, $args) : $message),
33+
E_USER_DEPRECATED
34+
));
35+
}

‎src/Symfony/Contracts/composer.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
},
2727
"replace": {
2828
"symfony/cache-contracts": "self.version",
29+
"symfony/deprecation-contracts": "self.version",
2930
"symfony/event-dispatcher-contracts": "self.version",
3031
"symfony/http-client-contracts": "self.version",
3132
"symfony/service-contracts": "self.version",
@@ -40,14 +41,15 @@
4041
},
4142
"autoload": {
4243
"psr-4": { "Symfony\\Contracts\\": "" },
44+
"file": [ "Deprecation/deprecated.php" ],
4345
"exclude-from-classmap": [
4446
"**/Tests/"
4547
]
4648
},
4749
"minimum-stability": "dev",
4850
"extra": {
4951
"branch-alias": {
50-
"dev-master": "2.0-dev"
52+
"dev-master": "2.1-dev"
5153
}
5254
}
5355
}

0 commit comments

Comments
 (0)
0