| 148 |
lars |
1 |
# Doctrine Deprecations
|
|
|
2 |
|
|
|
3 |
A small (side-effect free by default) layer on top of
|
|
|
4 |
`trigger_error(E_USER_DEPRECATED)` or PSR-3 logging.
|
|
|
5 |
|
|
|
6 |
- no side-effects by default, making it a perfect fit for libraries that don't know how the error handler works they operate under
|
|
|
7 |
- options to avoid having to rely on error handlers global state by using PSR-3 logging
|
|
|
8 |
- deduplicate deprecation messages to avoid excessive triggering and reduce overhead
|
|
|
9 |
|
|
|
10 |
We recommend to collect Deprecations using a PSR logger instead of relying on
|
|
|
11 |
the global error handler.
|
|
|
12 |
|
|
|
13 |
## Usage from consumer perspective:
|
|
|
14 |
|
|
|
15 |
Enable Doctrine deprecations to be sent to a PSR3 logger:
|
|
|
16 |
|
|
|
17 |
```php
|
|
|
18 |
\Doctrine\Deprecations\Deprecation::enableWithPsrLogger($logger);
|
|
|
19 |
```
|
|
|
20 |
|
|
|
21 |
Enable Doctrine deprecations to be sent as `@trigger_error($message, E_USER_DEPRECATED)`
|
|
|
22 |
messages.
|
|
|
23 |
|
|
|
24 |
```php
|
|
|
25 |
\Doctrine\Deprecations\Deprecation::enableWithTriggerError();
|
|
|
26 |
```
|
|
|
27 |
|
|
|
28 |
If you only want to enable deprecation tracking, without logging or calling `trigger_error` then call:
|
|
|
29 |
|
|
|
30 |
```php
|
|
|
31 |
\Doctrine\Deprecations\Deprecation::enableTrackingDeprecations();
|
|
|
32 |
```
|
|
|
33 |
|
|
|
34 |
Tracking is enabled with all three modes and provides access to all triggered
|
|
|
35 |
deprecations and their individual count:
|
|
|
36 |
|
|
|
37 |
```php
|
|
|
38 |
$deprecations = \Doctrine\Deprecations\Deprecation::getTriggeredDeprecations();
|
|
|
39 |
|
|
|
40 |
foreach ($deprecations as $identifier => $count) {
|
|
|
41 |
echo $identifier . " was triggered " . $count . " times\n";
|
|
|
42 |
}
|
|
|
43 |
```
|
|
|
44 |
|
|
|
45 |
### Suppressing Specific Deprecations
|
|
|
46 |
|
|
|
47 |
Disable triggering about specific deprecations:
|
|
|
48 |
|
|
|
49 |
```php
|
|
|
50 |
\Doctrine\Deprecations\Deprecation::ignoreDeprecations("https://link/to/deprecations-description-identifier");
|
|
|
51 |
```
|
|
|
52 |
|
|
|
53 |
Disable all deprecations from a package
|
|
|
54 |
|
|
|
55 |
```php
|
|
|
56 |
\Doctrine\Deprecations\Deprecation::ignorePackage("doctrine/orm");
|
|
|
57 |
```
|
|
|
58 |
|
|
|
59 |
### Other Operations
|
|
|
60 |
|
|
|
61 |
When used within PHPUnit or other tools that could collect multiple instances of the same deprecations
|
|
|
62 |
the deduplication can be disabled:
|
|
|
63 |
|
|
|
64 |
```php
|
|
|
65 |
\Doctrine\Deprecations\Deprecation::withoutDeduplication();
|
|
|
66 |
```
|
|
|
67 |
|
|
|
68 |
Disable deprecation tracking again:
|
|
|
69 |
|
|
|
70 |
```php
|
|
|
71 |
\Doctrine\Deprecations\Deprecation::disable();
|
|
|
72 |
```
|
|
|
73 |
|
|
|
74 |
## Usage from a library/producer perspective:
|
|
|
75 |
|
|
|
76 |
When you want to unconditionally trigger a deprecation even when called
|
|
|
77 |
from the library itself then the `trigger` method is the way to go:
|
|
|
78 |
|
|
|
79 |
```php
|
|
|
80 |
\Doctrine\Deprecations\Deprecation::trigger(
|
|
|
81 |
"doctrine/orm",
|
|
|
82 |
"https://link/to/deprecations-description",
|
|
|
83 |
"message"
|
|
|
84 |
);
|
|
|
85 |
```
|
|
|
86 |
|
|
|
87 |
If variable arguments are provided at the end, they are used with `sprintf` on
|
|
|
88 |
the message.
|
|
|
89 |
|
|
|
90 |
```php
|
|
|
91 |
\Doctrine\Deprecations\Deprecation::trigger(
|
|
|
92 |
"doctrine/orm",
|
|
|
93 |
"https://github.com/doctrine/orm/issue/1234",
|
|
|
94 |
"message %s %d",
|
|
|
95 |
"foo",
|
|
|
96 |
1234
|
|
|
97 |
);
|
|
|
98 |
```
|
|
|
99 |
|
|
|
100 |
When you want to trigger a deprecation only when it is called by a function
|
|
|
101 |
outside of the current package, but not trigger when the package itself is the cause,
|
|
|
102 |
then use:
|
|
|
103 |
|
|
|
104 |
```php
|
|
|
105 |
\Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
|
|
|
106 |
"doctrine/orm",
|
|
|
107 |
"https://link/to/deprecations-description",
|
|
|
108 |
"message"
|
|
|
109 |
);
|
|
|
110 |
```
|
|
|
111 |
|
|
|
112 |
Based on the issue link each deprecation message is only triggered once per
|
|
|
113 |
request.
|
|
|
114 |
|
|
|
115 |
A limited stacktrace is included in the deprecation message to find the
|
|
|
116 |
offending location.
|
|
|
117 |
|
|
|
118 |
Note: A producer/library should never call `Deprecation::enableWith` methods
|
|
|
119 |
and leave the decision how to handle deprecations to application and
|
|
|
120 |
frameworks.
|
|
|
121 |
|
|
|
122 |
## Usage in PHPUnit tests
|
|
|
123 |
|
|
|
124 |
There is a `VerifyDeprecations` trait that you can use to make assertions on
|
|
|
125 |
the occurrence of deprecations within a test.
|
|
|
126 |
|
|
|
127 |
```php
|
|
|
128 |
use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
|
|
|
129 |
|
|
|
130 |
class MyTest extends TestCase
|
|
|
131 |
{
|
|
|
132 |
use VerifyDeprecations;
|
|
|
133 |
|
|
|
134 |
public function testSomethingDeprecation()
|
|
|
135 |
{
|
|
|
136 |
$this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
|
|
|
137 |
|
|
|
138 |
triggerTheCodeWithDeprecation();
|
|
|
139 |
}
|
|
|
140 |
|
|
|
141 |
public function testSomethingDeprecationFixed()
|
|
|
142 |
{
|
|
|
143 |
$this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
|
|
|
144 |
|
|
|
145 |
triggerTheCodeWithoutDeprecation();
|
|
|
146 |
}
|
|
|
147 |
}
|
|
|
148 |
```
|
|
|
149 |
|
|
|
150 |
## What is a deprecation identifier?
|
|
|
151 |
|
|
|
152 |
An identifier for deprecations is just a link to any resource, most often a
|
|
|
153 |
Github Issue or Pull Request explaining the deprecation and potentially its
|
|
|
154 |
alternative.
|