Merge branch '2.7'

* 2.7: (28 commits)
  Fixing typo thanks to xabbuh
  Add missing comma in array
  Removed unneeded spaces
  Updated as per discussion
  Updated according to comment and changed to AppBundle
  Added configuration of the your_api_key_user_provider as user provider
  fixed typo (acme -> app)
  Fix code examples
  Fix typo: missing of
  Fix typo: missing space
  Fix typo: Fabien => World
  Adding reference link
  Quick proofread of the email cookbook
  Small grammar-ish fix
  Remove horizontal scrollbar
  Fix typos
  Fix typo, remove horizontal scrollbar
  Set twig service as private
  added Kévin as a merger for the Serializer component
  Fix typo: looks => look
  ...

best_practices/business-logic.rst

@@ -140,9 +140,12 @@ the class namespace as a parameter:
     # app/config/services.yml
 
     # service definition with class namespace as parameter
+    parameters:
+        slugger.class: AppBundle\Utils\Slugger
+
     services:
         app.slugger:
-            class: AppBundle\Utils\Slugger
+            class: "%slugger.class%"
 
 This practice is cumbersome and completely unnecessary for your own services:
 

best_practices/configuration.rst

@@ -6,6 +6,8 @@ and security credentials) and different environments (development, production).
 That's why Symfony recommends that you split the application configuration into
 three parts.
 
+.. _config-parameters.yml:
+
 Infrastructure-Related Configuration
 ------------------------------------
 

components/class_loader/class_map_generator.rst

@@ -45,7 +45,7 @@ Generating a Class Map
 ----------------------
 
 To generate the class map, simply pass the root directory of your class files
-to the :method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::createMap``
+to the :method:`Symfony\\Component\\ClassLoader\\ClassMapGenerator::createMap`
 method::
 
     use Symfony\Component\ClassLoader\ClassMapGenerator;
@@ -115,7 +115,10 @@ the same as in the example above)::
 
     use Symfony\Component\ClassLoader\ClassMapGenerator;
 
-    ClassMapGenerator::dump(array(__DIR__.'/library/bar', __DIR__.'/library/foo'), __DIR__.'/class_map.php');
+    ClassMapGenerator::dump(
+        array(__DIR__.'/library/bar', __DIR__.'/library/foo'),
+        __DIR__.'/class_map.php'
+    );
 
 .. _`PSR-0`: http://www.php-fig.org/psr/psr-0
 .. _`PSR-4`: http://www.php-fig.org/psr/psr-4

components/config/definition.rst

@@ -500,7 +500,7 @@ By changing a string value into an associative array with ``name`` as the key::
             ->arrayNode('connection')
                 ->beforeNormalization()
                     ->ifString()
-                    ->then(function($v) { return array('name'=> $v); })
+                    ->then(function ($v) { return array('name' => $v); })
                 ->end()
                 ->children()
                     ->scalarNode('name')->isRequired()

components/console/changing_default_command.rst

@@ -51,7 +51,7 @@ This will print the following to the command line:
 
 .. code-block:: text
 
-    Hello Fabien
+    Hello World
 
 .. tip::
 

components/console/helpers/debug_formatter.rst

@@ -51,8 +51,8 @@ display information that the program is started::
 
     $output->writeln($debugFormatter->start(
         spl_object_hash($process),
-        'Some process description')
-    );
+        'Some process description'
+    ));
 
     $process->run();
 
@@ -68,7 +68,7 @@ You can tweak the prefix using the third argument::
         spl_object_hash($process),
         'Some process description',
         'STARTED'
-    );
+    ));
     // will output:
     //  STARTED Some process description
 

components/console/helpers/dialoghelper.rst

@@ -230,7 +230,7 @@ this set the seventh argument to ``true``::
         true // enable multiselect
     );
 
