Merge branch '3.0' into 3.1

* 3.0:
  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
  refs #5898 Fix updates of testing.rst for 3.0

Author: xabbuh

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``

book/testing.rst

@@ -63,7 +63,7 @@ called ``Calculator`` in the ``Util/`` directory of the app bundle::
     }
 
 To test this, create a ``CalculatorTest`` file in the ``tests/AppBundle/Util`` directory
-of your bundle::
+of your application::
 
     // tests/AppBundle/Util/CalculatorTest.php
     namespace Tests\AppBundle\Util;
@@ -84,13 +84,13 @@ of your bundle::
 
 .. note::
 
-    By convention, the ``Tests/AppBundle`` directory should replicate the directory
+    By convention, the ``tests/AppBundle`` directory should replicate the directory
     of your bundle for unit tests. So, if you're testing a class in the
-    ``AppBundle/Util/`` directory, put the test in the ``tests/AppBundle/Util/``
+    ``src/AppBundle/Util/`` directory, put the test in the ``tests/AppBundle/Util/``
     directory.
 
 Just like in your real application - autoloading is automatically enabled
-via the ``autoload.php`` file (as configured by default in the
+via the ``app/autoload.php`` file (as configured by default in the
 ``phpunit.xml.dist`` file).
 
 Running tests for a given file or directory is also very easy:
@@ -835,7 +835,7 @@ 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 an ``phpunit.xml`` file to set up a configuration for your local machine
+create a ``phpunit.xml`` file to set up a configuration for your local machine
 only.
 
 .. tip::
@@ -870,7 +870,7 @@ configuration adds tests from a custom ``lib/tests`` directory:
         <testsuites>
             <testsuite name="Project Test Suite">
                 <!-- ... --->
-                <directory>../lib/tests</directory>
+                <directory>lib/tests</directory>
             </testsuite>
         </testsuites>
         <!-- ... --->
@@ -887,10 +887,10 @@ section:
         <filter>
             <whitelist>
                 <!-- ... -->
-                <directory>../lib</directory>
+                <directory>lib</directory>
                 <exclude>
                     <!-- ... -->
-                    <directory>../lib/tests</directory>
+                    <directory>lib/tests</directory>
                 </exclude>
             </whitelist>
         </filter>

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
 -----------