Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit fbf0adf

Browse filesBrowse files
wouterjwouterj
committed
Document DebugClassLoader type patch functionality
1 parent 17a7e85 commit fbf0adf
Copy full SHA for fbf0adf

File tree

1 file changed

+141
-10
lines changed
Filter options

1 file changed

+141
-10
lines changed

‎setup/upgrade_major.rst

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

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.