Merge branch '2.8' into 3.2

* 2.8: (46 commits)
  [symfony#7507] fix component name
  [symfony#7490] minor typo fix
  Added a note about redirections to absolute URLs in tests
  Added the changes suggested by reviewers
  [symfony#7620] use generate() in PHP templates before 2.8
  Fixed the RST syntax
  Improve example context
  [symfony#5621] Enhancing example of using bundle config
  [symfony#7601] minor tweak
  Update expiration.rst
  Update expiration.rst
  Update expiration.rst
  Update expiration.rst
  Minor reword and fixed the line length
  Improve specification explanation
  [symfony#7664] minor wording tweak
  Rewords and minor fixes
  Add an explanation about «constraints» validation
  [symfony#7645] enumerate ordered list items implicitly
  Adding a new article about "Creating a Bug Reproducer"
  ...

Author: xabbuh

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

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

contributing/code/index.rst

@@ -5,6 +5,7 @@ Contributing Code
     :maxdepth: 2
 
     bugs
+    reproducer
     patches
     maintenance
     core_team

contributing/code/reproducer.rst

@@ -0,0 +1,77 @@
+Creating a Bug Reproducer
+=========================
+
+The main Symfony code repository receives thousands of issues reports per year.
+Some of those issues are so obvious or easy to understand, that Symfony Core
+developers can fix them without any other information. However, other issues are
+much harder to understand because developers can't easily reproduce them in their
+computers. That's when we'll ask you to create a "bug reproducer", which is the
+minimum amount of code needed to make the bug appear when executed.
+
+Reproducing Simple Bugs
+-----------------------
+
+If you are reporting a bug related to some Symfony component used outside the
+Symfony framework, it's enough to share a small PHP script that when executed
+shows the bug::
+
+    // First, run "composer require symfony/validator"
+    // Then, execute this file:
+    <?php
+    require_once __DIR__.'/vendor/autoload.php';
+    use Symfony\Component\Validator\Constraints;
+
+    $wrongUrl = 'http://example.com/exploit.html?<script>alert(1);</script>';
+    $urlValidator = new Constraints\UrlValidator();
+    $urlConstraint = new Constraints\Url();
+
+    // The URL is wrong, so var_dump() should display an error, but it displays
+    // "null" instead because there is no context to build a validator violation
+    var_dump($urlValidator->validate($wrongUrl, $urlConstraint));
+
+Reproducing Complex Bugs
+------------------------
+
+If the bug is related to the Symfony Framework or if it's too complex to create
+a PHP script, it's better to reproduce the bug by forking the Symfony Standard
+edition. To do so:
+
+#. Go to https://github.com/symfony/symfony-standard and click on the **Fork**
+   button to make a fork of that repository or go to your already forked copy.
+#. Clone the forked repository into your computer:
+   ``git clone git://github.com/YOUR-GITHUB-USERNAME/symfony-standard.git``
+#. Browse the project and create a new branch (e.g. ``issue_23567``,
+   ``reproduce_23657``, etc.)
+#. Now you must add the minimum amount of code to reproduce the bug. This is the
+   trickiest part and it's explained a bit more later.
+#. Add, commit and push all your changes.
+#. Add a comment in your original issue report to share the URL of your forked
+   project (e.g. ``https://github.com/YOUR-GITHUB-USERNAME/symfony-standard/tree/issue_23567``)
+   and, if necessary, explain the steps to reproduce (e.g. "browse this URL",
+   "fill in this data in the form and submit it", etc.)
+
+Adding the Minimum Amount of Code Possible
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The key to create a bug reproducer is to solely focus on the feature that you
+suspect is failing. For example, imagine that you suspect that the bug is related
+to a route definition. Then, after forking the Symfony Standard Edition:
+
+#. Don't edit any of the default Symfony configuration options.
+#. Don't copy your original application code and don't use the same structure
+   of bundles, controllers, actions, etc. as in your original application.
+#. Open the default controller class of the AppBundle and add your routing
+   definition using annotations.
+#. Don't create or modify any other file.
+#. Execute the ``server:run`` command and browse the previously defined route
+   to see if the bug appears or not.
+#. If you can see the bug, you're done and you can already share the code with us.
+#. If you can't see the bug, you must keep making small changes. For example, if
+   your original route was defined using XML, forget about the previous route
+   annotation and define the route using XML instead. Or maybe your application
+   uses bundle inheritance and that's where the real bug is. Then, forget about
+   AppBundle and quickly generate a new AppParentBundle, make AppBundle inherit
+   from it and test if the route is working.
+
+In short, the idea is to keep adding small and incremental changes to the default
+Symfony Standard edition until you can reproduce the bug.

deployment/platformsh.rst

@@ -186,8 +186,8 @@ soon be able to see it in your browser.
 
 .. _`Platform.sh`: https://platform.sh
 .. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html
-.. _`Platform.sh project`: https://marketplace.commerceguys.com/platform/buy-now
-.. _`Platform.sh configuration files`: https://docs.platform.sh/reference/configuration-files
+.. _`Platform.sh project`: https://accounts.platform.sh/platform/buy-now
+.. _`Platform.sh configuration files`: https://docs.platform.sh/configuration/services.html
 .. _`GitHub`: https://github.com/platformsh/platformsh-examples
 .. _`available services`: https://docs.platform.sh/reference/configuration-files/#configure-services
-.. _`migrating your database and files`: https://docs.platform.sh/toolstacks/php/symfony/migrate-existing-site/
+.. _`migrating your database and files`: https://docs.platform.sh/tutorials/migrating.html

form/action_method.rst

@@ -9,31 +9,108 @@ URL under which the form was rendered. Sometimes you want to change these
 parameters. You can do so in a few different ways.
 
 If you use the :class:`Symfony\\Component\\Form\\FormBuilder` to build your
-form, you can use ``setAction()`` and ``setMethod()``::
+form, you can use ``setAction()`` and ``setMethod()``:
 
-    $form = $this->createFormBuilder($task)
-        ->setAction($this->generateUrl('target_route'))
-        ->setMethod('GET')
-        ->add('task', TextType::class)
-        ->add('dueDate', DateType::class)
-        ->add('save', SubmitType::class)
-        ->getForm();
+.. configuration-block::
+
+    .. code-block:: php-symfony
+
+        // AppBundle/Controller/DefaultController.php
+        namespace AppBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Symfony\Component\Form\Extension\Core\Type\DateType;
+        use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
+
+        class DefaultController extends Controller
+        {
+            public function newAction()
+            {
+                $form = $this->createFormBuilder($task)
+                    ->setAction($this->generateUrl('target_route'))
+                    ->setMethod('GET')
+                    ->add('task', TextType::class)
+                    ->add('dueDate', DateType::class)
+                    ->add('save', SubmitType::class)
+                    ->getForm();
+
+                // ...
+            }
+        }
+
+    .. code-block:: php-standalone
+
+        use Symfony\Component\Form\Forms;
+        use Symfony\Component\Form\Extension\Core\Type\DateType;
+        use Symfony\Component\Form\Extension\Core\Type\FormType;
+        use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
+
+        // ...
+
+        $formFactoryBuilder = Forms::createFormFactoryBuilder();
+
+        // Form factory builder configuration ...
+
+        $formFactory = $formFactoryBuilder->getFormFactory();
+
+        $form = $formFactory->createBuilder(FormType::class, $task)
+            ->setAction($this->generateUrl('target_route'))
+            ->setMethod('GET')
+            ->add('task', TextType::class)
+            ->add('dueDate', DateType::class)
+            ->add('save', SubmitType::class)
+            ->getForm();
 
 .. note::
 
     This example assumes that you've created a route called ``target_route``
     that points to the controller that processes the form.
 
 When using a form type class, you can pass the action and method as form
-options::
+options:
 
-    use AppBundle\Form\TaskType;
-    // ...
+.. configuration-block::
+
+    .. code-block:: php-symfony
+
+        // AppBundle/Controller/DefaultController.php
+        namespace AppBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use AppBundle\Form\TaskType;
+
+        class DefaultController extends Controller
+        {
+            public function newAction()
+            {
+                // ...
+
+                $form = $this->createForm(TaskType::class, $task, array(
+                    'action' => $this->generateUrl('target_route'),
+                    'method' => 'GET',
+                ));
+
+                // ...
+            }
+        }
 
-    $form = $this->createForm(TaskType::class, $task, array(
-        'action' => $this->generateUrl('target_route'),
-        'method' => 'GET',
-    ));
+    .. code-block:: php-standalone
+
+        use Symfony\Component\Form\Forms;
+        use AppBundle\Form\TaskType;
+
+        $formFactoryBuilder = Forms::createFormFactoryBuilder();
+
+        // Form factory builder configuration ...
+
+        $formFactory = $formFactoryBuilder->getFormFactory();
+
+        $form = $formFactory->create(TaskType::class, $task, array(
+            'action' => $this->generateUrl('target_route'),
+            'method' => 'GET',
+        ));
 
 Finally, you can override the action and method in the template by passing them
 to the ``form()`` or the ``form_start()`` helper functions: