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

src/Symfony/Contracts/Deprecation/.gitignore

@@ -0,0 +1,3 @@
+vendor/
+composer.lock
+phpunit.xml

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.

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.`

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"
+        }
+    }
+}

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
+    ));
+}

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"
         }
     }
 }