Merge branch '2.8' into 3.0

* 2.8:
  Simplified the contribution article for Symfony Docs
  Update routing.rst
  [#6590] fix version in versionadded directive
  Added note on YAML mappings as objects
  use static Yaml API
  Adding a description for the use_microseconds parameter introduced in MonologBundle v2.11
  Clarify signed requests in the ESI renderer

book/http_cache.rst

@@ -1198,6 +1198,12 @@ 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.
 
+.. caution::
+
+    The fragment listener only responds to signed requests. Requests are only
+    signed when using the fragment renderer and the ``render_esi`` Twig
+    function.
+
 .. note::
 
     Once you start using ESI, remember to always use the ``s-maxage``

components/yaml/introduction.rst

@@ -95,16 +95,20 @@ acts as a thin wrapper that simplifies common uses.
 Reading YAML Files
 ~~~~~~~~~~~~~~~~~~
 
-The :method:`Symfony\\Component\\Yaml\\Parser::parse` method parses a YAML
+The :method:`Symfony\\Component\\Yaml\\Yaml::parse` method parses a YAML
 string and converts it to a PHP array:
 
 .. code-block:: php
 
-    use Symfony\Component\Yaml\Parser;
+    use Symfony\Component\Yaml\Yaml;
+
+    $value = Yaml::parse(file_get_contents('/path/to/file.yml'));
 
-    $yaml = new Parser();
+.. caution::
 
-    $value = $yaml->parse(file_get_contents('/path/to/file.yml'));
+    Because it is currently possible to pass a filename to this method, you
+    must validate the input first. Passing a filename is deprecated in
+    Symfony 2.2, and was removed in Symfony 3.0.
 
 If an error occurs during parsing, the parser throws a
 :class:`Symfony\\Component\\Yaml\\Exception\\ParseException` exception
@@ -116,64 +120,49 @@ error occurred:
     use Symfony\Component\Yaml\Exception\ParseException;
 
     try {
-        $value = $yaml->parse(file_get_contents('/path/to/file.yml'));
+        $value = Yaml::parse(file_get_contents('/path/to/file.yml'));
     } catch (ParseException $e) {
         printf("Unable to parse the YAML string: %s", $e->getMessage());
     }
 
-.. tip::
-
-    As the parser is re-entrant, you can use the same parser object to load
-    different YAML strings.
-
-It may also be convenient to use the
-:method:`Symfony\\Component\\Yaml\\Yaml::parse` wrapper method:
+.. _components-yaml-dump:
 
-.. code-block:: php
+Objects for Mappings
+....................
 
-    use Symfony\Component\Yaml\Yaml;
+.. versionadded:: 2.7
+    Support for parsing mappings as objects was introduced in Symfony 2.7.
 
-    $yaml = Yaml::parse(file_get_contents('/path/to/file.yml'));
+Yaml :ref:`mappings <yaml-format-collections>` are basically associative
+arrays. You can instruct the parser to return mappings as objects (i.e.
+``\stdClass`` instances) by setting the fourth argument to ``true``::
 
-The :method:`Symfony\\Component\\Yaml\\Yaml::parse` static method takes a YAML string.
-Internally, it constructs a :class:`Symfony\\Component\\Yaml\\Parser` object and calls
-the :method:`Symfony\\Component\\Yaml\\Parser::parse` method.
-
-.. _components-yaml-dump:
+    $object = Yaml::parse('{"foo": "bar"}', false, false, true);
+    echo get_class($object); // stdClass
+    echo $object->foo; // bar
 
 Writing YAML Files
 ~~~~~~~~~~~~~~~~~~
 
-The :method:`Symfony\\Component\\Yaml\\Dumper::dump` method dumps any PHP
+The :method:`Symfony\\Component\\Yaml\\Yaml::dump` method dumps any PHP
 array to its YAML representation:
 
 .. code-block:: php
 
-    use Symfony\Component\Yaml\Dumper;
+    use Symfony\Component\Yaml\Yaml;
 
     $array = array(
         'foo' => 'bar',
         'bar' => array('foo' => 'bar', 'bar' => 'baz'),
     );
 
-    $dumper = new Dumper();
-
-    $yaml = $dumper->dump($array);
+    $yaml = Yaml::dump($array);
 
     file_put_contents('/path/to/file.yml', $yaml);
 
 If an error occurs during the dump, the parser throws a
 :class:`Symfony\\Component\\Yaml\\Exception\\DumpException` exception.
 
-If you only need to dump one array, you can use the
-:method:`Symfony\\Component\\Yaml\\Yaml::dump` static method shortcut:
-
-.. code-block:: php
-
-    use Symfony\Component\Yaml\Yaml;
-
-    $yaml = Yaml::dump($array);
-
 Array Expansion and Inlining
 ............................
 
@@ -185,7 +174,7 @@ representation:
 
     { foo: bar, bar: { foo: bar, bar: baz } }
 
-The second argument of the :method:`Symfony\\Component\\Yaml\\Dumper::dump`
+The second argument of the :method:`Symfony\\Component\\Yaml\\Yaml::dump`
 method customizes the level at which the output switches from the expanded
 representation to the inline one:
 

components/yaml/yaml_format.rst

@@ -165,6 +165,8 @@ YAML uses the ISO-8601 standard to express dates:
     # simple date
     2002-12-14
 
+.. _yaml-format-collections:
+
 Collections
 -----------