Debian Codegraph @

vendor/doctrine/deprecations/README.md

raw
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 by setting the `DOCTRINE_DEPRECATIONS` environment variable to `trigger`.
23 Alternatively, call:
24
25 ```php
26 \Doctrine\Deprecations\Deprecation::enableWithTriggerError();
27 ```
28
29 If you only want to enable deprecation tracking, without logging or calling `trigger_error`
30 then set the `DOCTRINE_DEPRECATIONS` environment variable to `track`.
31 Alternatively, call:
32
33 ```php
34 \Doctrine\Deprecations\Deprecation::enableTrackingDeprecations();
35 ```
36
37 Tracking is enabled with all three modes and provides access to all triggered
38 deprecations and their individual count:
39
40 ```php
41 $deprecations = \Doctrine\Deprecations\Deprecation::getTriggeredDeprecations();
42
43 foreach ($deprecations as $identifier => $count) {
44 echo $identifier . " was triggered " . $count . " times\n";
45 }
46 ```
47
48 ### Suppressing Specific Deprecations
49
50 Disable triggering about specific deprecations:
51
52 ```php
53 \Doctrine\Deprecations\Deprecation::ignoreDeprecations("https://link/to/deprecations-description-identifier");
54 ```
55
56 Disable all deprecations from a package
57
58 ```php
59 \Doctrine\Deprecations\Deprecation::ignorePackage("doctrine/orm");
60 ```
61
62 ### Other Operations
63
64 When used within PHPUnit or other tools that could collect multiple instances of the same deprecations
65 the deduplication can be disabled:
66
67 ```php
68 \Doctrine\Deprecations\Deprecation::withoutDeduplication();
69 ```
70
71 Disable deprecation tracking again:
72
73 ```php
74 \Doctrine\Deprecations\Deprecation::disable();
75 ```
76
77 ## Usage from a library/producer perspective:
78
79 When you want to unconditionally trigger a deprecation even when called
80 from the library itself then the `trigger` method is the way to go:
81
82 ```php
83 \Doctrine\Deprecations\Deprecation::trigger(
84 "doctrine/orm",
85 "https://link/to/deprecations-description",
86 "message"
87 );
88 ```
89
90 If variable arguments are provided at the end, they are used with `sprintf` on
91 the message.
92
93 ```php
94 \Doctrine\Deprecations\Deprecation::trigger(
95 "doctrine/orm",
96 "https://github.com/doctrine/orm/issue/1234",
97 "message %s %d",
98 "foo",
99 1234
100 );
101 ```
102
103 When you want to trigger a deprecation only when it is called by a function
104 outside of the current package, but not trigger when the package itself is the cause,
105 then use:
106
107 ```php
108 \Doctrine\Deprecations\Deprecation::triggerIfCalledFromOutside(
109 "doctrine/orm",
110 "https://link/to/deprecations-description",
111 "message"
112 );
113 ```
114
115 Based on the issue link each deprecation message is only triggered once per
116 request.
117
118 A limited stacktrace is included in the deprecation message to find the
119 offending location.
120
121 Note: A producer/library should never call `Deprecation::enableWith` methods
122 and leave the decision how to handle deprecations to application and
123 frameworks.
124
125 ## Usage in PHPUnit tests
126
127 There is a `VerifyDeprecations` trait that you can use to make assertions on
128 the occurrence of deprecations within a test.
129
130 ```php
131 use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
132
133 class MyTest extends TestCase
134 {
135 use VerifyDeprecations;
136
137 public function testSomethingDeprecation()
138 {
139 $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
140
141 triggerTheCodeWithDeprecation();
142 }
143
144 public function testSomethingDeprecationFixed()
145 {
146 $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/orm/issue/1234');
147
148 triggerTheCodeWithoutDeprecation();
149 }
150 }
151 ```
152
153 ## Displaying deprecations after running a PHPUnit test suite
154
155 It is possible to integrate this library with PHPUnit to display all
156 deprecations triggered during the test suite execution.
157
158 ```xml
159 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
160 xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
161 colors="true"
162 bootstrap="vendor/autoload.php"
163 displayDetailsOnTestsThatTriggerDeprecations="true"
164 failOnDeprecation="true"
165 >
166 <!-- one attribute to display the deprecations, the other to fail the test suite -->
167
168 <php>
169 <!-- ensures native PHP deprecations are used -->
170 <server name="DOCTRINE_DEPRECATIONS" value="trigger"/>
171 </php>
172
173 <!-- ensures the @ operator in @trigger_error is ignored -->
174 <source ignoreSuppressionOfDeprecations="true">
175 <include>
176 <directory>src</directory>
177 </include>
178 </source>
179 </phpunit>
180 ```
181
182 Note that you can still trigger Deprecations in your code, provided you use the
183 `#[IgnoreDeprecations]` to ignore them for tests that call it.
184
185 At the moment, it is not possible to disable deduplication with an environment
186 variable, but you can use a bootstrap file to achieve that:
187
188 ```php
189 // tests/bootstrap.php
190 <?php
191
192 declare(strict_types=1);
193
194 require dirname(__DIR__) . '/vendor/autoload.php';
195
196 use Doctrine\Deprecations\Deprecation;
197
198 Deprecation::withoutDeduplication();
199 ```
200
201 Then, reference that file in your PHPUnit configuration:
202
203 ```xml
204 <phpunit …
205 bootstrap="tests/bootstrap.php"
206 …
207 >
208 …
209 </phpunit>
210 ```
211
212 ## What is a deprecation identifier?
213
214 An identifier for deprecations is just a link to any resource, most often a
215 Github Issue or Pull Request explaining the deprecation and potentially its
216 alternative.