diff --git a/src/Symfony/Contracts/Deprecation/.gitignore b/src/Symfony/Contracts/Deprecation/.gitignore new file mode 100644 index 0000000000..c49a5d8df5 --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/.gitignore @@ -0,0 +1,3 @@ +vendor/ +composer.lock +phpunit.xml diff --git a/src/Symfony/Contracts/Deprecation/LICENSE b/src/Symfony/Contracts/Deprecation/LICENSE new file mode 100644 index 0000000000..5593b1d84f --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/LICENSE @@ -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. diff --git a/src/Symfony/Contracts/Deprecation/README.md b/src/Symfony/Contracts/Deprecation/README.md new file mode 100644 index 0000000000..d9738fe600 --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/README.md @@ -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.` diff --git a/src/Symfony/Contracts/Deprecation/composer.json b/src/Symfony/Contracts/Deprecation/composer.json new file mode 100644 index 0000000000..cb3929bcf1 --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/composer.json @@ -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" + } + } +} diff --git a/src/Symfony/Contracts/Deprecation/deprecated.php b/src/Symfony/Contracts/Deprecation/deprecated.php new file mode 100644 index 0000000000..b2568a9e08 --- /dev/null +++ b/src/Symfony/Contracts/Deprecation/deprecated.php @@ -0,0 +1,35 @@ + + * + * 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/composer.json b/src/Symfony/Contracts/composer.json index 6eccaa8598..b233c3da13 100644 --- a/src/Symfony/Contracts/composer.json +++ b/src/Symfony/Contracts/composer.json @@ -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" } } }