minor #17105 [DependencyInjection] Document proxifying interfaces for lazy services (tucksaun)

javiereguiluz · javiereguiluz · commit c35e9f5d1c82 · 2022-08-04T17:23:44.000+02:00
This PR was merged into the 4.4 branch. Discussion ---------- [DependencyInjection] Document proxifying interfaces for lazy services Symfony 4.2 introduced the possibility of lazy load services using final classes by proxyfying specific interfaces (symfony/symfony#20656), but this has not been documented yet. Targeting 4.4 because 4.4 is the oldest maintained branch, but should I target 4.2 as this was introduced in 4.2? Fix #10295 Commits ------- f86b976 [DI] Document proxifying interfaces for lazy services
diff --git a/service_container/lazy_services.rst b/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. 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``).
@@ -100,6 +101,81 @@ To check if your proxy works you can check the interface of the received object:
     over the ``lazy`` flag and directly instantiate the service as it would
     normally do.
 
+Interface Proxifying
+--------------------
+
+Under the hood, proxies generated to lazily load services inherit from the class
+used by the service. But sometimes this is not possible at all (`final`_ classes
+can not be extended for example) or not convenient.
+
+To workaround this limitation, you can configure a proxy to only implements
+specific interfaces.
+
+.. versionadded:: 4.2
+
+    Proxyfying interfaces was introduced in Symfony 4.2.
+
+.. 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 service using `final`_ classes. You can configure the proxy to
+implement multiple interfaces by repeating the "proxy" tag.
+
+.. tip::
+
+    This features can also act as a "safe guard". Because the proxy does not
+    extends the original class, only the methods defined by the interfaces can
+    be called, preventing to call implementation specific one. It also prevents
+    injecting the dependency at all if you type hinted a concrete implementation
+    instead of the interface.
+
 Additional Resources
 --------------------
 
