Updates to DI config for 3.3

controller.rst

@@ -116,29 +116,15 @@ For more information on routing, see :doc:`/routing`.
 .. index::
    single: Controller; Base controller class
 
-.. _anchor-name:
-   :ref:`The Base Controller Classes & Services <the-base-controller-class-services>`
+.. _the-base-controller-class-services:
 
 The Base Controller Classes & Services
 --------------------------------------
 
 For convenience, Symfony comes with two optional base
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` and
 :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`
-classes.
-If you extend one or the other, this won't change anything about how your
-controller works, but you'll get access to a number of **helper methods**.
-
-The base ``Controller`` also allows you to access the **service container** (see :ref:`controller-accessing-services`): an
-array-like object that gives you access to every useful object in the
-system. These useful objects are called **services**, and Symfony ships
-with a service object that can render Twig templates, another that can
-log messages and many more.
-
-On the other hand, the ``AbstractController`` prevents you from accessing the
-**service container**. When you need an external dependency, this forces you to
-write a code more robust as you have to explicitly define your dependencies by
-using :doc:`the controller as a service </controller/service>`.
+classes. You can extend either to get access to a number of `helper methods`_.
 
 Add the ``use`` statement atop the ``Controller`` class and then modify
 ``LuckyController`` to extend it::
@@ -153,11 +139,18 @@ Add the ``use`` statement atop the ``Controller`` class and then modify
         // ...
     }
 
-Helper methods are just shortcuts to using core Symfony functionality
-that's available to you with or without the use of the base
-controller classes. A great way to see the core functionality in
-action is to look in the
-:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
+That's it! You now have access to methods like :ref:`$this->render() <controller-rendering-templates>`
+and many others that you'll learn about next.
+
+.. tip::
+
+    You can extend either ``Controller`` or ``AbstractController``. The difference
+    is that when you extend ``AbstractController``, you can't access services directly
+    via ``$this->get()`` or ``$this->container->get()``. This forces you to write
+    more robust code to access services, but if you're not use, use ``Controller``.
+
+.. versionadded:: 3.3
+    The ``AbstractController`` class was added in Symfony 3.3.
 
 .. index::
    single: Controller; Redirecting
@@ -244,41 +237,136 @@ The Symfony templating system and Twig are explained more in the
 
 .. _controller-accessing-services:
 
-Accessing other Services
-~~~~~~~~~~~~~~~~~~~~~~~~
+Fetching Services as Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Symfony comes packed with a lot of useful objects, called *services*. These
-are used for rendering templates, sending emails, querying the database and
-any other "work" you can think of. When you install a new bundle, it probably
-brings in even *more* services.
+.. versionadded:: 3.3
+    The ability to type-hint an argument in order to receive a service was added
+    in Symfony 3.3.
 
-When extending the base ``Controller`` class, you can access any Symfony service
-via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get`
-method. Here are several common services you might need::
+Symfony comes *packed* with a lot of useful objects, called :doc:`services </service_container>`.
+These are used for rendering templates, sending emails, querying the database and
+any other "work" you can think of.
 
-    $templating = $this->get('templating');
+If you need a service, just type-hint an argument with its class (or interface) name.
+Symfony will automatically pass you the service you need::
 
-    $router = $this->get('router');
+    use Psr\Log\LoggerInterface
+    // ...
 
-    $mailer = $this->get('mailer');
+    /**
+     * @Route("/lucky/number/{max}")
+     */
+    public function numberAction($max, LoggerInterface $logger)
+    {
+        $logger->info('We are logging!');
+        // ...
+    }
 
-What other services exist? To list all services, use the ``debug:container``
-console command:
+Awesome!
+
+What other services exist? Each page of the documentation will reveal more and more
+services you can use. To list *all* services, use the ``debug:container`` console
+command:
 
 .. code-block:: terminal
 
     $ php bin/console debug:container
 
-For more information, see the :doc:`/service_container` article.
+If need to control the *exact* value of an argument, you can override your controller's
+service config:
 
-.. tip::
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            # ...
+
+            # explicitly configure the service
+            AppBundle\Controller\LuckyController:
+                public: true
+                tags:
+                    # add multiple tags to controller multiple args
+                    - name: controller.service_arguments
+                      action: numberAction
+                      argument: logger
+                      # pass this specific service id
+                      id: monolog.logger.doctrine
+
+    .. code-block:: xml
+
+        <!-- app/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
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <!-- ... -->
+
+                <!-- Explicitly configure the service -->
+                <service id="AppBundle\Controller\LuckyController" public="true">
+                    <tag
+                        name="controller.service_arguments"
+                        action="numberAction"
+                        argument="logger"
+                        id="monolog.logger.doctrine"
+                    />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\Controller\LuckyController;
+
+        $container->register(LuckyController::class)
+            ->setPublic(true)
+            ->addTag('controller.service_arguments', [
+                'action' => 'numberAction',
+                'argument' => 'logger',
+                'id' => 'monolog.logger.doctrine',
+            ])
+        ;
+
+For more information about services, see the :doc:`/service_container` article.
+
+.. note::
+    If this isn't working, make sure your controller is registered as a service,
+    :ref:`autoconfigured <services-autoconfigure>` and extends either
+    :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` or
+    :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`. Or,
+    you can tag your service manually with ``controller.service_arguments``.
 
-    To get a :ref:`container configuration parameter <config-parameter-intro>`,
-    use the
-    :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getParameter`
-    method::
+.. _accessing-other-services:
+.. _controller-access-services-directly:
 
