@@ -214,21 +214,31 @@ have an ``array`` return type in Symfony 6. In order to be compatible, you
214214must add the same return type to the ``getRoles() `` method while using
215215Symfony 5.4.
216216
217- To help with this, Symfony provides a ``DebugClassLoader `` that can add
218- these native return types automatically for you. It can be configured using
219- the ``SYMFONY_PATCH_TYPE_DECLARATIONS `` env var. The value of this env var
220- is url-encoded (e.g. ``param1=value2¶m2=value2 ``), the following
217+ To help with this, Symfony provides a script that can add these native
218+ return types automatically for you in the ``symfony/error-handler ``
219+ component. When installed, generate a complete class map using Composer
220+ and run the script to iterate over the class map and fix any incompatible
221+ 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+
232+ ``SYMFONY_PATCH_TYPE_DECLARATIONS `` env var. The value of this env var is
233+ url-encoded (e.g. ``param1=value2¶m2=value2 ``), the following
221234parameters are available:
222235
223236``force ``
224237 Enables fixing return types, the value must be one of:
225238
226- * ``2 `` to add all possible return types (default, useful for applications)
227- * ``1 `` to add return types only to tests/final/internal/private methods
228- * ``phpdoc `` to only add docblock annotations to the incompatible methods
229-
230- If you're developing an application, you should set this to ``2 ``. The
231- other values are useful for open source maintainers.
239+ * ``2 `` to add all possible return types (default, recommended for applications);
240+ * ``1 `` to add return types only to tests, final, internal or private methods;
241+ * ``phpdoc `` to only add docblock annotations to the incompatible methods.
232242
233243``php ``
234244 The target version of PHP - e.g. ``7.1 `` doesn't generate "object"
@@ -240,41 +250,49 @@ parameters are available:
240250 when a child class misses a return type while the parent declares an
241251 ``@return `` annotation (defaults to ``1 ``).
242252
243- If you're developing an application, use
244- ``SYMFONY_PATCH_TYPE_DECLARATIONS=force=2 ``. Symfony will only fix classes
245- that are autoloaded. You can create a custom script that makes sure all
246- classes in your project are loaded and fixed::
253+ If there are specific files that should be ignored, you can set the
254+ ``SYMFONY_PATCH_TYPE_EXCLUDE `` env var to a regex. This regex will be
255+ matched to the full path to the class and each matching path will be
256+ ignored. By default, this regex matches all classes in the ``vendor/ ``
257+ directory.
247258
248- <?php
249- // bin/fix-types.php
259+ ..sidebar ::Patching Types for Open Source Maintainers
250260
251- // required when using the PhpUnitBridge without "phpunit/phpunit"
252- require __DIR__.'/../vendor/bin/.phpunit/phpunit/vendor/autoload.php';
261+ Open source bundles and packages need to be more cautious with adding
262+ return types, as adding a return type forces all users extending the
263+ class to add the return type as well. The recommended approach is to
264+ use a 2 step process:
253265
254- $loader = require __DIR__.'/../vendor/autoload.php';
266+ 1. First, create a minor release (i.e. without backwards compatibility
267+ breaks) where you add types that can be safely introduced and add
268+ ``@return `` PHPdoc to all other methods:
255269
256- // enable Symfony's class loader
257- Symfony\Component\ErrorHandler\DebugClassLoader::enable();
270+ ..code-block ::terminal
258271
259- foreach ($loader->getClassMap() as $class => $file) {
260- // don't fix classes in the "vendor/" directory
261- if (str_contains(realpath($file), '/vendor/')) {
262- continue;
263- }
272+ # Add type declarations to all internal, final, tests and private methods.
273+ # Update the "php" parameter to match your minimum required PHP version
274+ $ SYMFONY_DEPRECATIONS_HELPER="force=1&php=7.4" ./vendor/bin/patch-type-declarations
264275
265- // loads the class
266- class_exists($class);
267- }
276+ # Add PHPdoc to the leftover public and protected methods
277+ $ SYMFONY_DEPRECATIONS_HELPER="force=phpdoc&php=7.4" ./vendor/bin/patch-type-declarations
268278
269- Symfony\Component\ErrorHandler\DebugClassLoader::checkClasses();
279+ @return ``
280+ PHPdoc where they are missing. The deprecations and patch script
281+ work purely based on the PHPdoc information. Users of this release
282+ will be warned to update their method declarations to add the
283+ missing return types.
270284
271- Now, you can use the Composer autoloader to find all classes and use this
272- script to fix them:
285+ If you didn't need any PHPdoc and all your method declarations are
286+ already compatible, you can safely allow ``^6.0 `` for the Symfony
287+ dependencies. Otherwise, you have to continue with (2).
273288
274- ..code-block ::terminal
289+ 2. Create a new major release (i.e. *with * backwards compatibility
290+ breaks) where you add types to all methods:
275291
276- # "-o" is important! This forces Composer to find all classes
277- $ composer dump-autoload -o
292+ ..code-block ::terminal
293+
294+ # Update the "php" parameter to match your minimum required PHP version
295+ $ SYMFONY_DEPRECATIONS_HELPER="force=2&php=7.4" ./vendor/bin/patch-type-declarations
278296
279- # run your custom script to add all types
280- $ SYMFONY_PATCH_TYPE_DECLARATIONS=force=2 php bin/fix-types.php
297+ As this release adds type declarations, you can safely allow
298+ `` ^6.0 `` for the Symfony dependencies.