Merge branch '2.4'

Conflicts:
	book/routing.rst
	components/routing/introduction.rst

Author: weaverryan

book/testing.rst

@@ -21,7 +21,7 @@ it has its own excellent `documentation`_.
     needed to test the Symfony core code itself.
 
 Each test - whether it's a unit test or a functional test - is a PHP class
-that should live in the `Tests/` subdirectory of your bundles. If you follow
+that should live in the ``Tests/`` subdirectory of your bundles. If you follow
 this rule, then you can run all of your application's tests with the following
 command:
 
@@ -783,47 +783,70 @@ PHPUnit Configuration
 ~~~~~~~~~~~~~~~~~~~~~
 
 Each application has its own PHPUnit configuration, stored in the
-``phpunit.xml.dist`` file. You can edit this file to change the defaults or
-create a ``phpunit.xml`` file to tweak the configuration for your local machine.
+``app/phpunit.xml.dist`` file. You can edit this file to change the defaults or
+create an ``app/phpunit.xml`` file to setup a configuration for your local
+machine only.
 
 .. tip::
 
-    Store the ``phpunit.xml.dist`` file in your code repository, and ignore the
+    Store the ``phpunit.xml.dist`` file in your code repository and ignore the
     ``phpunit.xml`` file.
 
-By default, only the tests stored in "standard" bundles are run by the
-``phpunit`` command (standard being tests in the ``src/*/Bundle/Tests`` or
-``src/*/Bundle/*Bundle/Tests`` directories) But you can easily add more
-directories. For instance, the following configuration adds the tests from
-the installed third-party bundles:
+By default, only the tests from your own custom bundles stored in the standard
+directories ``src/*/*Bundle/Tests`` or ``src/*/Bundle/*Bundle/Tests`` are run
+by the ``phpunit`` command, as configured in the ``phpunit.xml.dist`` file:
 
 .. code-block:: xml
 
-    <!-- hello/phpunit.xml.dist -->
-    <testsuites>
-        <testsuite name="Project Test Suite">
-            <directory>../src/*/*Bundle/Tests</directory>
-            <directory>../src/Acme/Bundle/*Bundle/Tests</directory>
-        </testsuite>
-    </testsuites>
+    <!-- app/phpunit.xml.dist -->
+    <phpunit>
+        <!-- ... -->
+        <testsuites>
+            <testsuite name="Project Test Suite">
+                <directory>../src/*/*Bundle/Tests</directory>
+                <directory>../src/*/Bundle/*Bundle/Tests</directory>
+            </testsuite>
+        </testsuites>
+        <!-- ... -->
+    </phpunit>
+
+But you can easily add more directories. For instance, the following
+configuration adds tests from a custom ``lib/tests`` directory:
+
+.. code-block:: xml
+
+    <!-- app/phpunit.xml.dist -->
+    <phpunit>
+        <!-- ... -->
+        <testsuites>
+            <testsuite name="Project Test Suite">
+                <!-- ... --->
+                <directory>../lib/tests</directory>
+            </testsuite>
+        </testsuites>
+        <!-- ... --->
+    </phpunit>
 
 To include other directories in the code coverage, also edit the ``<filter>``
 section:
 
 .. code-block:: xml
 
-    <!-- ... -->
-    <filter>
-        <whitelist>
-            <directory>../src</directory>
-            <exclude>
-                <directory>../src/*/*Bundle/Resources</directory>
-                <directory>../src/*/*Bundle/Tests</directory>
-                <directory>../src/Acme/Bundle/*Bundle/Resources</directory>
-                <directory>../src/Acme/Bundle/*Bundle/Tests</directory>
-            </exclude>
-        </whitelist>
-    </filter>
+    <!-- app/phpunit.xml.dist -->
+    <phpunit>
+        <!-- ... -->
+        <filter>
+            <whitelist>
+                <!-- ... -->
+                <directory>../lib</directory>
+                <exclude>
+                    <!-- ... -->
+                    <directory>../lib/tests</directory>
+                </exclude>
+            </whitelist>
+        </filter>
+        <!-- ... --->
+    </phpunit>
 
 Learn more
 ----------

components/form/type_guesser.rst

@@ -74,7 +74,7 @@ that the type guesser cannot guess the type.
 
 The ``TypeGuess`` constructor requires 3 options:
 
-* The type name (one of the :doc:`form types </reference/forms/types`);
+* The type name (one of the :doc:`form types </reference/forms/types>`);
 * Additional options (for instance, when the type is ``entity``, you also
   want to set the ``class`` option). If no types are guessed, this should be
   set to an empty array;

components/routing/introduction.rst

@@ -138,22 +138,23 @@ Using Prefixes
 
 You can add routes or other instances of
 :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection.
-This way you can build a tree of routes. Additionally you can define a prefix,
-default requirements, default options and host to all routes of a subtree with
-the :method:`Symfony\\Component\\Routing\\RouteCollection::addPrefix` method::
+This way you can build a tree of routes. Additionally you can define a prefix
+and default values for the parameters, requirements, options, schemes and the
+host to all routes of a subtree using methods provided by the
+``RouteCollection`` class::
 
     $rootCollection = new RouteCollection();
 
     $subCollection = new RouteCollection();
     $subCollection->add(...);
     $subCollection->add(...);
-    $subCollection->addPrefix(
-        '/prefix', // prefix
-        array(), // requirements
-        array(), // options
-        'admin.example.com', // host
-        array('https') // schemes
-    );
+    $subCollection->addPrefix('/prefix');
+    $subCollection->addDefaults(array(...));
+    $subCollection->addRequirements(array(...));
+    $subCollection->addOptions(array(...));
+    $subCollection->setHost('admin.example.com');
+    $subCollection->setMethods(array('POST'));
+    $subCollection->setSchemes(array('https'));
 
     $rootCollection->addCollection($subCollection);
 
@@ -170,7 +171,9 @@ with this class via its constructor::
         $host = 'localhost',
         $scheme = 'http',
         $httpPort = 80,
-        $httpsPort = 443
+        $httpsPort = 443,
+        $path = '/',
+        $queryString = ''
     )
 
 .. _components-routing-http-foundation:

components/security/authentication.rst

@@ -204,8 +204,8 @@ own, it just needs to follow these rules:
    :method:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface::isPasswordValid`
    must first of all make sure the password is not too long, i.e. the password length is no longer
    than 4096 characters. This is for security reasons (see `CVE-2013-5750`_), and you can use the
-   :method:`Symfony\\Component\\Security\\Core\\Encoder\\BasePasswordEncoder::isPasswordTooLong`_
-   method for this check:
+   :method:`Symfony\\Component\\Security\\Core\\Encoder\\BasePasswordEncoder::isPasswordTooLong`
+   method for this check::
 
        use Symfony\Component\Security\Core\Exception\BadCredentialsException;
 

cookbook/email/cloud.rst

@@ -7,7 +7,7 @@ How to use the Cloud to Send Emails
 Requirements for sending emails from a production system differ from your
 development setup as you don't want to be limited in the number of emails,
 the sending rate or the sender address. Thus,
-:doc:`using Gmail </cookbook/email/gmail>`_ or similar services is not an
+:doc:`using Gmail </cookbook/email/gmail>` or similar services is not an
 option. If setting up and maintaining your own reliable mail server causes
 you a headache there's a simple solution: Leverage the cloud to send your
 emails.

cookbook/form/dynamic_form_modification.rst

@@ -471,6 +471,7 @@ sport like this::
     // src/Acme/DemoBundle/Form/Type/SportMeetupType.php
     namespace Acme\DemoBundle\Form\Type;
 
+    use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
@@ -481,7 +482,10 @@ sport like this::
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
-                ->add('sport', 'entity', array(...))
+                ->add('sport', 'entity', array(
+                    'class'       => 'AcmeDemoBundle:Sport',
+                    'empty_value' => '',
+                ))
             ;
 
             $builder->addEventListener(
@@ -492,12 +496,19 @@ sport like this::
                     // this would be your entity, i.e. SportMeetup
                     $data = $event->getData();
 
-                    $positions = $data->getSport()->getAvailablePositions();
+                    $sport = $data->getSport();
+                    $positions = null === $sport ? array() : $sport->getAvailablePositions();
 
-                    $form->add('position', 'entity', array('choices' => $positions));
+                    $form->add('position', 'entity', array(
+                        'class'       => 'AcmeDemoBundle:Position',
+                        'empty_value' => '',
+                        'choices'     => $positions,
+                    ));
                 }
             );
         }
+
+        // ...
     }
 
 When you're building this form to display to the user for the first time,
@@ -530,21 +541,28 @@ The type would now look like::
     namespace Acme\DemoBundle\Form\Type;
 
     // ...
-    use Acme\DemoBundle\Entity\Sport;
     use Symfony\Component\Form\FormInterface;
+    use Acme\DemoBundle\Entity\Sport;
 
     class SportMeetupType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
-                ->add('sport', 'entity', array(...))
+                ->add('sport', 'entity', array(
+                    'class'       => 'AcmeDemoBundle:Sport',
+                    'empty_value' => '',
+                ));
             ;
 
-            $formModifier = function(FormInterface $form, Sport $sport) {
-                $positions = $sport->getAvailablePositions();
+            $formModifier = function(FormInterface $form, Sport $sport = null) {
+                $positions = null === $sport ? array() : $sport->getAvailablePositions();
 
-                $form->add('position', 'entity', array('choices' => $positions));
+                $form->add('position', 'entity', array(
+                    'class'       => 'AcmeDemoBundle:Position',
+                    'empty_value' => '',
+                    'choices'     => $positions,
+                ));
             };
 
             $builder->addEventListener(
@@ -570,17 +588,78 @@ The type would now look like::
                 }
             );
         }
+
+        // ...
+    }
+
+You can see that you need to listen on these two events and have different
+callbacks only because in two different scenarios, the data that you can use is
+available in different events. Other than that, the listeners always perform
+exactly the same things on a given form.
+
+One piece that is still missing is the client-side updating of your form after
+the sport is selected. This should be handled by making an AJAX call back to
+your application. Assume that you have a sport meetup creation controller::
+
+    // src/Acme/DemoBundle/Controller/MeetupController.php
+    namespace Acme\DemoBundle\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Component\HttpFoundation\Request;
+    use Acme\DemoBundle\Entity\SportMeetup;
+    use Acme\DemoBundle\Form\Type\SportMeetupType;
+    // ...
+
+    class MeetupController extends Controller
+    {
+        public function createAction(Request $request)
+        {
+            $meetup = new SportMeetup();
+            $form = $this->createForm(new SportMeetupType(), $meetup);
+            $form->handleRequest($request);
+            if ($form->isValid()) {
+                // ... save the meetup, redirect etc.
+            }
+
+            return $this->render(
+                'AcmeDemoBundle:Meetup:create.html.twig',
+                array('form' => $form->createView())
+            );
+        }
+
+        // ...
     }
 
-You can see that you need to listen on these two events and have different callbacks
-only because in two different scenarios, the data that you can use is available in different events.
-Other than that, the listeners always perform exactly the same things on a given form.
+The associated template uses some JavaScript to update the ``position`` form
+field according to the current selection in the ``sport`` field:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {# src/Acme/DemoBundle/Resources/views/Meetup/create.html.twig #}
+        {{ form_start(form) }}
+            {{ form_row(form.sport) }}    {# <select id="meetup_sport" ... #}
+            {{ form_row(form.position) }} {# <select id="meetup_position" ... #}
+            {# ... #}
+        {{ form_end(form) }}
+
+        .. include:: /cookbook/form/dynamic_form_modification_ajax_js.rst.inc
+
+    .. code-block:: html+php
+
+        <!-- src/Acme/DemoBundle/Resources/views/Meetup/create.html.php -->
+        <?php echo $view['form']->start($form) ?>
+            <?php echo $view['form']->row($form['sport']) ?>    <!-- <select id="meetup_sport" ... -->
+            <?php echo $view['form']->row($form['position']) ?> <!-- <select id="meetup_position" ... -->
+            <!-- ... -->
+        <?php echo $view['form']->end($form) ?>
+
+        .. include:: /cookbook/form/dynamic_form_modification_ajax_js.rst.inc
 
-One piece that may still be missing is the client-side updating of your form
-after the sport is selected. This should be handled by making an AJAX call
-back to your application. In that controller, you can submit your form, but
-instead of processing it, simply use the submitted form to render the updated
-fields. The response from the AJAX call can then be used to update the view.
+The major benefit of submitting the whole form to just extract the updated
+``position`` field is that no additional server-side code is needed; all the
+code from above to generate the submitted form can be reused.
 
 .. _cookbook-dynamic-form-modification-suppressing-form-validation:
 

cookbook/form/dynamic_form_modification_ajax_js.rst.inc

@@ -0,0 +1,25 @@
+<script>
+var $sport = $('#meetup_sport');
+// When sport gets selected ...
+$sport.change(function(){
+  // ... retrieve the corresponding form.
+  var $form = $(this).closest('form');
+  // Simulate form data, but only include the selected sport value.
+  var data = {};
+  data[$sport.attr('name')] = $sport.val();
+  // Submit data via AJAX to the form's action path.
+  $.ajax({
+    url : $form.attr('action'),
+    type: $form.attr('method'),
+    data : data,
+    success: function(html) {
+      // Replace current position field ...
+      $('#meetup_position').replaceWith(
+        // ... with the returned one from the AJAX response.
+        $(html).find('#meetup_position')
+      );
+      // Position field now displays the appropriate positions.
+    }
+  });
+});
+</script>