8000 Document DebugClassLoader type patch functionality · symfony/symfony-docs@0b2af4d · GitHub
[go: up one dir, main page]
Skip to content

Commit 0b2af4d

Browse files
wouterjwouterj
committed
Document DebugClassLoader type patch functionality
1 parent 17a7e85 commit 0b2af4d

File tree

1 file changed

+141
-10
lines changed

1 file changed

+141
-10
lines changed

‎setup/upgrade_major.rst

Lines changed: 141 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. index::
22
single: Upgrading; Major Version
33

4-
Upgrading a Major Version (e.g. 4.4.0 to 5.0.0)
4+
Upgrading a Major Version (e.g. 5.4.0 to 6.0.0)
55
===============================================
66

77
Every two years, Symfony releases a new major version release (the first number
@@ -30,7 +30,7 @@ backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
3030
classes, etc) code still works, but is marked as *deprecated*, indicating that
3131
it will be removed/changed in the future and that you should stop using it.
3232

33-
When the major version is released (e.g. 5.0.0), all deprecated features and
33+
When the major version is released (e.g. 6.0.0), all deprecated features and
3434
functionality are removed. So, as long as you've updated your code to stop
3535
using these deprecated features in the last version before the major (e.g.
3636
``4.4.*``), you should be able to upgrade without a problem. That means that
@@ -95,6 +95,12 @@ Now, you can start fixing the notices:
9595
Once you fixed them all, the command ends with ``0`` (success) and you're
9696
done!
9797

98+
.. caution::
99+
100+
You will probably see many deprecations about incompatible native
101+
return types. See :ref:`Add Native Return Types <upgrading-native-return-types>`
102+
for guidance in fixing these deprecations.
103+
98104
.. sidebar:: Using the Weak Deprecations Mode
99105

100106
Sometimes, you can't fix all deprecations (e.g. something was deprecated
@@ -135,12 +141,12 @@ starting with ``symfony/`` to the new major version:
135141
"...": "...",
136142
137143
"require": {
138-
- "symfony/cache": "4.4.*",
139-
+ "symfony/cache": "5.0.*",
140-
- "symfony/config": "4.4.*",
141-
+ "symfony/config": "5.0.*",
142-
- "symfony/console": "4.4.*",
143-
+ "symfony/console": "5.0.*",
144+
- "symfony/cache": "5.4.*",
145+
+ "symfony/cache": "6.0.*",
146+
- "symfony/config": "5.4.*",
147+
+ "symfony/config": "6.0.*",
148+
- "symfony/console": "5.4.*",
149+
+ "symfony/console": "6.0.*",
144150
"...": "...",
145151
146152
"...": "A few libraries starting with
@@ -154,15 +160,15 @@ starting with ``symfony/`` to the new major version:
154160
155161
At the bottom of your ``composer.json`` file, in the ``extra`` block you can
156162
find a data setting for the Symfony version. Make sure to also upgrade
157-
this one. For instance, update it to ``5.0.*`` to upgrade to Symfony 5.0:
163+
this one. For instance, update it to ``6.0.*`` to upgrade to Symfony 6.0:
158164

159165
.. code-block:: diff
160166
161167
"extra": {
162168
"symfony": {
163169
"allow-contrib": false,
164170
- "require": "4.4.*"
165-
+ "require": "5.0.*"
171+
+ "require": "6.0.*"
166172
}
167173
}
168174
@@ -186,3 +192,128 @@ Next, use Composer to download new versions of the libraries:
186192
In some rare situations, the next major version *may* contain backwards-compatibility
187193
breaks. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
188194
included in the Symfony repository for any BC break that you need to be aware of.
195+
196+
.. _upgrading-native-return-types:
197+
198+
Upgrading to Symfony 6: Add Native Return Types
199+
-----------------------------------------------
200+
201+
.. versionadded:: 5.4
202+
203+
The return-type checking and fixing features were introduced in Symfony 5.4.
204+
205+
Symfony 6 will come with native PHP return types to (almost all) methods.
206+
In PHP, if the parent has a return type declaration, any class implementing
207+
or overriding the method must have the return type as well. However, you
208+
can add a return type before the parent adds one. This means that it is
209+
important to add the native PHP return types to your classes before
210+
upgrading to Symfony 6.0. Otherwise, you will get incompatible declaration
211+
errors.
212+
213+
When debug mode is enabled (typically in the dev and test environment),
214+
Symfony will trigger deprecations for every incompatible method
215+
declarations based on PHPDocs. For instance, the ``UserInterface::getRoles()``
216+
method will have an ``array`` return type in Symfony 6. In Symfony 5.4, you
217+
will get a deprecation notice about this and you must add the return type
218+
declaration to your ``getRoles()`` method.4.
219+
220+
To help with this, Symfony provides a script that can add these return
221+
types automatically for you. Make sure you installed the ``symfony/error-handler``
222+
component. When installed, generate a complete class map using Composer and
223+
run the script to iterate over the class map and fix any incompatible
224+
method:
225+
226+
.. code-block:: terminal
227+
228+
# Make sure "exclude-from-classmap" is not filled in your "composer.json". Then dump the autoloader:
229+
230+
# "-o" is important! This forces Composer to find all classes
231+
$ composer dump-autoload -o
232+
233+
# patch all incompatible method declarations
234+
$ ./vendor/bin/patch-type-declarations
235+
236+
.. tip::
237+
238+
This feature is not limited to Symfony packages. It will also help you
239+
add types and prepare for other dependencies in your project.
240+
241+
The behavior of this script can be modified using the ``SYMFONY_PATCH_TYPE_DECLARATIONS``
242+
env var. The value of this env var is url-encoded (e.g.
243+
``param1=value2&param2=value2``), the following parameters are available:
244+
245+
``force``
246+
Enables fixing return types, the value must be one of:
247+
248+
* ``2`` to add all possible return types (default, recommended for applications);
249+
* ``1`` to add return types only to tests, final, internal or private methods;
250+
* ``phpdoc`` to only add ``@return`` docblock annotations to the incompatible
251+
methods, or ``#[\ReturnTypeWillChange]`` if it's triggered by the PHP engine.
252+
253+
``php``
254+
The target version of PHP - e.g. ``7.1`` doesn't generate "object"
255+
types (which were introduced in 7.2). This defaults to the PHP version
256+
used when running the script.
257+
258+
``deprecations``
259+
Set to ``0`` to disable deprecations. Otherwise, a deprecation notice
260+
when a child class misses a return type while the parent declares an
261+
``@return`` annotation (defaults to ``1``).
262+
263+
If there are specific files that should be ignored, you can set the
264+
``SYMFONY_PATCH_TYPE_EXCLUDE`` env var to a regex. This regex will be
265+
matched to the full path to the class and each matching path will be
266+
ignored (e.g. ``SYMFONY_PATCH_TYPE_EXCLUDE="/tests\/Fixtures\//"``).
267+
Classes in the ``vendor/`` directory are always ignored.
268+
269+
.. tip::
270+
271+
The script does not care about code style. Run your code style fixer,
272+
or `PHP CS Fixer`_ with the ``phpdoc_trim_consecutive_blank_line_separation``,
273+
``no_superfluous_phpdoc_tags`` and ``ordered_imports`` rules, after
274+
patching the types.
275+
276+
.. _patching-types-for-open-source-maintainers:
277+
278+
.. sidebar:: Patching Types for Open Source Maintainers
279+
280+
Open source bundles and packages need to be more cautious with adding
281+
return types, as adding a return type forces all users extending the
282+
class to add the return type as well. The recommended approach is to
283+
use a 2 step process:
284+
285+
1. First, create a minor release (i.e. without backwards compatibility
286+
breaks) where you add types that can be safely introduced and add
287+
``@return`` PHPDoc to all other methods:
288+
289+
.. code-block:: terminal
290+
291+
# Add type declarations to all internal, final, tests and private methods.
292+
# Update the "php" parameter to match your minimum required PHP version
293+
$ SYMFONY_DEPRECATIONS_HELPER="force=1&php=7.4" ./vendor/bin/patch-type-declarations
294+
295+
# Add PHPDoc to the leftover public and protected methods
296+
$ SYMFONY_DEPRECATIONS_HELPER="force=phpdoc&php=7.4" ./vendor/bin/patch-type-declarations
297+
298+
After running the scripts, check your classes and add more ``@return``
299+
PHPDoc where they are missing. The deprecations and patch script
300+
work purely based on the PHPDoc information. Users of this release
301+
will get deprecation notices telling them to add the missing return
302+
types from your package to their code.
303+
304+
If you didn't need any PHPDoc and all your method declarations are
305+
already compatible with Symfony, you can safely allow ``^6.0`` for
306+
the Symfony dependencies. Otherwise, you have to continue with (2).
307+
308+
2. Create a new major release (i.e. *with* backwards compatibility
309+
breaks) where you add types to all methods:
310+
311+
.. code-block:: terminal
312+
313+
# Update the "php" parameter to match your minimum required PHP version
314+
$ SYMFONY_DEPRECATIONS_HELPER="force=2&php=7.4" ./vendor/bin/patch-type-declarations
315+
316+
As this release adds type declarations, you can safely allow
317+
``^6.0`` for the Symfony dependencies.
318+
319+
.. _`PHP CS Fixer`: https://github.com/friendsofphp/php-cs-fixer

0 commit comments

Comments
 (0)
0