Merge branch '3.4'

* 3.4:
  more underlining!
  [#8571] Tweaks thanks to reviewers
  tweaked docs for Flex
  Update security.rst
  use .test instead of .dev as development domain
  updating controller scalar args for 3.4
  Shortened command... easier to remember ;)
  Final updates
  Last fixes
  Restored the "Full Default Configuration" dump
  Fixed an indentation issue
  Simplified the framework configuration reference
  Added Doctrine entities and documents to the list of known locations for classes

Author: weaverryan

bundles/best_practices.rst

@@ -115,23 +115,23 @@ files are going to be part of the repository.
 The following classes and files have specific emplacements (some are mandatory
 and others are just conventions followed by most developers):
 
-===============================  =============================  ================
-Type                             Directory                      Mandatory?
-===============================  =============================  ================
-Commands                         ``Command/``                   Yes
-Controllers                      ``Controller/``                No
-Service Container Extensions     ``DependencyInjection/``       Yes
-Event Listeners                  ``EventListener/``             No
-Model classes [1]                ``Model/``                     No
-Configuration                    ``Resources/config/``          No
-Web Resources (CSS, JS, images)  ``Resources/public/``          Yes
-Translation files                ``Resources/translations/``    Yes
-Templates                        ``Resources/views/``           Yes
-Unit and Functional Tests        ``Tests/``                     No
-===============================  =============================  ================
-
-[1] See :doc:`/doctrine/mapping_model_classes` for how to handle the
-mapping with a compiler pass.
+===================================================  ========================================
+Type                                                 Directory                               
+===================================================  ========================================
+Commands                                             ``Command/``                            
+Controllers                                          ``Controller/``                         
+Service Container Extensions                         ``DependencyInjection/``                
+Doctrine ORM entities (when not using annotations)   ``Entity/``
+Doctrine ODM documents (when not using annotations)  ``Document/``
+Event Listeners                                      ``EventListener/``                      
+Configuration                                        ``Resources/config/``                   
+Web Resources (CSS, JS, images)                      ``Resources/public/``                   
+Translation files                                    ``Resources/translations/``     
+Validation (when not using annotations)              ``Resources/config/validation/``
+Serialization (when not using annotations)           ``Resources/config/serialization/``
+Templates                                            ``Resources/views/``                    
+Unit and Functional Tests                            ``Tests/``                              
+===================================================  ========================================
 
 Classes
 -------

controller.rst

@@ -275,8 +275,8 @@ command:
 
     $ php bin/console debug:autowiring
 
-If you need control over 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 :ref:`bind <services-binding>`
+the argument by its name:
 
 .. configuration-block::
 
@@ -289,13 +289,9 @@ controller's service config:
             # explicitly configure the service
             App\Controller\LuckyController:
                 public: true
-                tags:
-                    # add multiple tags to control multiple args
-                    - name: controller.service_arguments
-                      action: numberAction
-                      argument: logger
-                      # pass this specific service id
-                      id: monolog.logger.doctrine
+                bind:
+                    # for any $logger argument, pass this specific service
+                    $logger: '@monolog.logger.doctrine'
 
     .. code-block:: xml
 
@@ -311,10 +307,8 @@ controller's service config:
 
                 <!-- Explicitly configure the service -->
                 <service id="App\Controller\LuckyController" public="true">
-                    <tag
-                        name="controller.service_arguments"
-                        action="numberAction"
-                        argument="logger"
+                    <bind key="$logger"
+                        type="service"
                         id="monolog.logger.doctrine"
                     />
                 </service>
@@ -325,25 +319,25 @@ controller's service config:
 
         // config/services.php
         use App\Controller\LuckyController;
+        use Symfony\Component\DependencyInjection\Reference;
 
         $container->register(LuckyController::class)
             ->setPublic(true)
-            ->addTag('controller.service_arguments', [
-                'action' => 'numberAction',
-                'argument' => 'logger',
-                'id' => 'monolog.logger.doctrine',
-            ])
+            ->setBindings(array(
+                '$logger' => new Reference('monolog.logger.doctrine'),
+            ))
         ;
 
 You can of course also use normal :ref:`constructor injection <services-constructor-injection>`
 in your controllers.
 
 .. caution::
 
