Update for potential new feature?

Author: wouterj

setup/upgrade_major.rst

@@ -214,21 +214,31 @@ have an ``array`` return type in Symfony 6. In order to be compatible, you
 must add the same return type to the ``getRoles()`` method while using
 Symfony 5.4.
 
-To help with this, Symfony provides a ``DebugClassLoader`` that can add
-these native return types automatically for you. It can be configured using
-the ``SYMFONY_PATCH_TYPE_DECLARATIONS`` env var. The value of this env var
-is url-encoded (e.g. ``param1=value2&param2=value2``), the following
+To help with this, Symfony provides a script that can add these native
+return types automatically for you in the ``symfony/error-handler``
+component. When installed, generate a complete class map using Composer
+and run the script to iterate over the class map and fix any incompatible
+method:
+
+.. code-block:: terminal
+
+    # "-o" is important! This forces Composer to find all classes
+    $ composer dump-autoload -o
+
+    # patch all incompatible method declarations
+    $ ./vendor/bin/patch-type-declarations
+
+The behavior of this script can be modified using the
+``SYMFONY_PATCH_TYPE_DECLARATIONS`` env var. The value of this env var is
+url-encoded (e.g. ``param1=value2&param2=value2``), the following
 parameters are available:
 
 ``force``
     Enables fixing return types, the value must be one of:
 
-    * ``2`` to add all possible return types (default, useful for applications)
-    * ``1`` to add return types only to tests/final/internal/private methods
-    * ``phpdoc`` to only add docblock annotations to the incompatible methods
-
-    If you're developing an application, you should set this to ``2``. The
-    other values are useful for open source maintainers.
+    * ``2`` to add all possible return types (default, recommended for applications);
+    * ``1`` to add return types only to tests, final, internal or private methods;
+    * ``phpdoc`` to only add docblock annotations to the incompatible methods.
 
 ``php``
     The target version of PHP - e.g. ``7.1`` doesn't generate "object"
@@ -240,41 +250,49 @@ parameters are available:
     when a child class misses a return type while the parent declares an
     ``@return`` annotation (defaults to ``1``).
 
-If you're developing an application, use
-``SYMFONY_PATCH_TYPE_DECLARATIONS=force=2``. Symfony will only fix classes
-that are autoloaded. You can create a custom script that makes sure all
-classes in your project are loaded and fixed::
+If there are specific files that should be ignored, you can set the
+``SYMFONY_PATCH_TYPE_EXCLUDE`` env var to a regex. This regex will be
+matched to the full path to the class and each matching path will be
+ignored. By default, this regex matches all classes in the ``vendor/``
+directory.
 
-    <?php
-    // bin/fix-types.php
+.. sidebar:: Patching Types for Open Source Maintainers
 
-    // required when using the PhpUnitBridge without "phpunit/phpunit"
-    require __DIR__.'/../vendor/bin/.phpunit/phpunit/vendor/autoload.php';
+    Open source bundles and packages need to be more cautious with adding
+    return types, as adding a return type forces all users extending the
+    class to add the return type as well. The recommended approach is to
+    use a 2 step process:
 
-    $loader = require __DIR__.'/../vendor/autoload.php';
+    1. First, create a minor release (i.e. without backwards compatibility
+       breaks) where you add types that can be safely introduced and add
+       ``@return`` PHPdoc to all other methods:
 
-    // enable Symfony's class loader
-    Symfony\Component\ErrorHandler\DebugClassLoader::enable();
+       .. code-block:: terminal
 
-    foreach ($loader->getClassMap() as $class => $file) {
-        // don't fix classes in the "vendor/" directory
-        if (str_contains(realpath($file), '/vendor/')) {
-            continue;
-        }
+           # Add type declarations to all internal, final, tests and private methods.
+           # Update the "php" parameter to match your minimum required PHP version
+           $ SYMFONY_DEPRECATIONS_HELPER="force=1&php=7.4" ./vendor/bin/patch-type-declarations
 
-        // loads the class
-        class_exists($class);
-    }
+           # Add PHPdoc to the leftover public and protected methods
+           $ SYMFONY_DEPRECATIONS_HELPER="force=phpdoc&php=7.4" ./vendor/bin/patch-type-declarations
 
-    Symfony\Component\ErrorHandler\DebugClassLoader::checkClasses();
+       After running the scripts, check your classes and add more ``@return``
+       PHPdoc where they are missing. The deprecations and patch script
+       work purely based on the PHPdoc information. Users of this release
+       will be warned to update their method declarations to add the
+       missing return types.
 
-Now, you can use the Composer autoloader to find all classes and use this
-script to fix them:
+       If you didn't need any PHPdoc and all your method declarations are
+       already compatible, you can safely allow ``^6.0`` for the Symfony
+       dependencies. Otherwise, you have to continue with (2).
 
-.. code-block:: terminal
+    2. Create a new major release (i.e. *with* backwards compatibility
+       breaks) where you add types to all methods:
 
-    # "-o" is important! This forces Composer to find all classes
-    $ composer dump-autoload -o
+       .. code-block:: terminal
+
+           # Update the "php" parameter to match your minimum required PHP version
+           $ SYMFONY_DEPRECATIONS_HELPER="force=2&php=7.4" ./vendor/bin/patch-type-declarations
 
-    # run your custom script to add all types
-    $ SYMFONY_PATCH_TYPE_DECLARATIONS=force=2 php bin/fix-types.php
+       As this release adds type declarations, you can safely allow
+       ``^6.0`` for the Symfony dependencies.