Documented the ArgumentResolver along the ControllerResolver

Iltar van der Berg · Iltar van der Berg · commit bd2fb2629c62 · 2016-04-01T15:40:16.000+02:00
diff --git a/components/http_kernel/introduction.rst b/components/http_kernel/introduction.rst
@@ -85,11 +85,22 @@ is really simple and involves creating an
 :doc:`event dispatcher </components/event_dispatcher/introduction>` and a
 :ref:`controller resolver <component-http-kernel-resolve-controller>` (explained
 below). To complete your working kernel, you'll add more event listeners
-to the events discussed below::
+to the events discussed below
+
+.. caution::
+
+    As of 3.1 the :class:`Symfony\\Component\\Httpkernel\\HttpKernel` accepts a fourth argument, which
+    should be an instance of :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface`.
+    In 4.0 this argument will become mandatory and the :class:`Symfony\\Component\\Httpkernel\\HttpKernel`
+    will no longer be able to fall back to the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`.
+
+ .. code-block:: php
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpKernel\HttpKernel;
     use Symfony\Component\EventDispatcher\EventDispatcher;
+    use Symfony\Component\HttpFoundation\RequestStack;
+    use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
     use Symfony\Component\HttpKernel\Controller\ControllerResolver;
 
     // create the Request object
@@ -98,10 +109,16 @@ to the events discussed below::
     $dispatcher = new EventDispatcher();
     // ... add some event listeners
 
-    // create your controller resolver
-    $resolver = new ControllerResolver();
+    $valueResolvers = [
+        // ... add some implementations of ArgumentValueResolverInterface
+    ];
+
+    // create your controller and argument resolver
+    $controllerResolver = new ControllerResolver();
+    $argumentResolver = new ArgumentResolver($argumentMetadataFactory, $valueResolvers);
+
     // instantiate the kernel
-    $kernel = new HttpKernel($dispatcher, $resolver);
+    $kernel = new HttpKernel($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
 
     // actually execute the kernel, which turns the request into a response
     // by dispatching events, calling a controller, and returning the response
@@ -212,7 +229,19 @@ Your job is to create a class that implements the interface and fill in its
 two methods: ``getController`` and ``getArguments``. In fact, one default
 implementation already exists, which you can use directly or learn from:
 :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolver`.
-This implementation is explained more in the sidebar below::
+This implementation is explained more in the sidebar below
+
+
+.. caution::
+
+    The `getArguments()` method in the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`
+    and respective interface :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolverInterface`
+    are deprecated as of 3.1 and will be removed in 4.0. You can use the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which uses the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface` instead.
+
+
+.. code-block:: php
 
     namespace Symfony\Component\HttpKernel\Controller;
 
@@ -231,7 +260,7 @@ on the controller resolver. This method is passed the ``Request`` and is respons
 for somehow determining and returning a PHP callable (the controller) based
 on the request's information.
 
-The second method, :method:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface::getArguments`,
+The second method, :method:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface::getArguments`,
 will be called after another event - ``kernel.controller`` - is dispatched.
 
 .. sidebar:: Resolving the Controller in the Symfony Framework
@@ -310,11 +339,11 @@ on the event object that's passed to listeners on this event.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Next, ``HttpKernel::handle`` calls
-:method:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface::getArguments`.
+:method:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface::getArguments`.
 Remember that the controller returned in ``getController`` is a callable.
 The purpose of ``getArguments`` is to return the array of arguments that
 should be passed to that controller. Exactly how this is done is completely
-up to your design, though the built-in :class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolver`
+up to your design, though the built-in :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolver`
 is a good example.
 
 .. image:: /images/components/http_kernel/07-controller-arguments.png
@@ -326,7 +355,7 @@ of arguments that should be passed when executing that callable.
 .. sidebar:: Getting the Controller Arguments in the Symfony Framework
 
     Now that you know exactly what the controller callable (usually a method
-    inside a controller object) is, the ``ControllerResolver`` uses `reflection`_
+    inside a controller object) is, the ``ArgumentResolver`` uses `reflection`_
     on the callable to return an array of the *names* of each of the arguments.
     It then iterates over each of these arguments and uses the following tricks
     to determine which value should be passed for each argument:
@@ -339,7 +368,18 @@ of arguments that should be passed when executing that callable.
 
     b) If the argument in the controller is type-hinted with Symfony's
        :class:`Symfony\\Component\\HttpFoundation\\Request` object, then the