-    You can *only* pass *services* to your controller arguments in this way. It's
-    not possible, for example, to pass a service parameter as a controller argument.
-    If you need a parameter, use the ``$this->getParameter('kernel.debug')`` shortcut
-    or pass the value through your controller's ``__construct()`` method.
+    You can *only* pass *services* to your controller arguments in this way. It's not
+    possible, for example, to pass a service parameter as a controller argument,
+    even by using ``bind``. If you need a parameter, use the ``$this->getParameter('kernel.debug')``
+    shortcut or pass the value through your controller's ``__construct()`` method
+    and specify its value with ``bind``.
 
 For more information about services, see the :doc:`/service_container` article.
 

reference/configuration/framework.rst

@@ -4,18 +4,23 @@
 FrameworkBundle Configuration ("framework")
 ===========================================
 
-The FrameworkBundle contains most of the "base" framework functionality
-and can be configured under the ``framework`` key in your application
-configuration. When using XML, you must use the
-``http://symfony.com/schema/dic/symfony`` namespace.
+The FrameworkBundle defines the main framework configuration, from sessions and
+translations to forms, validation, routing and more. All these options are
+configured under the ``framework`` key in your application configuration.
 
-This includes settings related to sessions, translation, forms, validation,
-routing and more.
+.. code-block:: terminal
 
-.. tip::
+    # displays the default config values defined by Symfony
+    $ php bin/console config:dump framework
+
+    # displays the actual config values used by your application
+    $ php bin/console debug:config framework
+
+.. note::
 
-   The XSD schema is available at
-   ``http://symfony.com/schema/dic/symfony/symfony-1.0.xsd``.
+    When using XML, you must use the ``http://symfony.com/schema/dic/symfony``
+    namespace and the related XSD schema is available at:
+    ``http://symfony.com/schema/dic/symfony/symfony-1.0.xsd``
 
 Configuration
 -------------

security.rst

@@ -993,8 +993,8 @@ To accomplish this you have 2 options:
 In both cases, you'll still deny access using methods similar to what was
 shown above.
 
-Retrieving the User Object
---------------------------
+3) Retrieving the User Object
+-----------------------------
 
 After authentication, the ``User`` object of the current user can be accessed
 via the ``security.token_storage`` service. From inside a controller, this will

service_container.rst

@@ -690,6 +690,13 @@ service whose id is ``monolog.logger.request``.
     the *service* whose id is ``monolog.logger.request``, and not just the *string*
     ``monolog.logger.request``.
 
+.. _services-binding:
+
+Binding Arguments by Name or Type
+---------------------------------
+
+You can also use the ``bind`` keyword to bind specific arguments by name or type.
+
 .. _services-autowire:
 
 The autowire Option

setup/flex.rst

@@ -5,20 +5,20 @@ Using Symfony Flex to Manage Symfony Applications
 
 `Symfony Flex`_ is the new way to install and manage Symfony applications. Flex
 is not a new Symfony version, but a tool that replaces and improves the
-`Symfony Installer`_.
+`Symfony Installer`_ and the `Symfony Standard Edition`_.
 
 Symfony Flex **automates the most common tasks of Symfony applications**, such
-as installing and removing bundles and other dependencies. Symfony Flex works
-for Symfony 3.3 and newer versions. Starting from Symfony 4.0, Flex will be used
-by default, but it will still be optional to use.
+as installing and removing bundles and other Composer dependencies. Symfony
+Flex works for Symfony 3.3 and newer versions. Starting from Symfony 4.0, Flex
+should be used by default, but it is still optional.
 
 How Does Flex Work
 ------------------
 
 Internally, Symfony Flex is a Composer plugin that modifies the behavior of the
-``require`` and ``update`` commands. When installing or updating dependencies
-in a Flex-enabled application, Symfony can perform tasks before and after the
-execution of Composer tasks.
+``require``, ``update``, and ``remove`` commands. When installing or removing
+dependencies in a Flex-enabled application, Symfony can perform tasks before
+and after the execution of Composer tasks.
 
 Consider the following example:
 
@@ -33,25 +33,30 @@ name. However, if the application has Symfony Flex installed, that command ends
 up installing and enabling the SwiftmailerBundle, which is the best way to
 integrate Swiftmailer, the official mailer for Symfony applications.
 
-When Symfony Flex is installed in the application and you execute ``composer require``,
-the application makes a request to Symfony Flex servers before trying to install
-the package with Composer:
+When Symfony Flex is installed in the application and you execute ``composer
+require``, the application makes a request to Symfony Flex servers before
+trying to install the package with Composer:
 
 * If there's no information about that package, Flex server returns nothing and
   the package installation follows the usual procedure based on Composer;
