Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 55e2c5b

Browse files
fabpotfabpot
committed
feature #35648 [Contracts/Deprecation] don't use assert(), rename to trigger_deprecation() (nicolas-grekas)
This PR was merged into the 5.1-dev branch. Discussion ---------- [Contracts/Deprecation] don't use assert(), rename to trigger_deprecation() | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | no | Deprecations? | no | Tickets | - | License | MIT | Doc PR | - This PR is a follow up the discussion that happened in #35526. I applied all the suggestions I received so far on this previous PR so that we can discuss them all together. Here are the changes: - the most important change is to *not* use `assert()` anymore. This fixes the objection from @ostrolucky and @derrabus that deprecations and assert() should not be bound to each other. Instead, in order to still make the function a no-op when wanted, it is suggested that apps declare an empty function. This will be more flexible in practice I believe and keeps all the benefits we envisioned by using assert(); - as suggested by @fabpot, the function is renamed `trigger_deprecation()` instead of `deprecated()`. Because the implementation is now not conditional anymore (from the package pov, since assert() is not used), my arguments to keep the previous name don't stand as strong as before to me so I'm fine renaming. - type hints are added back (requiring PHP 7.1 to use `void`). As mentioned in the 1st point, ppl that really want deprecations to be no-ops will redeclare the function as empty, thus not using any types, thus reclaiming all the perf diff. And for ppl that do want to catch deprecations, the overhead of types is negligible compared to any processing of the deprecations themselves. WDYT? All points can be discussed separately if needed of course. I'm personally fine with merging the PR as is, with all 3 changes. Commits ------- 0032b2a [Contracts/Deprecation] don't use assert(), rename to trigger_deprecation()
2 parents 916ff10 + 0032b2a commit 55e2c5b

File tree

5 files changed

+38
-42
lines changed

5 files changed

+38
-42
lines changed

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

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@ Symfony Deprecation Contracts
33

44
A generic function and convention to trigger deprecation notices.
55

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

1011
The function requires at least 3 arguments:
1112
- the name of the Composer package that is triggering the deprecation
@@ -15,8 +16,11 @@ The function requires at least 3 arguments:
1516

1617
Example:
1718
```php
18-
deprecated('symfony/blockchain', 8.9, 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin');
19+
trigger_deprecation('symfony/blockchain', '8.9', 'Using "%s" is deprecated, use "%s" instead.', 'bitcoin', 'fabcoin');
1920
```
2021

2122
This will generate the following message:
2223
`Since symfony/blockchain 8.9: Using "bitcoin" is deprecated, use "fabcoin" instead.`
24+
25+
While not necessarily recommended, the deprecation notices can be completely ignored by declaring an empty
26+
`function trigger_deprecation() {}` in your application.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
}
1616
],
1717
"require": {
18-
"php": "^7.0"
18+
"php": "^7.1"
1919
},
2020
"autoload": {
2121
"files": [
22-
"deprecated.php"
22+
"function.php"
2323
]
2424
},
2525
"minimum-stability": "dev",

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

Lines changed: 0 additions & 35 deletions
This file was deleted.

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <[email protected]>
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 <[email protected]>
22+
*/
23+
function trigger_deprecation(string $package, string $version, string $message, ...$args): void
24+
{
25+
@trigger_error(($package || $version ? "Since $package $version: " : '').($args ? vsprintf($message, $args) : $message), E_USER_DEPRECATED);
26+
}
27+
}

‎src/Symfony/Contracts/composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
},
4242
"autoload": {
4343
"psr-4": { "Symfony\\Contracts\\": "" },
44-
"files": [ "Deprecation/deprecated.php" ],
44+
"files": [ "Deprecation/function.php" ],
4545
"exclude-from-classmap": [
4646
"**/Tests/"
4747
]

0 commit comments

Comments
 (0)