Merge branch '3.4'

* 3.4:
  tweaks thanks to review
  Adding second argument to setTrustedProxies() and removing old information
  replace trusted_proxies reference
  replace diff code block with PHP code block
  Remove deprecated trusted_proxies config option
  Remove deprecated trusted_proxies config option
  Tweaks after review!
  Tweaks thanks to Javier's reviews
  updating example to show class as service id
  Fixing bad indentation with diff
  more type changes
  updating best practices for DI 3.3 changes
  Minor tweaks for the article that explains the new 3.3 DI features
  Update some examples using 3.3 features

Author: weaverryan

_build/redirection_map

@@ -336,3 +336,6 @@
 /components/dependency_injection/autowiring /service_container/autowiring
 /event_dispatcher/class_extension /event_dispatcher
 /security/target_path /security
+/service_container/third_party /service_container
+/templating/templating_service /templates
+/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy

best_practices/business-logic.rst

@@ -84,30 +84,42 @@ Next, define a new service for that class.
 
     # app/config/services.yml
     services:
-        # keep your service names short
-        app.slugger:
-            class: AppBundle\Utils\Slugger
+        # ...
+
+        # use the fully-qualified class name as the service id
+        AppBundle\Utils\Slugger:
+            public: false
+
+.. note::
 
-Traditionally, the naming convention for a service involved following the
-class name and location to avoid name collisions. Thus, the service
-*would have been* called ``app.utils.slugger``. But by using short service names,
-your code will be easier to read and use.
+    If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
+    the class is auto-registered as a service.
+
+Traditionally, the naming convention for a service was a short, but unique
+snake case key - e.g. ``app.utils.slugger``. But for most services, you should now
+use the class name.
 
 .. best-practice::
 
-    The name of your application's services should be as short as possible,
-    but unique enough that you can search your project for the service if
-    you ever need to.
+    The id of your application's services should be equal to their class name,
+    except when you have multiple services configured for the same class (in that
+    case, use a snake case id).
 
 Now you can use the custom slugger in any controller class, such as the
 ``AdminController``:
 
 .. code-block:: php
 
-    public function createAction(Request $request)
+    use AppBundle\Utils\Slugger;
+
+    public function createAction(Request $request, Slugger $slugger)
     {
         // ...
 
+        // 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()) {
             $slug = $this->get('app.slugger')->slugify($post->getTitle());
             $post->setSlug($slug);
@@ -116,6 +128,16 @@ Now you can use the custom slugger in any controller class, such as the
         }
     }
 
+Services can also be :ref:`public or private <container-public>`. If you use the
+:ref:`default services.yml configuration <service-container-services-load-example>`,
+all services are private by default.
+
+.. best-practice::
+
+    Services should be ``private`` whenever possible. This will prevent you from
+    accessing that service via ``$container->get()``. Instead, you will need to use
+    dependency injection.
+
 Service Format: YAML
 --------------------
 

best_practices/controllers.rst

@@ -97,16 +97,16 @@ for the homepage of our app:
 
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+    use Doctrine\ORM\EntityManagerInterface;
 
     class DefaultController extends Controller
     {
         /**
          * @Route("/", name="homepage")
          */
-        public function indexAction()
+        public function indexAction(EntityManagerInterface $em)
         {
-            $posts = $this->getDoctrine()
-                ->getRepository('AppBundle:Post')
+            $posts = $em->getRepository('AppBundle:Post')
                 ->findLatest();
 
             return $this->render('default/index.html.twig', array(
@@ -115,6 +115,22 @@ for the homepage of our app:
         }
     }
 
+Fetching Services
+-----------------
+
+If you extend the base ``Controller`` class, you can access services directly from
+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>`:
+
+.. best-practice::
+
+    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

best_practices/security.rst

@@ -224,9 +224,9 @@ more advanced use-case, you can always do the same security check in PHP:
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
      */
-    public function editAction($id)
+    public function editAction($id, EntityManagerInterface $em)
     {
-        $post = $this->getDoctrine()->getRepository('AppBundle:Post')
+        $post = $em->getRepository('AppBundle:Post')
             ->find($id);
 
         if (!$post) {
@@ -328,7 +328,8 @@ the same ``getAuthorEmail()`` logic you used above:
         }
     }
 
-Your application will :ref:`autoconfigure <services-autoconfigure>` your security
+If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
+your application will :ref:`autoconfigure <services-autoconfigure>` your security
 voter and inject a ``AccessDecisionManagerInterface`` instance in it thanks to
 :doc:`autowiring </service_container/autowiring>`.
 

bundles/best_practices.rst

@@ -384,7 +384,14 @@ If the bundle defines services, they must be prefixed with the bundle alias.
 For example, AcmeBlogBundle services must be prefixed with ``acme_blog``.
 
 In addition, services not meant to be used by the application directly, should
-be :ref:`defined as private <container-private-services>`.
+be :ref:`defined as private <container-private-services>`. For public services,
+:ref:`aliases should be created <service-autowiring-alias>` from the interface/class
+to the service id. For example, in MonologBundle, an alias is created from
+``Psr\Log\LoggerInterface`` to ``logger`` so that the ``LoggerInterface`` type-hint
+can be used for autowiring.
+
+Services should not use autowiring or autoconfiguration. Instead, all services should
+be defined explicitly.
 
 .. seealso::
 

bundles/extension.rst

@@ -129,6 +129,12 @@ read more about it, see the ":doc:`/bundles/configuration`" article.
 Adding Classes to Compile
 -------------------------
 
+.. note::
+
+    The ``addClassesToCompile()`` method was deprecated in Symfony 3.3, and will
+    be removed in Symfony 4.0. If you want to use this method and be compatible
+    with Symfony 4.0, check to see if the method exists before calling it.
+
 Symfony creates a big ``classes.php`` file in the cache directory to aggregate
 the contents of the PHP classes that are used in every request. This reduces the
 I/O operations and increases the application performance.

components/http_foundation/trusting_proxies.rst

@@ -32,12 +32,12 @@ Run this command from inside your controller via::
     use Symfony\Component\Console\Input\ArrayInput;
     use Symfony\Component\Console\Output\BufferedOutput;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\KernelInterface;
 
     class SpoolController extends Controller
     {
-        public function sendSpoolAction($messages = 10)
+        public function sendSpoolAction($messages = 10, KernelInterface $kernel)
         {
-            $kernel = $this->get('kernel');
             $application = new Application($kernel);
             $application->setAutoExit(false);