Merge branch '3.0' into 3.1

Author: wouterj

book/http_cache.rst

@@ -1198,11 +1198,6 @@ One great advantage of the ESI renderer is that you can make your application
 as dynamic as needed and at the same time, hit the application as little as
 possible.
 
-.. tip::
-
-    The listener only responds to local IP addresses or
-    :doc:`trusted proxies </cookbook/request/load_balancer_reverse_proxy>`.
-
 .. note::
 
     Once you start using ESI, remember to always use the ``s-maxage``

components/event_dispatcher/container_aware_dispatcher.rst

@@ -68,14 +68,15 @@ and the second argument is the service's class name (which must implement
 The ``EventSubscriberInterface`` is exactly as you would expect::
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\KernelEvents;
     // ...
 
     class StoreSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return array(
-                'kernel.response' => array(
+                KernelEvents::RESPONSE => array(
                     array('onKernelResponsePre', 10),
                     array('onKernelResponsePost', 0),
                 ),

components/form/introduction.rst

@@ -199,9 +199,12 @@ to bootstrap or access Twig and add the :class:`Symfony\\Bridge\\Twig\\Extension
     )));
     $formEngine = new TwigRendererEngine(array($defaultFormTheme));
     $formEngine->setEnvironment($twig);
+
+    // ... (see the previous CSRF Protection section for more information)
+
     // add the FormExtension to Twig
     $twig->addExtension(
-        new FormExtension(new TwigRenderer($formEngine, $csrfProvider))
+        new FormExtension(new TwigRenderer($formEngine, $csrfManager))
     );
 
     // create your form factory as normal

cookbook/bundles/configuration.rst

@@ -373,7 +373,7 @@ can place it anywhere you like. You should return this path as the base path::
         }
     }
 
-Assume the XSD file is called ``hello-1.0.xsd``, the schema location will be
+Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
 ``http://acme_company.com/schema/dic/hello/hello-1.0.xsd``:
 
 .. code-block:: xml

cookbook/composer.rst

@@ -14,35 +14,24 @@ following sections.
 Install Composer on Linux and Mac OS X
 --------------------------------------
 
-To install Composer on Linux or Mac OS X, execute the following two commands:
+#. Run the installer as described in `the official Composer documentation`_;
+#. Execute the following command to move the ``composer.phar`` to a directory that is in your path:
 
-.. code-block:: bash
+   .. code-block:: bash
 
-    $ curl -sS https://getcomposer.org/installer | php
-    $ sudo mv composer.phar /usr/local/bin/composer
-
-.. note::
-
-    If you don't have ``curl`` installed, you can also just download the
-    ``installer`` file manually at https://getcomposer.org/installer and
-    then run:
-
-    .. code-block:: bash
-
-        $ php installer
-        $ sudo mv composer.phar /usr/local/bin/composer
+       $ sudo mv composer.phar /usr/local/bin/composer
 
 Install Composer on Windows
 ---------------------------
 
-Download the installer from `getcomposer.org/download`_, execute it and follow
-the instructions.
+Download the installer from `getcomposer.org`_, execute it and follow the instructions.
 
 Learn more
 ----------
 
 Read the `Composer documentation`_ to learn more about its usage and features.
 
 .. _`Composer`: https://getcomposer.org/
-.. _`getcomposer.org/download`: https://getcomposer.org/download
 .. _`Composer documentation`: https://getcomposer.org/doc/00-intro.md
+.. _`getcomposer.org`: https://getcomposer.org/Composer-Setup.exe
+.. _the official Composer documentation: https://getcomposer.org/download

cookbook/event_dispatcher/event_listener.rst

@@ -142,14 +142,15 @@ listen to the same ``kernel.exception`` event::
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
 
     class ExceptionSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             // return the subscribed events, their methods and priorities
             return array(
-               'kernel.exception' => array(
+               KernelEvents::EXCEPTION => array(
                    array('processException', 10),
                    array('logException', 0),
                    array('notifyException', -10),

cookbook/form/data_transformers.rst

@@ -16,24 +16,26 @@ to render the form, and then back into a ``DateTime`` object on submit.
     When a form field has the ``inherit_data`` option set, Data Transformers
     won't be applied to that field.
 
-Simple Example: Sanitizing HTML on User Input
----------------------------------------------
+.. _simple-example-sanitizing-html-on-user-input:
 
-Suppose you have a Task form with a description ``textarea`` type::
+Simple Example: Transforming String Tags from User Input to an Array
+--------------------------------------------------------------------
+
+Suppose you have a Task form with a tags ``text`` type::
 
     // src/AppBundle/Form/TaskType.php
     namespace AppBundle\Form\Type;
 
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
 
     // ...
     class TaskType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('description', TextareaType::class);
+            $builder->add('tags', TextType::class)
         }
 
         public function configureOptions(OptionsResolver $resolver)
@@ -46,15 +48,10 @@ Suppose you have a Task form with a description ``textarea`` type::
         // ...
     }
 
-But, there are two complications:
-
-#. Your users are allowed to use *some* HTML tags, but not others: you need a way
-   to call :phpfunction:`strip_tags` after the form is submitted;
-
-#. To be friendly, you want to convert ``<br/>`` tags into line breaks (``\n``) before
-   rendering the field so the text is easier to edit.
+Internally the ``tags`` are stored as an array, but displayed to the user as a
+simple comma seperated string to make them easier to edit.
 
-This is a *perfect* time to attach a custom data transformer to the ``description``
+This is a *perfect* time to attach a custom data transformer to the ``tags``
 field. The easiest way to do this is with the :class:`Symfony\\Component\\Form\\CallbackTransformer`
 class::
 
@@ -63,27 +60,24 @@ class::
 
     use Symfony\Component\Form\CallbackTransformer;
     use Symfony\Component\Form\FormBuilderInterface;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
     // ...
 
     class TaskType extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
-            $builder->add('description', TextareaType::class);
+            $builder->add('tags', TextType::class);
 
-            $builder->get('description')
+            $builder->get('tags')
                 ->addModelTransformer(new CallbackTransformer(
-                    // transform <br/> to \n so the textarea reads easier
-                    function ($originalDescription) {
-                        return preg_replace('#<br\s*/?>#i', "\n", $originalDescription);
+                    function ($tagsAsArray) {
+                        // transform the array to a string
+                        return implode(', ', $tagsAsArray);
                     },
-                    function ($submittedDescription) {
-                        // remove most HTML tags (but not br,p)
-                        $cleaned = strip_tags($submittedDescription, '<br><br/><p>');
-
-                        // transform any \n to real <br/>
-                        return str_replace("\n", '<br/>', $cleaned);
+                    function ($tagsAsString) {
+                        // transform the string back to an array
+                        return explode(', ', $tagsAsString);
                     }
                 ))
             ;
@@ -92,10 +86,10 @@ class::
         // ...
     }
 
-The ``CallbackTransformer`` takes two callback functions as arguments. The first transforms
-the original value into a format that'll be used to render the field. The second
-does the reverse: it transforms the submitted value back into the format you'll use
-in your code.
+The ``CallbackTransformer`` takes two callback functions as arguments. The
+first transforms the original value into a format that'll be used to render the
+field. The second does the reverse: it transforms the submitted value back into
+the format you'll use in your code.
 
 .. tip::
 
@@ -106,10 +100,11 @@ in your code.
 You can also add the transformer, right when adding the field by changing the format
 slightly::
 
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
+    use Symfony\Component\Form\Extension\Core\Type\TextType;
 
     $builder->add(
-        $builder->create('description', TextareaType::class)
+        $builder
+            ->create('tags', TextType::class)
             ->addModelTransformer(...)
     );
 

cookbook/form/form_collections.rst

@@ -69,13 +69,18 @@ objects::
 
     class Tag
     {
-        public $name;
-    }
+        private $name;
 
-.. tip::
+        public function getName()
+        {
+            return $this->name;
+        }
 
-    The ``name`` property is public here, but it can just as easily be protected
-    or private (but then it would need ``getName`` and ``setName`` methods).
+        public function setName($name)
+        {
+            $this->name = $name;
+        }
+    }
 
 Then, create a form class so that a ``Tag`` object can be modified by the user::
 
@@ -155,10 +160,10 @@ In your controller, you'll create a new form from the ``TaskType``::
             // dummy code - this is here just so that the Task has some tags
             // otherwise, this isn't an interesting example
             $tag1 = new Tag();
-            $tag1->name = 'tag1';
+            $tag1->setName('tag1');
             $task->getTags()->add($tag1);
             $tag2 = new Tag();
-            $tag2->name = 'tag2';
+            $tag2->setName('tag2');
             $task->getTags()->add($tag2);
             // end dummy code
 

cookbook/request/load_balancer_reverse_proxy.rst

@@ -89,7 +89,7 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
        $response = $kernel->handle($request);
        // ...
 
-#. Ensure that the trusted_proxies setting in your ``app/config/config.yml`` 
+#. Ensure that the trusted_proxies setting in your ``app/config/config.yml``
    is not set or it will overwrite the ``setTrustedProxies`` call above.
 
 That's it! It's critical that you prevent traffic from all non-trusted sources.

create_framework/http_kernel_httpkernel_class.rst

@@ -151,8 +151,9 @@ only if needed::
     namespace Simplex;
 
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-    use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
 
     class StringResponseListener implements EventSubscriberInterface
     {
@@ -167,7 +168,7 @@ only if needed::
 
         public static function getSubscribedEvents()
         {
-            return array('kernel.view' => 'onView');
+            return array(KernelEvents::VIEW => 'onView');
         }
     }