Tweaks after amazing review from @GuilhemN and @xabbuh

symfony · weaverryan · May 5, 2017 · Apr 15, 2017 · Apr 28, 2017 · Apr 28, 2017
commit 12c49444c8be79f3988875fd619f958a0ff85e07
diff --git a/controller.rst b/controller.rst
@@ -147,7 +147,8 @@ and many others that you'll learn about next.
     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``.
+    more robust code to access services. But if you *do* need direct access to the
+    container, using ``Controller`` is fine.
 
 .. versionadded:: 3.3
     The ``AbstractController`` class was added in Symfony 3.3.
@@ -238,19 +239,19 @@ The Symfony templating system and Twig are explained more in the
 .. _controller-accessing-services:
 .. _accessing-other-services:
 
-Fetching Services as Arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Fetching Services as Controller Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. versionadded:: 3.3
-    The ability to type-hint an argument in order to receive a service was added
-    in Symfony 3.3.
+    The ability to type-hint a controller argument in order to receive a service
+    was added in Symfony 3.3.
 
 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.
 
-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::
+If you need a service in a controller, just type-hint an argument with its class
+(or interface) name. Symfony will automatically pass you the service you need::
 
     use Psr\Log\LoggerInterface
     // ...
@@ -266,16 +267,15 @@ Symfony will automatically pass you the service you need::
 
 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
+What other services can you type-hint? To see them, use the ``debug:container`` console
 command:
 
 .. code-block:: terminal
 
-    $ php bin/console debug:container
+    $ php bin/console debug:container --types
 
-If need to control the *exact* value of an argument, you can override your controller's
-service config:
+If you need control over the *exact* value of an argument, you can override your
+controller's service config:
 
 .. configuration-block::
 
@@ -334,22 +334,26 @@ service config:
             ])
         ;
 
+You can of course also use normal :ref:`constructor injection <services-constructor-injection>`
+in your controllers.
+
 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
+    is :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``.
+    you can tag your service manually with ``controller.service_arguments``. All
+    of this is done for you in a fresh Symfony install.
 
 .. _accessing-other-services:
 .. _controller-access-services-directly:
 
 Accessing the Container Directly
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If extending the base ``Controller`` class, you can access any Symfony service
+If you extend 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::
 
@@ -364,6 +368,8 @@ method. Here are several common services you might need::
 
 If you receive an eror like:
 
+.. code-block:: text
+
     You have requested a non-existent service "my_service_id"
 
 Check to make sure the service exists (use :ref:`debug:container <container-debug-container>`)

diff --git a/email.rst b/email.rst
@@ -128,7 +128,7 @@ an email is pretty straightforward::
 
         $mailer->send($message);
 
-        // or, you can also fetch the mailer service in this way
+        // or, you can also fetch the mailer service this way
         // $this->get('mailer')->send($message);
 
         return $this->render(...);

diff --git a/service_container.rst b/service_container.rst
@@ -25,7 +25,7 @@ Fetching and using Services
 
 The moment you start a Symfony app, your container *already* contains many services.
 These are like *tools*, waiting for you to take advantage of them. In your controller,
-you can "ask" for a service from the container by type-hinting an argument wit the
+you can "ask" for a service from the container by type-hinting an argument with the
 service's class or interface name. Want to :doc:`log </logging>` something? No problem::
 
     // src/AppBundle/Controller/ProductController.php
@@ -155,7 +155,7 @@ the service container *how* to instantiate it:
 
             # loads services from whatever directories you want (you can update this!)
             AppBundle\:
-                resource: '../../src/AppBundle/{Service,EventDispatcher,Twig,Form}'
+                resource: '../../src/AppBundle/{Service,Command,Form,EventSubscriber,Twig,Security}'
 
     .. code-block:: xml
 
@@ -171,14 +171,20 @@ the service container *how* to instantiate it:
                 <defaults autowire="true" autoconfigure="true" public="false" />
 
                 <!-- Load services from whatever directories you want (you can update this!) -->
-                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,EventDispatcher,Twig,Form}" />
+                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Command,Form,EventSubscriber,Twig,Security}" />
             </services>
         </container>
 
     .. code-block:: php
 
         // app/config/services.php
         // _defaults and loading entire directories is not possible with PHP configuration
+        // you need to define your servicess one-by-one
+        use AppBundle/Service/MessageGenerator;
+
+        $container->autowire(MessageGenerator::class)
+            ->setAutoconfigured(true)
+            ->setPublic(false);
 
 .. versionadded:: 3.3
     The ``_defaults`` key and ability to load services from a directory were added
@@ -228,18 +234,20 @@ be its class name in this case::
         }
     }
 
-However, this only works if you set your service to be :ref:`public <container-public>`.
+However, this only works if you make your service :ref:`public <container-public>`.
 
 .. caution::
 
     Service ids are case-insensitive (e.g. ``AppBundle\Service\MessageGenerator``
     and ``appbundle\service\messagegenerator`` refer to the same service). But this
     was deprecated in Symfony 3.3. Starting in 4.0, service ids will be case sensitive.
 
