Merge branch '4.0'

* 4.0:
  Use escaped backslashes
  Don't mention the UserInterface type-hinting
  Change symfony-public-dir to public-dir
  Update web/ directory to public/ on bundle page
  Fix wrong import path
  Add information about default value for decoration_priority
  Adding the missing attr option to the ChoiceType
  Update choice.rst
  Minor fixes in the bundles article
  Fixed the link to the bin/console script
  Update profiler.rst

Author: javiereguiluz

bundles.rst

@@ -44,7 +44,7 @@ file::
 Creating a Bundle
 -----------------
 
-This section creates and enables a new bundle to show how simple is to do it.
+This section creates and enables a new bundle to show how simple it is to do it.
 The new bundle is called AcmeTestBundle, where the ``Acme`` portion is just a
 dummy name that should be replaced by some "vendor" name that represents you or
 your organization (e.g. ABCTestBundle for some company named ``ABC``).
@@ -104,7 +104,7 @@ of the most common elements of a bundle:
 
 ``Resources/public/``
     Contains web assets (images, stylesheets, etc) and is copied or symbolically
-    linked into the project ``web/`` directory via the ``assets:install`` console
+    linked into the project ``public/`` directory via the ``assets:install`` console
     command.
 
 ``Tests/``

configuration/override_dir_structure.rst

@@ -143,7 +143,7 @@ those files::
 
     require_once __DIR__.'/../path/to/vendor/autoload.php';
 
-You also need to change the ``extra.symfony-public-dir`` option in the
+You also need to change the ``extra.public-dir`` option in the
 ``composer.json`` file:
 
 .. code-block:: json
@@ -152,7 +152,7 @@ You also need to change the ``extra.symfony-public-dir`` option in the
         "...": "...",
         "extra": {
             "...": "...",
-            "symfony-public-dir": "my_new_public_dir"
+            "public-dir": "my_new_public_dir"
         }
     }
 

controller.rst

@@ -300,7 +300,7 @@ Managing Errors and 404 Pages
 When things are not found, you should return a 404 response. To do this, throw a
 special type of exception::
 
-    use Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException;
+    use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
     // ...
     public function indexAction()

profiler.rst

@@ -12,7 +12,7 @@ install the profiler before using it:
 
 .. code-block:: terminal
 
-    $ composer require profiler
+    $ composer require profiler --dev
 
 .. toctree::
     :maxdepth: 1

quick_tour/the_architecture.rst

@@ -207,7 +207,7 @@ great tools for this: the web debug toolbar displays at the bottom of the page,
 are big, beautiful & explicit, and any configuration cache is automatically rebuilt
 whenever needed.
 
-But what about when you deploy to production? We will need to hide those tool and
+But what about when you deploy to production? We will need to hide those tools and
 optimize for speed!
 
 This is solved by Symfony's *environment* system and there are three: ``dev``, ``prod``
@@ -266,7 +266,7 @@ Platform as a Service (PaaS) deployment systems as well as Docker.
 But setting environment variables while developing can be a pain. That's why your
 app automatically loads a ``.env`` file, if the ``APP_ENV`` environment variable
 isn't set in the environment. The keys in this file then become environment variables
-are and read by your app:
+and are read by your app:
 
 .. code-block:: bash
 
@@ -278,7 +278,7 @@ are and read by your app:
 
 At first, the file doesn't contain much. But as your app grows, you'll add more
 configuration as you need it. But, actually, it gets much more interesting! Suppose
-your app needs database ORM. Let's install the Doctrine ORM:
+your app needs a database ORM. Let's install the Doctrine ORM:
 
 .. code-block:: terminal
 

reference/forms/types/choice.rst

@@ -29,8 +29,9 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
 | options     | - `empty_data`_                                                              |
 |             | - `error_bubbling`_                                                          |
 +-------------+------------------------------------------------------------------------------+
-| Inherited   | - `by_reference`_                                                            |
-| options     | - `data`_                                                                    |
+| Inherited   | - `attr`_                                                                    |
+| options     | - `by_reference`_                                                            |
+|             | - `data`_                                                                    |
 |             | - `disabled`_                                                                |
 |             | - `error_mapping`_                                                           |
 |             | - `inherit_data`_                                                            |