-       ``Request`` is passed in as the value.
+       ``Request`` is passed in as the value. If you have a custom class extending
+       the ``Request``, this is also accepted.
+
+    c) If the function or method argument is `variadic`_ and the ``Request``
+       ``attributes`` bag contains and array for that argument, they will all be
+       available through the `variadic`_ argument.
+
+    This functionality is provided by resolvers implementing the
+    :class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentValueResolverInterface`.
+    There are four implementations which provide the default behavior of Symfony but
+    customization is the key here. By implementing the ``ArgumentValueResolverInterface``
+    yourself and passing this to the ``ArgumentResolver``, you can extend this functionality.
 
 .. _component-http-kernel-calling-controller:
 
@@ -612,47 +652,64 @@ A full Working Example
 ----------------------
 
 When using the HttpKernel component, you're free to attach any listeners
-to the core events and use any controller resolver that implements the
-:class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface`.
-However, the HttpKernel component comes with some built-in listeners and
-a built-in ControllerResolver that can be used to create a working example::
+to the core events, use any controller resolver that implements the
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ControllerResolverInterface` and
+use any argument resolver that implements the
+:class:`Symfony\\Component\\HttpKernel\\Controller\\ArgumentResolverInterface`.
+However, the HttpKernel component comes with some built-in listeners, and everything
+else that can be used to create a working example::
+
+   use Symfony\Component\EventDispatcher\EventDispatcher;
+   use Symfony\Component\HttpFoundation\Request;
+   use Symfony\Component\HttpFoundation\RequestStack;
+   use Symfony\Component\HttpFoundation\Response;
+   use Symfony\Component\HttpKernel\Controller\ArgumentResolver;
+   use Symfony\Component\HttpKernel\Controller\ArgumentValueResolver\ArgumentFromAttributeResolver;
+   use Symfony\Component\HttpKernel\Controller\ArgumentValueResolver\DefaultArgumentValueResolver;
+   use Symfony\Component\HttpKernel\Controller\ArgumentValueResolver\RequestResolver;
+   use Symfony\Component\HttpKernel\Controller\ArgumentValueResolver\VariadicArgumentValueResolver;
+   use Symfony\Component\HttpKernel\Controller\ControllerResolver;
+   use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadataFactory;
+   use Symfony\Component\HttpKernel\EventListener\RouterListener;
+   use Symfony\Component\HttpKernel\HttpKernel;
+   use Symfony\Component\Routing\Matcher\UrlMatcher;
+   use Symfony\Component\Routing\RequestContext;
+   use Symfony\Component\Routing\Route;
+   use Symfony\Component\Routing\RouteCollection;
+
+   $routes = new RouteCollection();
+   $routes->add('hello', new Route('/hello/{name}', array(
+       '_controller' => function (Request $request) {
+           return new Response(
+               sprintf("Hello %s", $request->get('name'))
+           );
+       })
+   ));
+
+   $request = Request::createFromGlobals();
+
+   $matcher = new UrlMatcher($routes, new RequestContext());
+
+   $dispatcher = new EventDispatcher();
+   $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
+
+   $argumentValueResolvers = array(
+       new ArgumentFromAttributeResolver(),
+       new VariadicArgumentValueResolver(),
+       new RequestResolver(),
+       new DefaultArgumentValueResolver(),
+   );
+
+   $controllerResolver = new ControllerResolver();
+   $argumentResolver = new ArgumentResolver(new ArgumentMetadataFactory(), $argumentValueResolvers);
+
+   $kernel = new HttpKernel($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
+
+   $response = $kernel->handle($request);
+   $response->send();
+
+   $kernel->terminate($request, $response);
 
-    use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\HttpFoundation\RequestStack;
-    use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\HttpKernel\HttpKernel;
-    use Symfony\Component\EventDispatcher\EventDispatcher;
-    use Symfony\Component\HttpKernel\Controller\ControllerResolver;
-    use Symfony\Component\HttpKernel\EventListener\RouterListener;
-    use Symfony\Component\Routing\RouteCollection;
-    use Symfony\Component\Routing\Route;
-    use Symfony\Component\Routing\Matcher\UrlMatcher;
-    use Symfony\Component\Routing\RequestContext;
-
-    $routes = new RouteCollection();
-    $routes->add('hello', new Route('/hello/{name}', array(
-            '_controller' => function (Request $request) {
-                return new Response(
-                    sprintf("Hello %s", $request->get('name'))
-                );
-            }
-        )
-    ));
-
-    $request = Request::createFromGlobals();
-
-    $matcher = new UrlMatcher($routes, new RequestContext());
-
-    $dispatcher = new EventDispatcher();
-    $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
-
-    $resolver = new ControllerResolver();
-    $kernel = new HttpKernel($dispatcher, $resolver);
-
-    $response = $kernel->handle($request);
-    $response->send();
-
-    $kernel->terminate($request, $response);
 
 .. _http-kernel-sub-requests:
 
@@ -716,3 +773,4 @@ look like this::
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
 .. _`EmailSenderListener`: https://github.com/symfony/swiftmailer-bundle/blob/master/EventListener/EmailSenderListener.php
+.. _variadic: http://php.net/manual/en/functions.arguments.php
diff --git a/create_framework/http_kernel_controller_resolver.rst b/create_framework/http_kernel_controller_resolver.rst
@@ -43,10 +43,20 @@ component:
 
     $ composer require symfony/http-kernel
 
-The HttpKernel component has many interesting features, but the one we need
-right now is the *controller resolver*. A controller resolver knows how to
-determine the controller to execute and the arguments to pass to it, based on
-a Request object. All controller resolvers implement the following interface::
+The HttpKernel component has many interesting features, but the ones we need
+right now are the *controller resolver* and *argument resolver*. A controller resolver knows how to
+determine the controller to execute and the argument resolver determines the arguments to pass to it,
+based on a Request object. All controller resolvers implement the following interface
+
+.. caution::
+
+    The `getArguments()` method in the :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolver`
+    and respective interface :class:`Symfony\\Component\\Httpkernel\\Controller\\ControllerResolverInterface`
+    are deprecated as of 3.1 and will be removed in 4.0. You can use the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolver` which uses the
+    :class:`Symfony\\Component\\Httpkernel\\Controller\\ArgumentResolverInterface` instead.
+
+.. code-block:: php
 
     namespace Symfony\Component\HttpKernel\Controller;
 
@@ -58,6 +68,12 @@ a Request object. All controller resolvers implement the following interface::
         function getArguments(Request $request, $controller);
     }
 
+    // ...
+    interface ArgumentResolverInterface
+    {
+        function getArguments(Request $request, $controller);
+    }
+
 The ``getController()`` method relies on the same convention as the one we
 have defined earlier: the ``_controller`` request attribute must contain the
 controller associated with the Request. Besides the built-in PHP callbacks,
@@ -74,10 +90,14 @@ resolver from HttpKernel::
 
     use Symfony\Component\HttpKernel;
 
-    $resolver = new HttpKernel\Controller\ControllerResolver();
+    $valueResolvers = [/* array of ArgumentValueResolverInterface implemetations */];
+    $argumentMetadataFactory = new Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadataFactory();
+
+    $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+    $argumentResolver = new HttpKernel\Controller\ArgumentResolver($argumentMetadataFactory, $valueResolvers);
 
-    $controller = $resolver->getController($request);
-    $arguments = $resolver->getArguments($request, $controller);
+    $controller = $controllerResolver->getController($request);
+    $arguments = $argumentResolver->getArguments($request, $controller);
 
     $response = call_user_func_array($controller, $arguments);
 
@@ -140,14 +160,12 @@ method is not defined, an argument has no matching attribute, ...).
 
 .. note::
 
-    With the great flexibility of the default controller resolver, you might
-    wonder why someone would want to create another one (why would there be an
-    interface if not?). Two examples: in Symfony, ``getController()`` is
-    enhanced to support
-    :doc:`controllers as services </cookbook/controller/service>`; and in
-    `FrameworkExtraBundle`_, ``getArguments()`` is enhanced to support
-    parameter converters, where request attributes are converted to objects
-    automatically.
+    With the great flexibility of the default controller resolver and argument
+    resolver, you might wonder why someone would want to create another one
+    (why would there be an interface if not?). Two examples: in Symfony,
+    ``getController()`` is enhanced to support :doc:`controllers as services </cookbook/controller/service>`;
+    and ``getArguments()`` provides an extension point to alter or enhance
+    the resolving of arguments.
 
 Let's conclude with the new version of our framework::
 
@@ -156,6 +174,7 @@ Let's conclude with the new version of our framework::
 
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Controller\ArgumentValueResolver as ArgumentValueResolver;
     use Symfony\Component\Routing;
     use Symfony\Component\HttpKernel;
 
@@ -174,13 +193,27 @@ Let's conclude with the new version of our framework::
     $context = new Routing\RequestContext();
     $context->fromRequest($request);
     $matcher = new Routing\Matcher\UrlMatcher($routes, $context);
-    $resolver = new HttpKernel\Controller\ControllerResolver();
+
+    $valueResolvers = [
+        new ArgumentValueResolver\ArgumentFromAttributeResolver(),
+        new ArgumentValueResolver\VariadicArgumentValueResolver(),
+        new ArgumentValueResolver\RequestResolver(),
+        new ArgumentValueResolver\DefaultArgumentValueResolver(),
+    ];
+
+    $argumentMetadataFactory = new Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadataFactory();
+
+    $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+    $argumentResolver = new HttpKernel\Controller\ArgumentResolver($argumentMetadataFactory, $valueResolvers);
+
+    $controller = $controllerResolver->getController($request);
+    $arguments = $argumentResolver->getArguments($request, $controller);
 
     try {
         $request->attributes->add($matcher->match($request->getPathInfo()));
 
-        $controller = $resolver->getController($request);
-        $arguments = $resolver->getArguments($request, $controller);
+        $controller = $controllerResolver->getController($request);
+        $arguments = $argumentResolver->getArguments($request, $controller);
 
         $response = call_user_func_array($controller, $arguments);
     } catch (Routing\Exception\ResourceNotFoundException $e) {
@@ -192,7 +225,7 @@ Let's conclude with the new version of our framework::
     $response->send();
 
 Think about it once more: our framework is more robust and more flexible than
-ever and it still has less than 40 lines of code.
+ever and it still has less than 60 lines of code.
 
 .. _`reflection`: http://php.net/reflection
 .. _`FrameworkExtraBundle`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
