Documented the ArgumentResolver along the ControllerResolver

Author: Iltar van der Berg

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,12 @@ to the events discussed below::
     $dispatcher = new EventDispatcher();
     // ... add some event listeners
 
-    // create your controller resolver
-    $resolver = new ControllerResolver();
+    // create your controller and argument resolvers
+    $controllerResolver = new ControllerResolver();
+    $argumentResolver = new ArgumentResolver();
+
     // 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 +225,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 +256,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 +335,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 +351,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 +364,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 +648,52 @@ 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\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'))
-                );
-            }
-        )
-    ));
+   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\ControllerResolver;
+   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;
 
-    $request = Request::createFromGlobals();
+   $routes = new RouteCollection();
+   $routes->add('hello', new Route('/hello/{name}', array(
+       '_controller' => function (Request $request) {
+           return new Response(
+               sprintf("Hello %s", $request->get('name'))
+           );
+       })
+   ));
 
-    $matcher = new UrlMatcher($routes, new RequestContext());
+   $request = Request::createFromGlobals();
 
-    $dispatcher = new EventDispatcher();
-    $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
+   $matcher = new UrlMatcher($routes, new RequestContext());
 
-    $resolver = new ControllerResolver();
-    $kernel = new HttpKernel($dispatcher, $resolver);
+   $dispatcher = new EventDispatcher();
+   $dispatcher->addSubscriber(new RouterListener($matcher, new RequestStack()));
 