-        $from = $this->getParameter('app.mailer.from');
+Accessing the Container Directly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If extending the base ``Controller`` class, you can access any Symfony service
+via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get`
+method. Here are several common services you might need::
+
+    $templating = $this->get('templating');
+
+    $router = $this->get('router');
+
+    $mailer = $this->get('mailer');
+
+    // you can also fetch parameters
+    $someParameter = $this->getParameter('some_parameter');
+
+If you receive an eror like:
+
+    You have requested a non-existent service "my_service_id"
+
+Check to make sure the service exists (use :ref:`debug:container <container-debug-container>`)
+and that it's :ref:`public <container-public>`.
 
 .. index::
    single: Controller; Managing errors
@@ -355,7 +443,6 @@ Symfony provides a nice session object that you can use to store information
 about the user between requests. By default, Symfony stores the attributes in a
 cookie by using native PHP sessions.
 
-
 .. versionadded:: 3.3
     The ability to request a ``Session`` instance in controllers was introduced
     in Symfony 3.3.
@@ -418,20 +505,6 @@ For example, imagine you're processing a :doc:`form </forms>` submission::
         return $this->render(...);
     }
 
-.. tip::
-
-    As a developer, you might prefer not to extend the ``Controller``. To
-    use the flash message functionality, you can request the flash bag from
-    the :class:`Symfony\\Component\\HttpFoundation\\Session\\Session`::
-
-        use Symfony\Component\HttpFoundation\Session\Session;
-
-        public function indexAction(Session $session)
-        {
-            // getFlashBag is not available in the SessionInterface and requires the Session
-            $flashBag = $session->getFlashBag();
-        }
-
 After processing the request, the controller sets a flash message in the session
 and then redirects. The message key (``notice`` in this example) can be anything:
 you'll use this key to retrieve the message.
@@ -636,12 +709,7 @@ and it's a PHP function where you can do anything in order to return the
 final ``Response`` object that will be returned to the user.
 
 To make life easier, you'll probably extend the base ``Controller`` class because
-this gives two things:
-
-A) Shortcut methods (like ``render()`` and ``redirectToRoute()``);
-
-B) Access to *all* of the useful objects (services) in the system via the
-   :ref:`get() <controller-accessing-services>` method.
+this gives access to shortcut methods (like ``render()`` and ``redirectToRoute()``).
 
 In other articles, you'll learn how to use specific services from inside your controller
 that will help you persist and fetch objects from a database, process form submissions,
@@ -666,4 +734,5 @@ Learn more about Controllers
 
     controller/*
 
+.. _`helper methods`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/ControllerTrait.php
 .. _`unvalidated redirects security vulnerability`: https://www.owasp.org/index.php/Open_redirect

doctrine.rst

@@ -548,6 +548,7 @@ a controller, this is pretty easy. Add the following method to the
     // ...
     use AppBundle\Entity\Product;
     use Symfony\Component\HttpFoundation\Response;
+    use Doctrine\ORM\EntityManagerInterface;
 
     // ...
     public function createAction()
@@ -568,6 +569,12 @@ a controller, this is pretty easy. Add the following method to the
         return new Response('Saved new product with id '.$product->getId());
     }
 
+    // you can also receive the $em as an argument
+    public function editAction(EntityManagerInterface $em)
+    {
+        // ...
+    }
+
 .. note::
 
     If you're following along with this example, you'll need to create a

email.rst

@@ -100,7 +100,7 @@ The Swift Mailer library works by creating, configuring and then sending
 of the message and is accessible via the ``mailer`` service. Overall, sending
 an email is pretty straightforward::
 
-    public function indexAction($name)
+    public function indexAction($name, \Swift_Mailer $mailer)
     {
         $message = \Swift_Message::newInstance()
             ->setSubject('Hello Email')
@@ -125,7 +125,11 @@ an email is pretty straightforward::
             )
             */
         ;
-        $this->get('mailer')->send($message);
+
+        $mailer->send($message);
+
+        // or, you can also fetch the mailer service in this way
+        // $this->get('mailer')->send($message);
 
         return $this->render(...);
     }

logging.rst

@@ -10,9 +10,13 @@ Logging a Message
 To log a message, fetch the ``logger`` service from the container in
 your controller::
 
-    public function indexAction()
+    use Psr\Log\LoggerInterface;
+
+    public function indexAction(LoggerInterface $logger)
     {
-        $logger = $this->get('logger');
+        // alternative way of getting the logger
+        // $logger = $this->get('logger');
+
         $logger->info('I just got the logger');
         $logger->error('An error occurred');