Merge branch '3.2'

* 3.2: (71 commits)
  Rewriting the service container docs
  Minor reword
  Adding a tip for validation in forms without class
  [#7217] add versionadded directives
  [#7203] merge note and versionadded directive
  Use the new configurator YAML syntax
  Added a note about the .htaccess files included by Symfony apps
  Made unmapped field example in forms chapter more descriptive
  [#7507] fix namespace
  [#7507] fix component name
  [#7490] minor typo fix
  Added a note about redirections to absolute URLs in tests
  [#7204] link to API doc
  Added docs for JsonResponse::fromJsonString
  Added the changes suggested by reviewers
  [#7620] use generate() in PHP templates before 2.8
  Fixed the RST syntax
  Improve example context
  Minor formatting changes
  [#7519] some minor tweaks
  ...

Author: weaverryan

_build/redirection_map

@@ -332,3 +332,4 @@
 /deployment/tools /deployment
 /install/bundles /setup/bundles
 /form /forms
+/testing/simulating_authentication /testing/http_authentication

bundles/configuration.rst

@@ -218,18 +218,64 @@ This class can now be used in your ``load()`` method to merge configurations and
 force validation (e.g. if an additional option was passed, an exception will be
 thrown)::
 
+    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
+
     public function load(array $configs, ContainerBuilder $container)
     {
         $configuration = new Configuration();
 
         $config = $this->processConfiguration($configuration, $configs);
-        // ...
+        
+        // you now have these 2 config keys
+        // $config['twitter']['client_id'] and $config['twitter']['client_secret']
     }
 
 The ``processConfiguration()`` method uses the configuration tree you've defined
 in the ``Configuration`` class to validate, normalize and merge all the
 configuration arrays together.
 
+Now, you can use the ``$config`` variable to modify a service provided by your bundle.
+For example, imagine your bundle has the following example config:
+
+.. code-block:: xml
+
+    <!-- src/Acme/SocialBundle/Resources/config/services.xml -->
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <container xmlns="http://symfony.com/schema/dic/services"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://symfony.com/schema/dic/services
+            http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+        <services>
+            <service id="acme.social.twitter_client" class="Acme\SocialBundle\TwitterClient">
+                <argument></argument> <!-- will be filled in with client_id dynamically -->
+                <argument></argument> <!-- will be filled in with client_secret dynamically -->
+            </service>
+        </services>
+    </container>
+
+In your extension, you can load this and dynamically set its arguments::
+
+    // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
+    // ...
+
+    use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+    use Symfony\Component\Config\FileLocator;
+
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        $loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
+        $loader->load('services.xml');
+
+        $configuration = new Configuration();
+        $config = $this->processConfiguration($configuration, $configs);
+
+        $def = $container->getDefinition('acme.social.twitter_client');
+        $def->replaceArgument(0, $config['twitter']['client_id']);
+        $def->replaceArgument(1, $config['twitter']['client_secret']);
+    }
+
+
 .. tip::
 
     Instead of calling ``processConfiguration()`` in your extension each time you
@@ -253,9 +299,7 @@ configuration arrays together.
         }
 
     This class uses the ``getConfiguration()`` method to get the Configuration
-    instance. You should override it if your Configuration class is not called
-    ``Configuration`` or if it is not placed in the same namespace as the
-    extension.
+    instance.
 
 .. sidebar:: Processing the Configuration yourself
 

bundles/inheritance.rst

@@ -93,8 +93,9 @@ The same goes for routing files and some other resources.
 
     The overriding of resources only works when you refer to resources with
     the ``@FOSUserBundle/Resources/config/routing/security.xml`` method.
-    If you refer to resources without using the ``@BundleName`` shortcut, they
-    can't be overridden in this way.
+    You need to use the ``@BundleName`` shortcut when referring to resources
+    so they can be successfully overridden (except templates, which are
+    overridden in a different way, as explained in :doc:`/templating/overriding`).
 
 .. caution::
 

bundles/installation.rst

@@ -48,7 +48,7 @@ version, include it as the second argument of the `composer require`_ command:
 B) Enable the Bundle
 --------------------
 
-At this point, the bundle is installed in your Symfony project (in
+At this point, the bundle is installed in your Symfony project (e.g. 
 ``vendor/friendsofsymfony/``) and the autoloader recognizes its classes.
 The only thing you need to do now is register the bundle in ``AppKernel``::
 

bundles/override.rst

@@ -39,7 +39,7 @@ Services & Configuration
 
 If you want to modify service definitions of another bundle, you can use a compiler
 pass to change the class of the service or to modify method calls. In the following
-example, the implementing class for the ``original-service-id`` is changed to 
+example, the implementing class for the ``original-service-id`` is changed to
 ``Acme\DemoBundle\YourService``::
 
     // src/Acme/DemoBundle/DependencyInjection/Compiler/OverrideServiceCompilerPass.php
@@ -72,16 +72,8 @@ associations. Learn more about this feature and its limitations in
 Forms
 -----
 
-Form types are referred to by their fully-qualified class name::
-
-    $builder->add('name', CustomType::class);
-
-This means that you cannot override this by creating a sub-class of ``CustomType``
-and registering it as a service and tagging it with ``form.type`` (you *could*
-do this in earlier version).
-
-Instead, you should use a "form type extension" to modify the existing form type.
-For more information, see :doc:`/form/create_form_type_extension`.
+Existing form types can be modified defining
+:doc:`form type extensions </form/create_form_type_extension>`.
 
 .. _override-validation:
 
@@ -92,7 +84,7 @@ Symfony loads all validation configuration files from every bundle and
 combines them into one validation metadata tree. This means you are able to
 add new constraints to a property, but you cannot override them.
 
-To override this, the 3rd party bundle needs to have configuration for
+To overcome this, the 3rd party bundle needs to have configuration for
 :doc:`validation groups </validation/groups>`. For instance, the FOSUserBundle
 has this configuration. To create your own validation, add the constraints
 to a new validation group:

bundles/prepend_extension.rst

@@ -2,7 +2,7 @@
    single: Configuration; Semantic
    single: Bundle; Extension configuration
 
-How to Simplify Configuration of multiple Bundles
+How to Simplify Configuration of Multiple Bundles
 =================================================
 
 When building reusable and extensible applications, developers are often
@@ -12,9 +12,9 @@ users to choose to remove functionality they are not using. Creating multiple
 bundles has the drawback that configuration becomes more tedious and settings
 often need to be repeated for various bundles.
 
-Using the below approach, it is possible to remove the disadvantage of the
-multiple bundle approach by enabling a single Extension to prepend the settings
-for any bundle. It can use the settings defined in the ``app/config/config.yml``
+It is possible to remove the disadvantage of the multiple bundle approach 
+by enabling a single Extension to prepend the settings for any bundle.
+It can use the settings defined in the ``app/config/config.yml``
 to prepend settings just as if they had been written explicitly by
 the user in the application configuration.
 

components/http_foundation.rst

@@ -562,13 +562,23 @@ class, which can make this even easier::
 
     use Symfony\Component\HttpFoundation\JsonResponse;
 
+    // if you know the data to send when creating the response
+    $response = new JsonResponse(array('data' => 123));
+
+    // if you don't know the data to send when creating the response
     $response = new JsonResponse();
-    $response->setData(array(
-        'data' => 123
-    ));
+    // ...
+    $response->setData(array('data' => 123));
+
+    // if the data to send is already encoded in JSON
+    $response = JsonResponse::fromJsonString('{ "data": 123 }');
+
+.. versionadded:: 3.2
+    The :method:`Symfony\\Component\\HttpFoundation\\JsonResponse::fromJsonString`
+    method was added in Symfony 3.2.
 
-This encodes your array of data to JSON and sets the ``Content-Type`` header
-to ``application/json``.
+The ``JsonResponse`` class sets the ``Content-Type`` header to
+``application/json`` and encodes your data to JSON when needed.
 
 .. caution::
 

components/phpunit_bridge.rst

@@ -229,14 +229,25 @@ The :class:`Symfony\\Bridge\\PhpUnit\\ClockMock` class provided by this bridge
 allows you to mock the PHP's built-in time functions ``time()``,
 ``microtime()``, ``sleep()`` and ``usleep()``.
 
-To use the ``ClockMock`` class in your test, you can:
+To use the ``ClockMock`` class in your test, add the ``@group time-sensitive``
+annotation to its class or methods. This annotation only works when executing
+PHPUnit using the ``vendor/bin/simple-phpunit`` script or when registering the
+following listener in your PHPUnit configuration:
 
-* (**Recommended**) Add the ``@group time-sensitive`` annotation to its class or
-  method;
+.. code-block:: xml
+
+    <!-- phpunit.xml.dist -->
+    <!-- ... -->
+    <listeners>
+        <listener class="\Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+    </listeners>
+
+.. note::
 
-* Register it manually by calling ``ClockMock::register(__CLASS__)`` and
-  ``ClockMock::withClockMock(true)`` before the test and
-  ``ClockMock::withClockMock(false)`` after the test.
+    If you don't want to use the ``@group time-sensitive`` annotation, you can
+    register the ``ClockMock`` class manually by calling
+    ``ClockMock::register(__CLASS__)`` and ``ClockMock::withClockMock(true)``
+    before the test and ``ClockMock::withClockMock(false)`` after the test.
 
 As a result, the following is guaranteed to work and is no longer a transient
 test::

components/var_dumper/advanced.rst

@@ -181,6 +181,102 @@ method. They also typically implement the
 them from re-implementing the logic required to walk through a
 :class:`Symfony\\Component\\VarDumper\\Cloner\\Data` object's internal structure.
 
+The :class:`Symfony\\Component\\VarDumper\\Dumper\\HtmlDumper` limits string
+length and nesting depth of the output to make it more readable. These options
+can be overriden by the third optional parameter of the
+:method:`dump(Data $data) <Symfony\\Component\\VarDumper\\Dumper\\DataDumperInterface::dump>`
+method::
+
+    use Symfony\Component\VarDumper\Dumper\HtmlDumper;
+
+    $output = fopen('php://memory', 'r+b');
+
+    $dumper = new HtmlDumper();
+    $dumper->dump($var, $output, array(
+        // 1 and 160 are the default values for these options
+        'maxDepth' => 1,
+        'maxStringLength' => 160
+    ));
+
+.. versionadded:: 3.2
+    Support for passing display options to the ``dump()`` method was introduced
+    in Symfony 3.2.
+
+The output format of a dumper can be fine tuned by the two flags 
+``DUMP_STRING_LENGTH`` and ``DUMP_LIGHT_ARRAY`` which are passed as a bitmap
+in the third constructor argument. They can also be set via environment 
+variables when using
+:method:`assertDumpEquals($dump, $data, $message) <Symfony\\Component\\VarDumper\\Test\\VarDumperTestTrait::assertDumpEquals>`
+during unit testing.
+
+.. versionadded:: 3.1
+    The ``DUMP_STRING_LENGTH`` and ``DUMP_LIGHT_ARRAY`` flags were introduced
+    in Symfony 3.1.
+
+If ``DUMP_STRING_LENGTH`` is set, then the length of a string is displayed
+next to its content:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper();
+    echo $dumper->dump($var, true);
+
+    // array:1 [
+    //   0 => "test"
+    // ]
+
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH);
+    echo $dumper->dump($var, true);
+
+    // (added string length before the string)
+    // array:1 [
+    //   0 => (4) "test"
+    // ]
+
+If ``DUMP_LIGHT_ARRAY`` is set, then arrays are dumped in a shortened format
+similar to PHP's short array notation:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper();
+    echo $dumper->dump($var, true);
+
+    // array:1 [
+    //   0 => "test"
+    // ]
+
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_LIGHT_ARRAY);
+    echo $dumper->dump($var, true);
+
+    // (no more array:1 prefix)
+    // [
+    //   0 => "test"
+    // ]
+
+If you would like to use both options, then you can just    combine them by
+using a the logical OR operator ``|``:
+
+.. code-block:: php
+
+    use Symfony\Component\VarDumper\Dumper\AbstractDumper;
+    use Symfony\Component\VarDumper\Dumper\CliDumper;
+
+    $var = array('test');
+    $dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH | AbstractDumper::DUMP_LIGHT_ARRAY);
+    echo $dumper->dump($var, true);
+
+    // [
+    //   0 => (4) "test"
+    // ]
+
 Casters
 -------
 

console/coloring.rst

@@ -68,6 +68,12 @@ You can also set these colors and options directly inside the tagname::
     // bold text with underscore
     $output->writeln('<options=bold,underscore>foo</>');
 
+.. note::
+
+    If you need to render a tag literally, escape it with a backslash: ``\<info>``
+    or use the :method:`Symfony\\Component\\Console\\Formatter\\OutputFormatter::escape`
+    method to escape all the tags included in the given string.
+
 .. _Cmder: http://cmder.net/
 .. _ConEmu: https://conemu.github.io/
 .. _ANSICON: https://github.com/adoxa/ansicon/releases