-    $selectedColors = array_map(function($c) use ($colors) {
+    $selectedColors = array_map(function ($c) use ($colors) {
         return $colors[$c];
     }, $selected);
 

components/console/helpers/questionhelper.rst

@@ -41,6 +41,24 @@ The second argument to
 is the default value to return if the user doesn't enter any input. Any other
 input will ask the same question again.
 
+.. tip::
+
+    You can customize the regex used to check if the answer means "yes" in the
+    third argument of the constructor. For instance, to allow anything that
+    starts with either ``y`` or ``j``, you would set it to::
+
+        $question = new ConfirmationQuestion(
+            'Continue with this action?',
+            false,
+            '/^(y|j)/i'
+        );
+
+    The regex defaults to ``/^y/i``.
+
+    .. versionadded:: 2.7
+        The regex argument was introduced in Symfony 2.7. Before, only answers
+        starting with ``y`` were considered as "yes".
+
 Asking the User for Information
 -------------------------------
 
@@ -90,7 +108,7 @@ option is the default one.
 If the user enters an invalid string, an error message is shown and the user
 is asked to provide the answer another time, until they enter a valid string
 or reach the maximum number of attempts. The default value for the maximum number
-of attempts is ``null``, which means infinite number attempts. You can define
+of attempts is ``null``, which means infinite number of attempts. You can define
 your own error message using
 :method:`Symfony\\Component\\Console\\Question\\ChoiceQuestion::setErrorMessage`.
 

components/console/introduction.rst

@@ -459,9 +459,11 @@ method::
 
             $command = $application->find('demo:greet');
             $commandTester = new CommandTester($command);
-            $commandTester->execute(
-                array('command' => $command->getName(), 'name' => 'Fabien', '--iterations' => 5)
-            );
+            $commandTester->execute(array(
+                'command'      => $command->getName(),
+                'name'         => 'Fabien',
+                '--iterations' => 5,
+            ));
 
             $this->assertRegExp('/Fabien/', $commandTester->getDisplay());
         }

components/expression_language/syntax.rst

@@ -259,7 +259,7 @@ For example::
     $inGroup = $language->evaluate(
         'user.group in ["human_resources", "marketing"]',
         array(
-            'user' => $user
+            'user' => $user,
         )
     );
 

components/var_dumper/introduction.rst

@@ -62,6 +62,17 @@ current PHP SAPI:
     You'll also learn how to change the format or redirect the output to
     wherever you want.
 
+.. tip::
+
+    In order to have the ``dump()`` function always available when running
+    any PHP code, you can install it globally on your computer:
+
+    #. Run ``composer global require symfony/var-dumper``;
+    #. Add ``auto_prepend_file = ${HOME}/.composer/vendor/autoload.php``
+       to your ``php.ini`` file;
+    #. From time to time, run ``composer global update`` to have the latest
+       bug fixes.
+
 DebugBundle and Twig Integration
 --------------------------------
 

contributing/code/core_team.rst

@@ -57,7 +57,10 @@ Active Core Members
   * **Christophe Coevoet** (:merger:`stof`) can merge into the BrowserKit_,
     Config_, Console_, DependencyInjection_, DomCrawler_, EventDispatcher_,
     HttpFoundation_, HttpKernel_, Serializer_, Stopwatch_, DoctrineBridge_,
-    MonologBridge_, and TwigBridge_ components.
+    MonologBridge_, and TwigBridge_ components;
+
+  * **Kévin Dunglas** (:merger:`dunglas`) can merge into the Serializer_
+    component.
 
 * **Deciders** (``@symfony/deciders`` on GitHub):
 

cookbook/configuration/external_parameters.rst

@@ -98,14 +98,6 @@ You can now reference these parameters wherever you need them.
             )
         ));
 
-.. note::
-
-    Even in debug mode, setting or changing an environment variable
-    requires your cache to be cleared to make the parameter available.
-    In debug mode, this is required since only a change to a configuration
-    file that is loaded by Symfony triggers your configuration to be
-    re-evaluated.
-
 Constants
 ---------
 

cookbook/email/email.rst

@@ -7,43 +7,36 @@ How to Send an Email
 Sending emails is a classic task for any web application and one that has
 special complications and potential pitfalls. Instead of recreating the wheel,
 one solution to send emails is to use the SwiftmailerBundle, which leverages
-the power of the `Swift Mailer`_ library.
-
-.. note::
-
-    Don't forget to enable the bundle in your kernel before using it::
-
-        public function registerBundles()
-        {
-            $bundles = array(
-                // ...
-
-                new Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle(),
-            );
-
-            // ...
-        }
+the power of the `Swift Mailer`_ library. This bundle comes with the Symfony
+Standard Edition.
 
 .. _swift-mailer-configuration:
 
 Configuration
 -------------
 
-Before using Swift Mailer, be sure to include its configuration. The only
-mandatory configuration parameter is ``transport``:
+To use Swift Mailer, you'll need to configure it for your mail server.
+
+.. tip::
+
+    Instead of setting up/using your own mail server, you may want to use
+    a hosted mail provider such as `Mandrill`_, `SendGrid`_, `Amazon SES`_
+    or others. These give you an SMTP server, username and password (sometimes
+    called keys) that can be used with the Swift Mailer configuration.
+
+In a standard Symfony installation, some ``swiftmailer`` configuration is
+already included:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # app/config/config.yml
         swiftmailer:
