Merge branch '4.0'

* 4.0:
  Added a short section about registering commands
  Use create-project instead of require to create reproducer project
  Explain which branch to select for Pull Requests
  Removed some wrong mentions to AppBundle
  Better explain how to inject mailers different than the default one
  Missing the obvious <?php
  SF 4+ does not rely on Command inheritance anymore
  Update email field length in annotation
  Update upload_file.rst
  Clarify Symfony Console option conventions
  Clarify how to use short options with values.
  Use the long array syntax
  the bundle no longer recommend for Sf4
  Fixes deprecated ProcessBuilder usage

Author: javiereguiluz

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+<!--
+
+If your pull request fixes a BUG, use the oldest maintained branch that contains
+the bug (see https://symfony.com/roadmap for the list of maintained branches).
+
+If your pull request documents a NEW FEATURE, use the same Symfony branch where
+the feature was introduced (and `master` for features of unreleased versions).
+
+-->

components/console/helpers/processhelper.rst

@@ -14,7 +14,7 @@ a very verbose verbosity (e.g. -vv)::
     use Symfony\Component\Process\ProcessBuilder;
 
     $helper = $this->getHelper('process');
-    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+    $process = new Process(array('figlet', 'Symfony'));
 
     $helper->run($output, $process);
 
@@ -55,7 +55,7 @@ There are three ways to use the process helper:
     use Symfony\Component\Process\ProcessBuilder;
 
     // ...
-    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+    $process = new Process(array('figlet', 'Symfony'));
 
     $helper->run($output, $process);
 

console.rst

@@ -69,25 +69,23 @@ method. Then you can optionally define a help message and the
         ;
     }
 
+Registering the Command
+-----------------------
+
+Symfony commands must be registered as services and :doc:`tagged </service_container/tags>`
+with the ``console.command`` tag. If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
+
 Executing the Command
 ---------------------
 
-Symfony registers any PHP class extending :class:`Symfony\\Component\\Console\\Command\\Command`
-as a console command automatically. So you can now execute this command in the
-terminal:
+After configuring and registering the command, you can execute it in the terminal:
 
 .. code-block:: terminal
 
     $ php bin/console app:create-user
 
-.. note::
-
-    If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-    your command classes are automatically registered as services.
-
-    You can also manually register your command as a service by configuring the service
-    and :doc:`tagging it </service_container/tags>` with ``console.command``.
-
 As you might expect, this command will do nothing as you didn't write any logic
 yet. Add your own logic inside the ``execute()`` method, which has access to the
 input stream (e.g. options and arguments) and the output stream (to write

console/input.rst

@@ -174,6 +174,11 @@ flag:
                 1
             );
 
+Note that to comply with the `docopt standard`_, long options can specify their
+values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
+``--iterations=5``), but short options can only use white spaces or no
+separation at all (e.g. ``-i 5`` or ``-i5``).
+
 There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
@@ -184,8 +189,8 @@ There are four option variants you can use:
     behavior of options;
 
 ``InputOption::VALUE_REQUIRED``