+
 * If there's special information about that package, Flex returns it in a file
-  called "recipe" and the application uses it to decide which package to install
-  and which automated tasks to run after the installation.
+  called "recipe" and the application uses it to decide which package to
+  install and which automated tasks to run after the installation.
 
 In the above example, Symfony Flex asks about the ``mailer`` package and the
-Symfony Flex server detects that ``mailer`` is in fact an alias for SwiftmailerBundle
-and returns the "recipe" for it.
+Symfony Flex server detects that ``mailer`` is in fact an alias for
+SwiftmailerBundle and returns the "recipe" for it.
+
+Flex keeps tracks of the recipes it installed in a ``symfony.lock`` file, which
+must be committed to your code repository.
 
 Symfony Flex Recipes
 ~~~~~~~~~~~~~~~~~~~~
 
 Recipes are defined in a ``manifest.json`` file and can contain any number of
-other files and directories. For example, this is the ``manifest.json`` for SwiftmailerBundle:
+other files and directories. For example, this is the ``manifest.json`` for
+SwiftmailerBundle:
 
 .. code-block:: javascript
 
@@ -69,27 +74,29 @@ other files and directories. For example, this is the ``manifest.json`` for Swif
     }
 
 The ``aliases`` option allows Flex to install packages using short and easy to
-remember names (``composer require mailer`` vs ``composer require symfony/swiftmailer-bundle``).
-The ``bundles`` option tells Flex in which environments should this bundle be
-enabled automatically (``all`` in this case). The ``env`` option makes Flex to
-add new environment variables to the application. Finally, the ``copy-from-recipe``
-option allows the recipe to copy files and directories into your application.
-
-The instructions defined in this ``manifest.json`` file are also used by Symfony
-Flex when uninstalling dependencies (e.g. ``composer remove mailer``) to undo
-all changes. This means that Flex can remove the SwiftmailerBundle from the
-application, delete the ``MAILER_URL`` environment variable and any other file
-and directory created by this recipe.
+remember names (``composer require mailer`` vs ``composer require
+symfony/swiftmailer-bundle``). The ``bundles`` option tells Flex in which
+environments this bundle should be enabled automatically (``all`` in this
+case). The ``env`` option makes Flex to add new environment variables to the
+application. Finally, the ``copy-from-recipe`` option allows the recipe to copy
+files and directories into your application.
+
+The instructions defined in this ``manifest.json`` file are also used by
+Symfony Flex when uninstalling dependencies (e.g. ``composer remove mailer``)
+to undo all changes. This means that Flex can remove the SwiftmailerBundle from
+the application, delete the ``MAILER_URL`` environment variable and any other
+file and directory created by this recipe.
 
 Symfony Flex recipes are contributed by the community and they are stored in
 two public repositories:
 
 * `Main recipe repository`_, is a curated list of recipes for high quality and
   maintained packages. Symfony Flex only looks in this repository by default.
-* `Contrib recipe repository`_, contains all the recipes created by the community.
-  All of them are guaranteed to work, but their associated packages could be
-  unmaintained. Symfony Flex ignores these recipes by default, but you can execute
-  this command to start using them in your project:
+
+* `Contrib recipe repository`_, contains all the recipes created by the
+  community. All of them are guaranteed to work, but their associated packages
+  could be unmaintained. Symfony Flex ignores these recipes by default, but you
+  can execute this command to start using them in your project:
 
   .. code-block:: terminal
 
@@ -103,9 +110,9 @@ Using Symfony Flex in New Applications
 --------------------------------------
 
 Symfony has published a new "skeleton" project, which is a minimal Symfony
-project recommended to create new applications. This "skeleton" already includes
-Symfony Flex as a dependency, so you can create a new Flex-enabled Symfony
-application executing the following command:
+project recommended to create new applications. This "skeleton" already
+includes Symfony Flex as a dependency. This means you can create a new Flex-enabled
+Symfony application by executing the following command:
 
 .. code-block:: terminal
 
@@ -114,7 +121,8 @@ application executing the following command:
 .. note::
 
     The use of the Symfony Installer to create new applications is no longer