-            transport:  smtp
-            encryption: ssl
-            auth_mode:  login
-            host:       smtp.gmail.com
-            username:   your_username
-            password:   your_password
+            transport: "%mailer_transport%"
+            host:      "%mailer_host%"
+            username:  "%mailer_user%"
+            password:  "%mailer_password%"
 
     .. code-block:: xml
 
@@ -55,27 +48,24 @@ mandatory configuration parameter is ``transport``:
         -->
 
         <swiftmailer:config
-            transport="smtp"
-            encryption="ssl"
-            auth-mode="login"
-            host="smtp.gmail.com"
-            username="your_username"
-            password="your_password" />
+            transport="%mailer_transport%"
+            host="%mailer_host%"
+            username="%mailer_user%"
+            password="%mailer_password%" />
 
     .. code-block:: php
 
         // app/config/config.php
         $container->loadFromExtension('swiftmailer', array(
-            'transport'  => "smtp",
-            'encryption' => "ssl",
-            'auth_mode'  => "login",
-            'host'       => "smtp.gmail.com",
-            'username'   => "your_username",
-            'password'   => "your_password",
+            'transport'  => "%mailer_transport%",
+            'host'       => "%mailer_host%",
+            'username'   => "%mailer_user%",
+            'password'   => "%mailer_password%",
         ));
 
-The majority of the Swift Mailer configuration deals with how the messages
-themselves should be delivered.
+These values (e.g. ``%mailer_transport%``), are reading from the parameters
+that are set in the :ref:`parameters.yml <config-parameters.yml>` file. You
+can modify the values in that file, or set the values directly here.
 
 The following configuration attributes are available:
 
@@ -105,15 +95,27 @@ an email is pretty straightforward::
     {
         $mailer = $this->get('mailer');
         $message = $mailer->createMessage()
-            ->setSubject('Hello Email')
+            ->setSubject('You have Completed Registration!')
             ->setFrom('send@example.com')
             ->setTo('recipient@example.com')
             ->setBody(
                 $this->renderView(
-                    'HelloBundle:Hello:email.txt.twig',
+                    // app/Resources/views/Emails/registration.html.twig
+                    'Emails/registration.html.twig',
+                    array('name' => $name)
+                ),
+                'text/html'
+            )
+            /*
+             * If you also want to include a plaintext version of the message
+            ->addPart(
+                $this->renderView(
+                    'Emails/registration.txt.twig',
                     array('name' => $name)
-                )
+                ),
+                'text/plain'
             )
+            */
         ;
         $mailer->send($message);
 
@@ -138,3 +140,6 @@ of `Creating Messages`_ in great detail in its documentation.
 
 .. _`Swift Mailer`: http://swiftmailer.org/
 .. _`Creating Messages`: http://swiftmailer.org/docs/messages.html
+.. _`Mandrill`: https://mandrill.com/
+.. _`SendGrid`: https://sendgrid.com/
+.. _`Amazon SES`: http://aws.amazon.com/ses/

cookbook/routing/method_parameters.rst

@@ -18,17 +18,17 @@ delete it by matching on GET, PUT and DELETE.
         blog_show:
             path:     /blog/{slug}
             defaults: { _controller: AppBundle:Blog:show }
-            methods:   [GET]
+            methods:  [GET]
 
         blog_update:
             path:     /blog/{slug}
             defaults: { _controller: AppBundle:Blog:update }
-            methods:   [PUT]
+            methods:  [PUT]
 
         blog_delete:
             path:     /blog/{slug}
             defaults: { _controller: AppBundle:Blog:delete }
-            methods:   [DELETE]
+            methods:  [DELETE]
 
     .. code-block:: xml
 

cookbook/routing/slash_in_parameter.rst

@@ -24,6 +24,21 @@ a more permissive regex path.
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class DemoController
+        {
+            /**
+             * @Route("/hello/{name}", name="_hello", requirements={"name"=".+"})
+             */
+            public function helloAction($name)
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         _hello:
@@ -60,19 +75,4 @@ a more permissive regex path.
 
         return $collection;
 
-    .. code-block:: php-annotations
-
-        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
-
-        class DemoController
-        {
-            /**
-             * @Route("/hello/{name}", name="_hello", requirements={"name" = ".+"})
-             */
-            public function helloAction($name)
-            {
-                // ...
-            }
-        }
-
 That's it! Now, the ``{username}`` parameter can contain the ``/`` character.