-    This value is required (e.g. ``--iterations=5``), the option itself is
-    still optional;
+    This value is required (e.g. ``--iterations=5`` or ``-i5``), the option
+    itself is still optional;
 
 ``InputOption::VALUE_OPTIONAL``
     This option may or may not have a value (e.g. ``--yell`` or
@@ -211,3 +216,14 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
     when the option was used without a value (``command --language``) or when
     it wasn't used at all (``command``). In both cases, the value retrieved for
     the option will be ``null``.
+
+.. caution::
+
+    While it is possible to separate an option from its value with a white space,
+    using this form leads to an ambiguity should the option appear before the
+    command name. For example, ``php bin/console --iterations 5 app:greet Fabien``
+    is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
+    this situation, always place options after the command name, or avoid using
+    a space to separate the option name from its value.
+
+.. _`docopt standard`: http://docopt.org/

contributing/code/reproducer.rst

@@ -39,7 +39,7 @@ a PHP script, it's better to reproduce the bug by creating a new project. To do
 
 .. code-block:: terminal
 
-    $ composer require symfony/skeleton bug_app
+    $ composer create-project symfony/skeleton bug_app
 
 2. Now you must add the minimum amount of code to reproduce the bug. This is the
    trickiest part and it's explained a bit more later.

controller/upload_file.rst

@@ -271,7 +271,7 @@ Then, define a service for this class:
 
             App\Service\FileUploader:
                 arguments:
-                    $targetDir: '%brochures_directory%'
+                    $targetDirectory: '%brochures_directory%'
 
     .. code-block:: xml
 

event_dispatcher.rst

@@ -91,7 +91,7 @@ using a special "tag":
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="AppBundle\EventListener\ExceptionListener">
+                <service id="App\EventListener\ExceptionListener">
                     <tag name="kernel.event_listener" event="kernel.exception" />
                 </service>
             </services>

http_cache/esi.rst

@@ -139,7 +139,7 @@ matter), Symfony uses the standard ``render`` helper to configure ESI tags:
         <!-- you can use a controller reference -->
         <?php echo $view['actions']->render(
             new Symfony\Component\HttpKernel\Controller\ControllerReference(
-                'AppBundle:News:latest',
+                'App\Controller\NewsController::latest',
                 array('maxPerPage' => 5)
             ),
             array('strategy' => 'esi')

page_creation.rst

@@ -43,6 +43,7 @@ Suppose you want to create a page - ``/lucky/number`` - that generates a lucky (
 random) number and prints it. To do that, create a "Controller class" and a
 "controller" method inside of it::
 
+    <?php
     // src/Controller/LuckyController.php
     namespace App\Controller;
 
@@ -281,7 +282,7 @@ project:
 
 ``src/``
     All your PHP code lives here.
-    
+
 ``templates/``
     All your Twig templates live here.
 

reference/configuration/swiftmailer.rst

@@ -344,7 +344,7 @@ key (the default mailer is identified by the ``default_mailer`` option):
             ),
         ));
 
-Each mailer is registered as a service::
+Each mailer is registered automatically as a service with these IDs::
 
     // ...
 
@@ -362,3 +362,70 @@ Each mailer is registered as a service::
     When configuring multiple mailers, options must be placed under the
     appropriate mailer key of the configuration instead of directly under the
     ``swiftmailer`` key.
+
+When using :ref:`autowiring <services-autowire>` only the default mailer is
+injected when type-hinting some argument with the ``\Swift_Mailer`` class. If
+you need to inject a different mailer in some service, use any of these
+alternatives based on the :ref:`service binding <services-binding>` feature:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            _defaults:
+                bind:
+                    # this injects the second mailer when type-hinting constructor arguments with \Swift_Mailer
+                    \Swift_Mailer: '@swiftmailer.mailer.second_mailer'
+                    # this injects the second mailer when a service constructor argument is called $specialMailer
+                    $specialMailer: '@swiftmailer.mailer.second_mailer'
+
+            App\Some\Service:
+                # this injects the second mailer only for this argument of this service
+                $differentMailer: '@swiftmailer.mailer.second_mailer'
+
+            # ...
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <defaults autowire="true" autoconfigure="true" public="false">
+                    <!-- this injects the second mailer when type-hinting constructor arguments with \Swift_Mailer -->
+                    <bind key="\Swift_Mailer">@swiftmailer.mailer.second_mailer</bind>
+                    <!-- this injects the second mailer when a service constructor argument is called $specialMailer -->
+                    <bind key="$specialMailer">@swiftmailer.mailer.second_mailer</bind>
+                </defaults>
+
+                <service id="App\Some\Service">
+                    <!-- this injects the second mailer only for this argument of this service -->
+                    <argument key="$differentMailer">@swiftmailer.mailer.second_mailer</argument>
+                </service>
+
+                <!-- ... -->
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        use App\Some\Service;
+        use Symfony\Component\DependencyInjection\Reference;
+        use Psr\Log\LoggerInterface;
+
+        $container->register(Service::class)
+            ->setPublic(true)
+            ->setBindings(array(
+                // this injects the second mailer when this service type-hints constructor arguments with \Swift_Mailer
+                \Swift_Mailer => '@swiftmailer.mailer.second_mailer',
+                // this injects the second mailer when this service has a constructor argument called $specialMailer
+                '$specialMailer' => '@swiftmailer.mailer.second_mailer',
+            ))
+        ;