Merge branch '6.1' into 6.2

* 6.1:
  [DI] Document proxifying interfaces for lazy services

Author: javiereguiluz

service_container/lazy_services.rst

@@ -25,7 +25,8 @@ until you interact with the proxy in some way.
 
 .. caution::
 
-    Lazy services do not support `final`_ classes.
+    Lazy services do not support `final`_ classes, but you can use
+    `Interface Proxifying`_ to work around this limitation.
 
     In PHP versions prior to 8.0 lazy services do not support parameters with
     default values for built-in PHP classes (e.g. ``PDO``).
@@ -87,5 +88,76 @@ To check if your lazy service works you can check the interface of the received
     dump(class_implements($service));
     // the output should include "Symfony\Component\VarExporter\LazyGhostObjectInterface"
 
+Interface Proxifying
+--------------------
+
+Under the hood, proxies generated to lazily load services inherit from the class
+used by the service. However, sometimes this is not possible at all (e.g. because
+the class is `final`_ and can not be extended) or not convenient.
+
+To workaround this limitation, you can configure a proxy to only implement
+specific interfaces.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Twig\AppExtension:
+                lazy: 'Twig\Extension\ExtensionInterface'
+                # or a complete definition:
+                lazy: true
+                tags:
+                    - { name: 'proxy', interface: 'Twig\Extension\ExtensionInterface' }
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Twig\AppExtension" lazy="Twig\Extension\ExtensionInterface"/>
+                <!-- or a complete definition: -->
+                <service id="App\Twig\AppExtension" lazy="true">
+                    <tag name="proxy" interface="Twig\Extension\ExtensionInterface"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Twig\AppExtension;
+        use Twig\Extension\ExtensionInterface;
+
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            $services->set(AppExtension::class)
+                ->lazy()
+                ->tag('proxy', ['interface' => ExtensionInterface::class])
+            ;
+        };
+
+The virtual `proxy`_ injected into other services will only implement the
+specified interfaces and will not extend the original service class, allowing to
+lazy load services using `final`_ classes. You can configure the proxy to
+implement multiple interfaces by adding new "proxy" tags.
+
+.. tip::
+
+    This feature can also act as a safe guard: given that the proxy does not
+    extend the original class, only the methods defined by the interface can
+    be called, preventing to call implementation specific methods. It also
+    prevents injecting the dependency at all if you type-hinted a concrete
+    implementation instead of the interface.
+
 .. _`ghost object`: https://en.wikipedia.org/wiki/Lazy_loading#Ghost
 .. _`final`: https://www.php.net/manual/en/language.oop5.final.php