-    recommended since Symfony 3.3. Use Composer ``create-project`` command instead.
+    recommended since Symfony 3.3. Use Composer ``create-project`` command
+    instead.
 
 Upgrading Existing Applications to Flex
 ---------------------------------------
@@ -144,29 +152,42 @@ following directory structure, which is the same used by default in Symfony 4:
 
 This means that installing the ``symfony/flex`` dependency in your application
 is not enough. You must also upgrade the directory structure to the one showed
-above. Sadly, there's no automatic tool to make this upgrade, so you must follow
-these manual steps:
-
-#. Create a new empty Symfony application (``composer create-project symfony/skeleton my-project-flex``)
-#. Copy the ``require`` and ``require-dev`` dependencies defined in your original
-   project's ``composer.json`` file to the ``composer.json`` file of the new project.
-#. Install the dependencies in the new project executing ``composer install``. This
-   will make Symfony Flex generate all the configuration files in ``config/packages/``
+above. There's no automatic tool to make this upgrade, so you must follow these
+manual steps:
+
+#. Create a new empty Symfony application (``composer create-project
+   symfony/skeleton my-project-flex``)
+
+#. Merge the ``require`` and ``require-dev`` dependencies defined in your
+   original project's ``composer.json`` file to the ``composer.json`` file of the
+   new project (don't copy the ``symfony/symfony`` dependency, but add the
+   relevant components you are effectively using in your project).
+
+#. Install the dependencies in the new project executing ``composer install``.
+   This will make Symfony Flex generate all the configuration files in
+   ``config/packages/``
+
 #. Review the generated ``config/packages/*.yaml`` files and make any needed
-   changes according to the configuration defined in the ``app/config/config_*.yml``
-   file of your original project. Beware that this is the most time-consuming
-   and error-prone step of the upgrade process.
-#. Move the original parameters defined in ``app/config/parameters.*.yml`` to the
-   new ``config/services.yaml`` and ``.env`` files depending on your needs.
+   changes according to the configuration defined in the
+   ``app/config/config_*.yml`` file of your original project. Beware that this is
+   the most time-consuming and error-prone step of the upgrade process.
+
+#. Move the original parameters defined in ``app/config/parameters.*.yml`` to
+   the new ``config/services.yaml`` and ``.env`` files depending on your needs.
+
 #. Move the original source code from ``src/{App,...}Bundle/`` to ``src/`` and
-   update the namespaces of every PHP file (advanced IDEs can do this automatically).
-#. Move the original templates from ``templates/`` to ``templates/``
-#. Make any other change needed by your application. For example, if your original
-   ``public/app_*.php`` front controllers were customized, add those changes to the
-   new ``public/index.php`` controller.
+   update the namespaces of every PHP file (advanced IDEs can do this
+   automatically).
+
+#. Move the original templates from ``app/Resources/views/`` to ``templates/``
+
+#. Make any other change needed by your application. For example, if your
+   original ``web/app_*.php`` front controllers were customized, add those changes
+   to the new ``public/index.php`` controller.
 
 .. _`Symfony Flex`: https://github.com/symfony/flex
 .. _`Symfony Installer`: https://github.com/symfony/symfony-installer
+.. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
 .. _`Main recipe repository`: https://github.com/symfony/recipes
 .. _`Contrib recipe repository`: https://github.com/symfony/recipes-contrib
 .. _`Symfony Recipes documentation`: https://github.com/symfony/recipes/blob/master/README.rst

setup/homestead.rst

@@ -48,19 +48,19 @@ configuration:
 
     # ...
     sites:
-        - map: symfony-demo.dev
+        - map: symfony-demo.test
           to: /home/vagrant/projects/symfony_demo/web
           type: symfony
 
 The ``type`` option tells Homestead to use the Symfony nginx configuration.
 
-At last, edit the hosts file on your local machine to map ``symfony-demo.dev``
+At last, edit the hosts file on your local machine to map ``symfony-demo.test``
 to ``192.168.10.10`` (which is the IP used by Homestead)::
 
     # /etc/hosts (unix) or C:\Windows\System32\drivers\etc\hosts (Windows)
-    192.168.10.10 symfony-demo.dev
+    192.168.10.10 symfony-demo.test
 
-Now, navigate to ``http://symfony-demo.dev`` in your web browser and enjoy
+Now, navigate to ``http://symfony-demo.test`` in your web browser and enjoy
 developing your Symfony application!
 
 .. seealso::