-    $response = $kernel->handle($request);
-    $response->send();
+   $controllerResolver = new ControllerResolver();
+   $argumentResolver = new ArgumentResolver();
+
+   $kernel = new HttpKernel($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
+
+   $response = $kernel->handle($request);
+   $response->send();
+
+   $kernel->terminate($request, $response);
 
-    $kernel->terminate($request, $response);
 
 .. _http-kernel-sub-requests:
 
@@ -716,3 +757,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

components/serializer.rst

@@ -296,7 +296,7 @@ You are now able to serialize only attributes in the groups you want::
     $serializer = new Serializer(array($normalizer));
 
     $data = $serializer->normalize($obj, null, array('groups' => array('group1')));
-    // $data = ['foo' => 'foo'];
+    // $data = array('foo' => 'foo');
 
     $obj2 = $serializer->denormalize(
         array('foo' => 'foo', 'bar' => 'bar'),

cookbook/deployment/fortrabbit.rst

@@ -20,13 +20,13 @@ Before getting started, you should have done a few things on the fortrabbit side
 Preparing your Application
 --------------------------
 
-You don't need to change any code to deploy a Symfony application to fortrabbit. 
+You don't need to change any code to deploy a Symfony application to fortrabbit.
 But it requires some minor tweaks to its configuration.
 
 Configure Logging
 ~~~~~~~~~~~~~~~~~
 
-Per default Symfony logs to a file. Modify the ``app/config/config_prod.yml`` file 
+Per default Symfony logs to a file. Modify the ``app/config/config_prod.yml`` file
 to redirect it to :phpfunction:`error_log`:
 
 .. configuration-block::
@@ -73,7 +73,7 @@ to redirect it to :phpfunction:`error_log`:
 Configuring Database Access & Session Handler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can use the fortrabbit App Secrets to attain your database credentials. 
+You can use the fortrabbit App Secrets to attain your database credentials.
 Create the file ``app/config/config_prod_secrets.php`` with the following
 contents::
 
@@ -98,7 +98,7 @@ contents::
     // check if the Memcache component is present
     if (isset($secrets['MEMCACHE'])) {
         $memcache = $secrets['MEMCACHE'];
-        $handlers = [];
+        $handlers = array();
 
         foreach (range(1, $memcache['COUNT']) as $num) {
             $handlers[] = $memcache['HOST'.$num].':'.$memcache['PORT'.$num];
@@ -175,19 +175,19 @@ Configuring the Environment in the Dashboard
 PHP Settings
 ~~~~~~~~~~~~
 
-The PHP version and enabled extensions are configuable under the PHP settings 
+The PHP version and enabled extensions are configuable under the PHP settings
 of your App within the fortrabbit Dashboard.
 
 Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~
 
-Set the ``SYMFONY_ENV`` environment variable to ``prod`` to make sure the right 
+Set the ``SYMFONY_ENV`` environment variable to ``prod`` to make sure the right
 config files get loaded. ENV vars are configuable in fortrabbit Dashboard as well.
 
 Document Root
 ~~~~~~~~~~~~~
 
-The document root is configuable for every custom domain you setup for your App. 
+The document root is configuable for every custom domain you setup for your App.
 The default is ``/htdocs``, but for Symfony you probably want to change it to
 ``/htdocs/web``. You also do so in the fortrabbit Dashboard under ``Domain`` settings.
 
@@ -197,8 +197,8 @@ Deploying to fortrabbit
 It is assumed that your codebase is under version-control with Git and dependencies
 are managed with Composer (locally).
 
-Every time you push to fortrabbit composer install runs before your code gets 
-deployed. To finetune the deployment behavior put a `fortrabbit.yml`_. deployment 
+Every time you push to fortrabbit composer install runs before your code gets
+deployed. To finetune the deployment behavior put a `fortrabbit.yml`_. deployment
 file (optional) in the project root.
 
 Add fortrabbit as a (additional) Git remote and add your configuration changes:
@@ -221,11 +221,11 @@ Commit and push
     Replace ``<your-app>`` with the name of your fortrabbit App.
 
 .. code-block:: bash
-    
+
    Commit received, starting build of branch master
 
    –––––––––––––––––––––––  ∙ƒ  –––––––––––––––––––––––
-   
+
    B U I L D
 
    Checksum:
@@ -244,7 +244,7 @@ Commit and push
    Installing dependencies (including require-dev) from lock file
    Nothing to install or update
    Generating autoload files
-  
+
    - - -
    172ms
 
@@ -271,11 +271,11 @@ Commit and push
 
 .. note::
 
-   The first ``git push`` takes much longer as all composer dependencies get 
-   downloaded. All subsequent deploys are done within seconds. 
+   The first ``git push`` takes much longer as all composer dependencies get
+   downloaded. All subsequent deploys are done within seconds.
 
-That's it! Your application is being deployed on fortrabbit. More information 
-about `database migrations and tunneling`_ can be found in the fortrabbit 
+That's it! Your application is being deployed on fortrabbit. More information
+about `database migrations and tunneling`_ can be found in the fortrabbit
 documentation.
 
 .. _`fortrabbit`: https://www.fortrabbit.com

create_framework/dependency_injection.rst

@@ -9,23 +9,26 @@ to it::
     // example.com/src/Simplex/Framework.php
     namespace Simplex;
 
+    use Symfony\Component\EventDispatcher\EventDispatcher;
     use Symfony\Component\Routing;
+    use Symfony\Component\HttpFoundation;
     use Symfony\Component\HttpKernel;
-    use Symfony\Component\EventDispatcher\EventDispatcher;
 
     class Framework extends HttpKernel\HttpKernel
     {
         public function __construct($routes)
         {
             $context = new Routing\RequestContext();
             $matcher = new Routing\Matcher\UrlMatcher($routes, $context);
-            $resolver = new HttpKernel\Controller\ControllerResolver();
+
+            $controllerResolver = new HttpKernel\Controller\ControllerResolver();
+            $argumentResolver = new HttpKernel\Controller\ArgumentResolver();
 
             $dispatcher = new EventDispatcher();
             $dispatcher->addSubscriber(new HttpKernel\EventListener\RouterListener($matcher));
             $dispatcher->addSubscriber(new HttpKernel\EventListener\ResponseListener('UTF-8'));
 
-            parent::__construct($dispatcher, $resolver);
+            parent::__construct($dispatcher, $controllerResolver, new RequestStack(), $argumentResolver);
         }
     }
 
@@ -101,7 +104,8 @@ Create a new file to host the dependency injection container configuration::
         ->setArguments(array($routes, new Reference('context')))
     ;
     $sc->register('request_stack', 'Symfony\Component\HttpFoundation\RequestStack');
-    $sc->register('resolver', 'Symfony\Component\HttpKernel\Controller\ControllerResolver');
+    $sc->register('controller_resolver', 'Symfony\Component\HttpKernel\Controller\ControllerResolver');
+    $sc->register('argument_resolver', 'Symfony\Component\HttpKernel\Controller\ArgumentResolver');
 
     $sc->register('listener.router', 'Symfony\Component\HttpKernel\EventListener\RouterListener')
         ->setArguments(array(new Reference('matcher'), new Reference('request_stack')))
@@ -118,7 +122,12 @@ Create a new file to host the dependency injection container configuration::
         ->addMethodCall('addSubscriber', array(new Reference('listener.exception')))
     ;
     $sc->register('framework', 'Simplex\Framework')
-        ->setArguments(array(new Reference('dispatcher'), new Reference('resolver')))
+        ->setArguments(array(
+            new Reference('dispatcher'),
+            new Reference('controller_resolver'),
+            new Reference('request_stack'),
+            new Reference('argument_resolver'),
+        ))
     ;
 
     return $sc;