Tweaks after review!

Author: weaverryan

best_practices/business-logic.rst

@@ -86,7 +86,7 @@ Next, define a new service for that class.
     services:
         # ...
 
-        # use the class name as the service id
+        # use the fully-qualified class name as the service id
         AppBundle\Utils\Slugger:
             public: false
 
@@ -116,7 +116,8 @@ Now you can use the custom slugger in any controller class, such as the
     {
         // ...
 
-        // you can also fetch a public service like this, but is not the best-practice
+        // you can also fetch a public service like this
+        // but fetching services in this way is not considered a best practice
         // $slugger = $this->get('app.slugger');
 
         if ($form->isSubmitted() && $form->isValid()) {

best_practices/controllers.rst

@@ -119,7 +119,7 @@ Fetching Services
 -----------------
 
 If you extend the base ``Controller`` class, you can access services directly from
-the container via ``$this->container->get()`` or ``$this->get()``. Instead, you
+the container via ``$this->container->get()`` or ``$this->get()``. But instead, you
 should use dependency injection to fetch services: most easily done by
 :ref:`type-hinting action method arguments <controller-accessing-services>`:
 
@@ -128,6 +128,9 @@ should use dependency injection to fetch services: most easily done by
     Don't use ``$this->get()`` or ``$this->container->get()`` to fetch services
     from the container. Instead, use dependency injection.
 
+By not fetching services directly from the container, you can make your services
+*private*, which has :ref:`several advantages <services-why-private>`.
+
 .. _best-practices-paramconverter:
 
 Using the ParamConverter
@@ -177,14 +180,13 @@ manually. In our application, we have this situation in ``CommentController``:
 
 .. code-block:: php
 
-    use Doctrine\ORM\EntityManagerInterface;
-
     /**
      * @Route("/comment/{postSlug}/new", name = "comment_new")
      */
-    public function newAction(Request $request, $postSlug, EntityManagerInterface $em)
+    public function newAction(Request $request, $postSlug)
     {
-        $post = $em->getRepository('AppBundle:Post')
+        $post = $this->getDoctrine()
+            ->getRepository('AppBundle:Post')
             ->findOneBy(array('slug' => $postSlug));
 
         if (!$post) {

service_container/alias_private.rst

@@ -57,8 +57,13 @@ You can also control the ``public`` option on a service-by-service basis:
         $container->register(Foo::class)
             ->setPublic(false);
 
+.. _services-why-private:
+
 Private services are special because they allow the container to optimize whether
-and how they are instantiated. This increases the container's performance.
+and how they are instantiated. This increases the container's performance. It also
+gives you better errors: if you try to reference a non-existent service, you will
+get a clear error when you refresh *any* page, even if the problematic code would
+not have run on that page.
 
 Now that the service is private, you *should not* fetch the service directly
 from the container::