+.. _services-constructor-injection:
+
 Injecting Services/Config into a Service
 ----------------------------------------
 
-What if need to access the ``logger`` service from within ``MessageGenerator``?
+What if you need to access the ``logger`` service from within ``MessageGenerator``?
 Your service does *not* have access to the container directly, so you can't fetch
 it via ``$this->container->get()``.
 
@@ -272,17 +280,17 @@ when instantiating the ``MessageGenerator``. How does it know to do this?
 :doc:`Autowiring </service_container/autowiring>`. The key is the ``LoggerInterface``
 type-hint in your ``__construct()`` method and the ``autowire: true`` config in
 ``services.yml``. When you type-hint an argument, the container will automatically
-find the matching service. If it can't or there is any ambiguity, you'll see a clear
-exception with a helpful suggestion.
+find the matching service. If it can't, you'll see a clear exception with a helpful
+suggestion.
 
 Be sure to read more about :doc:`autowiring </service_container/autowiring>`.
 
 .. tip::
 
     How should you know to use ``LoggerInterface`` for the type-hint? The best way
     is by reading the docs for whatever feature you're using. You can also use the
-    ``php bin/console debug:container`` console command to get a hint
-    to the class name for a service.
+    ``php bin/console debug:container --types`` console command to get a list of
+    available type-hints.
 
 Handling Multiple Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -337,7 +345,7 @@ the new ``Updates`` sub-directory:
 
             # registers all classes in Services & Updates directories
             AppBundle\:
-                resource: '../../src/AppBundle/{Service,Updates,EventDispatcher,Twig,Form}'
+                resource: '../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}'
 
     .. code-block:: xml
 
@@ -352,7 +360,7 @@ the new ``Updates`` sub-directory:
                 <!-- ... -->
 
                 <!-- Registers all classes in Services & Updates directories -->
-                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Updates,EventDispatcher,Twig,Form}" />
+                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}" />
             </services>
         </container>
 
@@ -370,7 +378,7 @@ Now, you can use the service immediately::
     }
 
 Thanks to autowiring and your type-hints in ``__construct()``, the container creates
-the ``SiteUpdateManager`` object and passes it the correct arguments. In most cases,
+the ``SiteUpdateManager`` object and passes it the correct argument. In most cases,
 this works perfectly.
 
 Manually Wiring Arguments
@@ -428,7 +436,7 @@ pass here. No problem! In your configuration, you can explicitly set this argume
 
             # same as before
             AppBundle\:
-                resource: '../../src/AppBundle/{Service,Updates}'
+                resource: '../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}'
 
             # explicitly configure the service
             AppBundle\Updates\SiteUpdateManager:
@@ -448,7 +456,7 @@ pass here. No problem! In your configuration, you can explicitly set this argume
                 <!-- ... -->
 
                 <!-- Same as before -->
-                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Updates}" />
+                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}" />
 
                 <!-- Explicitly configure the service -->
                 <service id="AppBundle\Updates\SiteUpdateManager">
@@ -526,6 +534,8 @@ and reference it with the ``%parameter_name%`` syntax:
 
     .. code-block:: php
 
+        // app/config/services.php
+        use AppBundle\Updates\SiteUpdateManager;
         $container->setParameter('admin_email', 'manager@example.com');
 
         $container->autowire(SiteUpdateManager::class)
@@ -659,7 +669,7 @@ The autoconfigure Option
 Above, we've set ``autoconfigure: true`` in the ``_defaults`` section so that it
 applies to all services defined in that file. With this setting, the container will
 automatically apply certain configuration to your services, based on your service's
-*class*. The is mostly used to *auto-tag* your services.
+*class*. This is mostly used to *auto-tag* your services.
 
 For example, to create a Twig Extension, you need to create a class, register it
 as a service, and :doc:`tag </service_container/tags>` it with ``twig.extension``:
@@ -702,7 +712,8 @@ as a service, and :doc:`tag </service_container/tags>` it with ``twig.extension`
             ->addTag('twig.extension');
 
 But, with ``autoconfigure: true``, you don't need the tag. In fact, all you need
-to do is load your service from the ``Twig`` directory:
+to do is load your service from the ``Twig`` directory, which is already loaded
+by default in a fresh Symfony install:
 
 .. configuration-block::
 
@@ -716,7 +727,7 @@ to do is load your service from the ``Twig`` directory:
 
             # load your services from the Twig directory
             AppBundle\:
-                resource: '../../src/AppBundle/{Service,EventDispatcher,Twig,Form}'
+                resource: '../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}'
 
     .. code-block:: xml
 
@@ -731,7 +742,7 @@ to do is load your service from the ``Twig`` directory:
                 <defaults autowire="true" autoconfigure="true" />
 
                 <!-- Load your services-->
-                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,EventDispatcher,Twig,Form}" />
+                <prototype namespace="AppBundle\" resource="../../src/AppBundle/{Service,Updates,Command,Form,EventSubscriber,Twig,Security}" />
             </services>
         </container>