Updating more types, and basically rewriting the alias article

Author: weaverryan

security.rst

@@ -1289,7 +1289,6 @@ Authentication (Identifying/Logging in the User)
     security/api_key_authentication
     security/custom_authentication_provider
     security/pre_authenticated
-    security/target_path
     security/csrf_in_login_form
     security/named_encoders
     security/multiple_user_providers

security/access_denied_handler.rst

@@ -49,9 +49,9 @@ configure it under your firewall:
     .. code-block:: xml
 
         <config>
-          <firewall name="main">
-            <access_denied_handler>AppBundle\Security\AccessDeniedHandler</access_denied_handler>
-          </firewall>
+            <firewall name="main">
+                <access_denied_handler>AppBundle\Security\AccessDeniedHandler</access_denied_handler>
+            </firewall>
         </config>
 
     .. code-block:: php

security/api_key_authentication.rst

@@ -338,12 +338,12 @@ and ``provider`` keys:
 
         $container->loadFromExtension('security', array(
             'providers' => array(
-                'api_key_user_provider'  => array(
+                'api_key_user_provider' => array(
                     'id' => ApiKeyUserProvider::class,
                 ),
             ),
             'firewalls' => array(
-                'secured_area'       => array(
+                'main' => array(
                     'pattern'        => '^/api',
                     'stateless'      => true,
                     'simple_preauth' => array(
@@ -594,7 +594,7 @@ current URL is before creating the token in ``createToken()``::
             // set the only URL where we should look for auth information
             // and only return the token if we're at that URL
             $targetUrl = '/login/check';
-            if ($request->getPathInfo() != $targetUrl)
+            if ($request->getPathInfo() !== $targetUrl)
                 return;
             }
 

security/form_login.rst

@@ -31,14 +31,6 @@ directly to the login page), then the user is redirected to the default page,
 which is  ``/`` (i.e. the homepage) by default. You can change this behavior
 in several ways.
 
-.. note::
-
-    As mentioned, by default the user is redirected back to the page originally
-    requested. Sometimes, this can cause problems, like if a background Ajax
-    request "appears" to be the last visited URL, causing the user to be
-    redirected there. For information on controlling this behavior, see
-    :doc:`/security/target_path`.
-
 Changing the default Page
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

service_container.rst

@@ -858,6 +858,10 @@ You can override any service that's imported by using its id (class name) below
 the options (e.g. ``public``) are inherited from the import (but the overridden
 service *does* still inherit from ``_defaults``).
 
+You can also ``exclude`` certain paths. This is optional, but will slightly increase
+performance in the ``dev`` environment: excluded paths are not tracked and so modifying
+them will not cause the container to be rebuilt.
+
 .. note::
 
     Wait, does this mean that *every* class in ``src/AppBundle`` is registered as

service_container/alias_private.rst

@@ -9,30 +9,33 @@ How to Create Service Aliases and Mark Services as Private
 Marking Services as Public / Private
 ------------------------------------
 
-When defining services, you'll usually want to be able to access these definitions
-within your application code. These services are called *public*. For
-example, the ``doctrine`` service is a public service. This means that you can
-fetch it from the container using the ``get()`` method::
+When defining a service, it can be made to be *public* or *private*. If a service
+is *public*, it means that you can access it directly from the container at runtime.
+For example, the ``doctrine`` service is a public service::
 
+    // only public services can be accessed in this way
     $doctrine = $container->get('doctrine');
 
-In some cases, a service *only* exists to be injected into another service
-and is *not* intended to be fetched directly from the container as shown
-above.
+But typically, services are accessed using :ref:`dependency injection <services-constructor-injection>`.
+And in this case, those services do *not* need to be public.
 
 .. _inlined-private-services:
 
-In these cases, to get a minor performance boost and ensure the service will not
-be retrieved directly from the container, you can set the service to be *not*
-public (i.e. private):
+So unless you *specifically* need to access a service directly from the container
+via ``$container->get()``, the best-practice is to make your services *private*.
+In fact, the :ref:`default services.yml configuration <container-public>` configures
+all services to be private by default.
+
+You can also control the ``public`` option on a service-by-service basis:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         services:
-            foo:
-                class: Example\Foo
+            # ...
+
+            AppBundle\Service\Foo:
                 public: false
 
     .. code-block:: xml
@@ -43,29 +46,30 @@ public (i.e. private):
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="foo" class="Example\Foo" public="false" />
+                <service id="AppBundle\Service\Foo" public="false" />
             </services>
         </container>
 
     .. code-block:: php
 
-        use Example\Foo;
+        use AppBundle\Service\Foo;
 
-        $container->register('foo', Foo::class)
+        $container->register(Foo::class)
             ->setPublic(false);
 
-What makes private services special is that, since the container knows that the
-service will never be requested from outside, it can optimize whether and how it
-is instanciated. This increases the container's performance.
+Private services are special because they allow the container to optimize whether
+and how they are instantiated. This increases the container's performance.
 
 Now that the service is private, you *should not* fetch the service directly
 from the container::
 
-    $container->get('foo');
+    use AppBundle\Service\Foo;
+
+    $container->get(Foo::class);
 
 This *may or may not work*, depending on how the container has optimized the
-service instanciation and, even in the cases where it works, is
-deprecated. Simply said: A service can be marked as private if you do not want
+service instantiation and, even in the cases where it works, is
+deprecated. Simply said: A service should be marked as private if you do not want
 to access it directly from your code.
 
 However, if a service has been marked as private, you can still alias it
@@ -76,6 +80,8 @@ However, if a service has been marked as private, you can still alias it
     Services are by default public, but it's considered a good practice to mark
     as much services private as possible.
 
+.. _services-alias:
+
 Aliasing
 --------
 
@@ -88,11 +94,13 @@ services.
     .. code-block:: yaml
 
         services:
-            app.phpmailer:
-                class: AppBundle\Mail\PhpMailer
+            # ...
+            AppBundle\Mail\PhpMailer:
+                public: false
 
             app.mailer:
-                alias: app.phpmailer
+                alias: AppBundle\Mail\PhpMailer
+                public: true
 
     .. code-block:: xml
 
@@ -102,22 +110,23 @@ services.
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="app.phpmailer" class="AppBundle\Mail\PhpMailer" />
+                <service class="AppBundle\Mail\PhpMailer" public="false" />
 
-                <service id="app.mailer" alias="app.phpmailer" />
+                <service id="app.mailer" alias="AppBundle\Mail\PhpMailer" />
             </services>
         </container>
 
     .. code-block:: php
 
         use AppBundle\Mail\PhpMailer;
 
-        $container->register('app.phpmailer', PhpMailer::class);
+        $container->register(PhpMailer::class)
+            ->setPublic(false);
 
-        $container->setAlias('app.mailer', 'app.phpmailer');
+        $container->setAlias('app.mailer', PhpMailer::class);
 
 This means that when using the container directly, you can access the
-``app.phpmailer`` service by asking for the ``app.mailer`` service like this::
+``PhpMailer`` service by asking for the ``app.mailer`` service like this::
 
     $container->get('app.mailer'); // Would return a PhpMailer instance
 
@@ -141,8 +150,7 @@ or you decided not to maintain it anymore), you can deprecate its definition:
 
     .. code-block:: yaml
 
-       acme.my_service:
-           class: ...
+       AppBundle\Service\OldService:
            deprecated: The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.
 
     .. code-block:: xml
@@ -153,16 +161,18 @@ or you decided not to maintain it anymore), you can deprecate its definition:
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="acme.my_service" class="...">
+                <service id="AppBundle\Service\OldService">
                     <deprecated>The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.</deprecated>
                 </service>
             </services>
         </container>
 
     .. code-block:: php
 
+        use AppBundle\Service\OldService;
+
         $container
-            ->register('acme.my_service', '...')
+            ->register(OldService::class)
             ->setDeprecated(
                 true,
                 'The "%service_id%" service is deprecated since 2.8 and will be removed in 3.0.'
@@ -189,6 +199,6 @@ occurrence of the ``%service_id%`` placeholder in your template.
     deprecated, until when it will be maintained and the alternative services
     to use (if any).
 
-For service decorators (see above), if the definition does not modify the
-deprecated status, it will inherit the status from the definition that is
-decorated.
+For service decorators (see :doc:`/service_container/service_decoration`), if the
+definition does not modify the deprecated status, it will inherit the status from
+the definition that is decorated.