Document DebugClassLoader type patch functionality

Author: wouterj

setup/upgrade_major.rst

@@ -1,7 +1,7 @@
 .. index::
     single: Upgrading; Major Version
 
-Upgrading a Major Version (e.g. 4.4.0 to 5.0.0)
+Upgrading a Major Version (e.g. 5.4.0 to 6.0.0)
 ===============================================
 
 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,
 classes, etc) code still works, but is marked as *deprecated*, indicating that
 it will be removed/changed in the future and that you should stop using it.
 
-When the major version is released (e.g. 5.0.0), all deprecated features and
+When the major version is released (e.g. 6.0.0), all deprecated features and
 functionality are removed. So, as long as you've updated your code to stop
 using these deprecated features in the last version before the major (e.g.
 ``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:
 Once you fixed them all, the command ends with ``0`` (success) and you're
 done!
 
+.. caution::
+
+    You will probably see many deprecations about incompatible native
+    return types. See :ref:`Add Native Return Types <upgrading-native-return-types>`
+    for guidance in fixing these deprecations.
+
 .. sidebar:: Using the Weak Deprecations Mode
 
     Sometimes, you can't fix all deprecations (e.g. something was deprecated
@@ -135,12 +141,12 @@ starting with ``symfony/`` to the new major version:
           "...": "...",
 
           "require": {
-    -         "symfony/cache": "4.4.*",
-    +         "symfony/cache": "5.0.*",
-    -         "symfony/config": "4.4.*",
-    +         "symfony/config": "5.0.*",
-    -         "symfony/console": "4.4.*",
-    +         "symfony/console": "5.0.*",
+    -         "symfony/cache": "5.4.*",
+    +         "symfony/cache": "6.0.*",
+    -         "symfony/config": "5.4.*",
+    +         "symfony/config": "6.0.*",
+    -         "symfony/console": "5.4.*",
+    +         "symfony/console": "6.0.*",
               "...": "...",
 
               "...": "A few libraries starting with
@@ -154,15 +160,15 @@ starting with ``symfony/`` to the new major version:
 
 At the bottom of your ``composer.json`` file, in the ``extra`` block you can
 find a data setting for the Symfony version. Make sure to also upgrade
-this one. For instance, update it to ``5.0.*`` to upgrade to Symfony 5.0:
+this one. For instance, update it to ``6.0.*`` to upgrade to Symfony 6.0:
 
 .. code-block:: diff
 
       "extra": {
           "symfony": {
               "allow-contrib": false,
     -       "require": "4.4.*"
-    +       "require": "5.0.*"
+    +       "require": "6.0.*"
           }
       }
 
@@ -186,3 +192,89 @@ Next, use Composer to download new versions of the libraries:
 In some rare situations, the next major version *may* contain backwards-compatibility
 breaks. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
 included in the Symfony repository for any BC break that you need to be aware of.
+
+.. _upgrading-native-return-types:
+
+Upgrading to Symfony 6: Add Native Return Types
+-----------------------------------------------
+
+.. versionadded:: 5.4
+
+    The return type checking and fixing features were introduced in Symfony 5.4.
+
+Symfony 6 will come with native PHP return types to (almost all) methods.
+It is important to add the native PHP return types to your classes first.
+Otherwise, you will get incompatible declaration errors when upgrading to
+Symfony 6.0.
+
+When debug mode is enabled (typically in the dev and test environment),
+Symfony will trigger deprecations for every incompatible method
+declaration. For instance, the ``UserInterface::getRoles()`` method will
+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
+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.
+
+``php``
+    The target version of PHP - e.g. ``7.1`` doesn't generate "object"
+    types (which were introduced in 7.2). This defaults to the PHP version
+    used when running the script.
+
+``deprecations``
+    Set to ``0`` to disable deprecations. Otherwise, a deprecation notice
+    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::
+
+    <?php
+    // bin/fix-types.php
+
+    // required when using the PhpUnitBridge without "phpunit/phpunit"
+    require __DIR__.'/../vendor/bin/.phpunit/phpunit/vendor/autoload.php';
+
+    $loader = require __DIR__.'/../vendor/autoload.php';
+
+    // enable Symfony's class loader
+    Symfony\Component\ErrorHandler\DebugClassLoader::enable();
+
+    foreach ($loader->getClassMap() as $class => $file) {
+        // don't fix classes in the "vendor/" directory
+        if (str_contains(realpath($file), '/vendor/')) {
+            continue;
+        }
+
+        // loads the class
+        class_exists($class);
+    }
+
+    Symfony\Component\ErrorHandler\DebugClassLoader::checkClasses();
+
+Now, you can use the Composer autoloader to find all classes and use this
+script to fix them:
+
+.. code-block:: terminal
+
+    # "-o" is important! This forces Composer to find all classes
+    $ composer dump-autoload -o
+
+    # run your custom script to add all types
+    $ SYMFONY_PATCH_TYPE_DECLARATIONS=force=2 php bin/fix-types.php