@@ -98,6 +99,7 @@ method::
         'choice_attr' => function($category, $key, $index) {
             return ['class' => 'category_'.strtolower($category->getName())];
         },
+        
         'group_by' => function($category, $key, $index) {
             // randomly assign things into 2 groups
             return rand(0, 1) == 1 ? 'Group A' : 'Group B';
@@ -252,6 +254,8 @@ Inherited Options
 
 These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
+.. include:: /reference/forms/types/options/attr.rst.inc
+
 .. include:: /reference/forms/types/options/by_reference.rst.inc
 
 .. include:: /reference/forms/types/options/data.rst.inc

routing.rst

@@ -616,7 +616,7 @@ Troubleshooting
 
 Here are some common errors you might see while working with routing:
 
-    Controller "App\Controller\BlogController::show()" requires that you
+    Controller "App\\Controller\\BlogController::show()" requires that you
     provide a value for the "$slug" argument.
 
 This happens when your controller method has an argument (e.g. ``$slug``)::

security.rst

@@ -1007,16 +1007,14 @@ If you still prefer to use traditional ACLs, refer to the `Symfony ACL bundle`_.
 -----------------------------
 
 After authentication, the ``User`` object of the current user can be accessed
-via the ``security.token_storage`` service. From inside a controller, this will
-look like::
+via the ``getUser()`` shortcut (which uses the ``security.token_storage``
+service). From inside a controller, this will look like::
 
     public function index()
     {
         $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY');
 
         $user = $this->getUser();
-        // or you can also type-hint a method argument with this class:
-        // Symfony\Component\Security\Core\User\UserInterface (e.g. "UserInterface $user")
     }
 
 .. tip::
@@ -1044,14 +1042,7 @@ It's important to check if the user is authenticated first. If they're not,
 ``$user`` will either be ``null`` or the string ``anon.``. Wait, what? Yes,
 this is a quirk. If you're not logged in, the user is technically the string
 ``anon.``, though the ``getUser()`` controller shortcut converts this to
-``null`` for convenience. When type-hinting the
-:class:`Symfony\\Component\\Security\\Core\\User\\UserInterface\\UserInterface`
-and being logged-in is optional, you can allow a null value for the argument::
-
-    public function index(UserInterface $user = null)
-    {
-        // $user is null when not logged-in or anon.
-    }
+``null`` for convenience.
 
 The point is this: always check to see if the user is logged in before using
 the User object, and use the ``isGranted()`` method (or
@@ -1065,6 +1056,25 @@ the User object, and use the ``isGranted()`` method (or
         // ...
     }
 
+.. note::
+
+    An alternative way to get the current user in a controller is to type-hint
+    the controller argument with
+    :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface\\UserInterface`
+    (and default it to ``null`` if being logged-in is optional)::
+
+        use Symfony\Component\Security\Core\User\UserInterface\UserInterface;
+
+        public function indexAction(UserInterface $user = null)
+        {
+            // $user is null when not logged-in or anon.
+        }
+
+    This is only recommended for experienced developers who don't extend from the
+    :ref:`Symfony base controller <the-base-controller-class-services>` and
+    don't use the :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerTrait`
+    either. Otherwise, it's recommended to keep using the ``getUser()`` shortcut.
+
 Retrieving the User in a Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

service_container/service_decoration.rst

@@ -179,9 +179,9 @@ replaces the ``app.mailer`` service. The old ``app.mailer`` service is renamed t
 Decoration Priority
 -------------------
 
-If you want to apply more than one decorator to a service, you can control their
-order by configuring the priority of decoration, this can be any integer number
-(decorators with higher priorities will be applied first).
+When applying multiple decorators to a service, you can control their order with
+the ``decoration_priority`` option. Its value is an integer that defaults to
+``0`` and higher priorities mean that decorators will be applied earlier.
 
 .. configuration-block::
 

setup/flex.rst

@@ -254,4 +254,4 @@ manual steps:
 .. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/config/services.yaml
 .. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
 .. _`copying Symfony's index.php source`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
-.. _`copying Symfony's bin/console source`: https://github.com/symfony/recipes/tree/master/symfony/console/3.3
+.. _`copying Symfony's bin/console source`: https://github.com/symfony/recipes/blob/master/symfony/console/3.3/bin/console