[Contracts/Deprecation] Provide a generic function and convention to …

…trigger deprecation notices
symfony · fabpot · Feb 5, 2020 · Jan 30, 2020 · Feb 5, 2020 · f0f41cbfc56a6b5bbe6a267ee86414b8b53a1c09
commit f0f41cbfc56a6b5bbe6a267ee86414b8b53a1c09
diff --git a/src/Symfony/Contracts/Deprecation/.gitignore 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
@@ -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
@@ -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
@@ -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
@@ -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
+    ));
+}
diff --git a/src/Symfony/Contracts/composer.json b/src/Symfony/Contracts/composer.json
@@ -26,6 +26,7 @@
     },
     "replace": {
         "symfony/cache-contracts": &qu
6D47
ot;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,14 +41,15 @@
     },
     "autoload": {
         "psr-4": { "Symfony\\Contracts\\": "" },
+        "file": [ "Deprecation/deprecated.php" ],
         "exclude-from-classmap": [
             "**/Tests/"
         ]
     },
     "minimum-stability": "dev",
     "extra": {
         "branch-alias": {
-            "dev-master": "2.0-dev"
+            "dev-master": "2.1-dev"
         }
     }
 }