Merge branch '2.3' into 2.4

book/forms.rst

@@ -13,7 +13,7 @@ learning the most important features of the form library along the way.
 
    The Symfony Form component is a standalone library that can be used outside
    of Symfony2 projects. For more information, see the `Symfony2 Form component`_
-   on Github.
+   on GitHub.
 
 .. index::
    single: Forms; Create a simple form
@@ -39,6 +39,7 @@ going to need to build a form. But before you begin, first focus on the generic
         {
             return $this->task;
         }
+
         public function setTask($task)
         {
             $this->task = $task;
@@ -48,7 +49,7 @@ going to need to build a form. But before you begin, first focus on the generic
         {
             return $this->dueDate;
         }
-        
+
         public function setDueDate(\DateTime $dueDate = null)
         {
             $this->dueDate = $dueDate;
@@ -172,7 +173,7 @@ helper functions:
 
 That's it! By printing ``form(form)``, each field in the form is rendered, along
 with a label and error message (if there is one). The ``form`` function also
-surrounds everything in the necessary HTML ``form`` tag. As easy as this is,
+surrounds everything in the necessary HTML ``<form>`` tag. As easy as this is,
 it's not very flexible (yet). Usually, you'll want to render each form field
 individually so you can control how the form looks. You'll learn how to do
 that in the ":ref:`form-rendering-template`" section.
@@ -267,7 +268,8 @@ possible paths:
    .. note::
 
       Redirecting a user after a successful form submission prevents the user
-      from being able to hit "refresh" and re-post the data.
+      from being able to hit the "Refresh" button of their browser and re-post
+      the data.
 
 .. index::
    single: Forms; Multiple Submit Buttons
@@ -566,7 +568,7 @@ First, we need to add the two buttons to the form::
 
 Then, we configure the button for returning to the previous step to run
 specific validation groups. In this example, we want it to suppress validation,
-so we set its ``validation_groups`` options to false::
+so we set its ``validation_groups`` option to false::
 
     $form = $this->createFormBuilder($task)
         // ...
@@ -979,10 +981,10 @@ to the ``form()`` or the ``form_start()`` helper:
 .. note::
 
     If the form's method is not GET or POST, but PUT, PATCH or DELETE, Symfony2
-    will insert a hidden field with the name "_method" that stores this method.
+    will insert a hidden field with the name ``_method`` that stores this method.
     The form will be submitted in a normal POST request, but Symfony2's router
-    is capable of detecting the "_method" parameter and will interpret the
-    request as PUT, PATCH or DELETE request. Read the cookbook chapter
+    is capable of detecting the ``_method`` parameter and will interpret it as
+    a PUT, PATCH or DELETE request. Read the cookbook chapter
     ":doc:`/cookbook/routing/method_parameters`" for more information.
 
 .. index::
@@ -1076,7 +1078,8 @@ the choice is ultimately up to you.
 
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('task')
+            $builder
+                ->add('task')
                 ->add('dueDate', null, array('mapped' => false))
                 ->add('save', 'submit');
         }
@@ -1316,8 +1319,7 @@ the ``cascade_validation`` option to ``TaskType``::
         ));
     }
 
-Render the ``Category`` fields in the same way
-as the original ``Task`` fields:
+Render the ``Category`` fields in the same way as the original ``Task`` fields:
 
 .. configuration-block::
 

book/routing.rst

@@ -1224,10 +1224,10 @@ Generating URLs
 ---------------
 
 The routing system should also be used to generate URLs. In reality, routing
-is a bi-directional system: mapping the URL to a controller+parameters and
+is a bidirectional system: mapping the URL to a controller+parameters and
 a route+parameters back to a URL. The
 :method:`Symfony\\Component\\Routing\\Router::match` and
-:method:`Symfony\\Component\\Routing\\Router::generate` methods form this bi-directional
+:method:`Symfony\\Component\\Routing\\Router::generate` methods form this bidirectional
 system. Take the ``blog_show`` example route from earlier::
 
     $params = $this->get('router')->match('/blog/my-blog-post');
@@ -1258,12 +1258,25 @@ route. With this information, any URL can easily be generated::
 
 .. note::
 
