├── CHANGELOG.md ├── LICENSE ├── README.md ├── composer.json └── function.php /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | CHANGELOG 2 | ========= 3 | 4 | The changelog is maintained for all Symfony contracts at the following URL: 5 | https://github.com/symfony/contracts/blob/main/CHANGELOG.md 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2020-present 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. 20 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 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 `trigger_deprecation()` that triggers silenced deprecation notices. 7 | 8 | By using a custom PHP error handler such as the one provided by the Symfony ErrorHandler component, 9 | the triggered deprecations can be caught and logged for later discovery, both on dev and prod environments. 10 | 11 | The function requires at least 3 arguments: 12 | - the name of the Composer package that is triggering the deprecation 13 | - the version of the package that introduced the deprecation 14 | - the message of the deprecation 15 | - more arguments can be provided: they will be inserted in the message using `printf()` formatting 16 | 17 | Example: 18 | ```php 19 | trigger_deprecation('symfony/blockchain', '8.9', 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin'); 20 | ``` 21 | 22 | This will generate the following message: 23 | `Since symfony/blockchain 8.9: Using "bitcoin" is deprecated, use "fabcoin" instead.` 24 | 25 | While not recommended, the deprecation notices can be completely ignored by declaring an empty 26 | `function trigger_deprecation() {}` in your application. 27 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 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": ">=8.1" 19 | }, 20 | "autoload": { 21 | "files": [ 22 | "function.php" 23 | ] 24 | }, 25 | "minimum-stability": "dev", 26 | "extra": { 27 | "branch-alias": { 28 | "dev-main": "3.6-dev" 29 | }, 30 | "thanks": { 31 | "name": "symfony/contracts", 32 | "url": "https://github.com/symfony/contracts" 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /function.php: -------------------------------------------------------------------------------- 1 | 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 | if (!function_exists('trigger_deprecation')) { 13 | /** 14 | * Triggers a silenced deprecation notice. 15 | * 16 | * @param string $package The name of the Composer package that is triggering the deprecation 17 | * @param string $version The version of the package that introduced the deprecation 18 | * @param string $message The message of the deprecation 19 | * @param mixed ...$args Values to insert in the message using printf() formatting 20 | * 21 | * @author Nicolas Grekas 22 | */ 23 | function trigger_deprecation(string $package, string $version, string $message, mixed ...$args): void 24 | { 25 | @trigger_error(($package || $version ? "Since $package $version: " : '').($args ? vsprintf($message, $args) : $message), \E_USER_DEPRECATED); 26 | } 27 | } 28 | --------------------------------------------------------------------------------