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 89c9b45

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

File tree

1 file changed

+136
-10
lines changed
Filter options

1 file changed

+136
-10
lines changed

‎setup/upgrade_major.rst

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