-    In controllers that extend Symfony's base
+    In controllers that don't extend Symfony's base
     :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller`,
-    you can use the
-    :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::generateUrl`
-    method, which calls the router service's
-    :method:`Symfony\\Component\\Routing\\Router::generate` method.
+    you can use the ``router`` service's
+    :method:`Symfony\\Component\\Routing\\Router::generate` method::
+
+        use Symfony\Component\DependencyInjection\ContainerAware;
+
+        class MainController extends ContainerAware
+        {
+            public function showAction($slug)
+            {
+                // ...
+
+                $url = $this->container->get('router')->generate(
+                    'blog_show',
+                    array('slug' => 'my-blog-post')
+                );
+            }
+        }
 
 In an upcoming section, you'll learn how to generate URLs from inside templates.
 
@@ -1352,19 +1365,19 @@ to ``generateUrl()``:
 
 .. note::
 
-    The host that's used when generating an absolute URL is the host of
-    the current ``Request`` object. This is detected automatically. But if
-    you generate absolute URLs for scripts run from the command line, this
-    won't work. But don't worry! Just see :doc:`/cookbook/console/sending_emails`
-    for details.
+    The host that's used when generating an absolute URL is automatically
+    detected using the current ``Request`` object. When generating absolute
+    URLs from outside the web context (for instance in a console command) this
+    doesn't work. See :doc:`/cookbook/console/sending_emails` to learn how to
+    solve this problem.
 
 Summary
 -------
 
 Routing is a system for mapping the URL of incoming requests to the controller
 function that should be called to process the request. It both allows you
 to specify beautiful URLs and keeps the functionality of your application
-decoupled from those URLs. Routing is a two-way mechanism, meaning that it
+decoupled from those URLs. Routing is a bidirectional mechanism, meaning that it
 should also be used to generate URLs.
 
 Learn more from the Cookbook

components/console/helpers/dialoghelper.rst

@@ -113,7 +113,7 @@ method::
         'Please enter the name of the bundle',
         function ($answer) {
             if ('Bundle' !== substr($answer, -6)) {
-                throw new \RunTimeException(
+                throw new \RuntimeException(
                     'The name of the bundle should be suffixed with \'Bundle\''
                 );
             }

components/serializer.rst

@@ -181,6 +181,37 @@ method on the normalizer definition::
 As a final result, the deserializer uses the ``first_name`` attribute as if
 it were ``firstName`` and uses the ``getFirstName`` and ``setFirstName`` methods.
 
+Using Callbacks to Serialize Properties with Object Instances
+-------------------------------------------------------------
+
+When serializing, you can set a callback to format a specific object property::
+
+    use Acme\Person;
+    use Symfony\Component\Serializer\Encoder\JsonEncoder;
+    use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer;
+    use Symfony\Component\Serializer\Serializer;
+
+    $encoder = new JsonEncoder();
+    $normalizer = new GetSetMethodNormalizer();
+
+    $callback = function ($dateTime) {
+        return $dateTime instanceof \DateTime
+            ? $dateTime->format(\DateTime::ISO8601)
+            : '';
+    }
+
+    $normalizer->setCallbacks(array('createdAt' => $callback));
+
+    $serializer = new Serializer(array($normalizer), array($encoder));
+
+    $person = new Person();
+    $person->setName('cordoval');
+    $person->setAge(34);
+    $person->setCreatedAt(new \DateTime('now'));
+
+    $serializer->serialize($person, 'json');
+    // Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"}
+
 JMSSerializer
 -------------
 

reference/dic_tags.rst

@@ -477,9 +477,23 @@ To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag:
             ->addTag('kernel.cache_warmer', array('priority' => 0))
         ;
 
-The ``priority`` value is optional, and defaults to 0. This value can be
-from -255 to 255, and the warmers will be executed in the order of their
-priority.
+.. note::
+
+    The ``priority`` value is optional, and defaults to 0.
+    The higher the priority, the sooner it gets executed.
+
+Core Cache Warmers
+~~~~~~~~~~~~~~~~~~
+
++-------------------------------------------------------------------------------------------+-----------+
+| Cache Warmer Class Name                                                                   | Priority  |
++-------------------------------------------------------------------------------------------+-----------+
+| :class:`Symfony\\Bundle\\FrameworkBundle\\CacheWarmer\\TemplatePathsCacheWarmer`          | 20        |
++-------------------------------------------------------------------------------------------+-----------+
+| :class:`Symfony\\Bundle\\FrameworkBundle\\CacheWarmer\\RouterCacheWarmer`                 | 0         |
++-------------------------------------------------------------------------------------------+-----------+
+| :class:`Symfony\\Bundle\\TwigBundle\\CacheWarmer\\TemplateCacheCacheWarmer`               | 0         |
++-------------------------------------------------------------------------------------------+-----------+
 
 .. _dic-tags-kernel-event-listener: