Merge branch '2.7' into 2.8

* 2.7: (31 commits)
  Fixed the RST syntax
  Improve example context
  [#5621] Enhancing example of using bundle config
  [#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
  [#7664] minor wording tweak
  Rewords and minor fixes
  Add an explanation about «constraints» validation
  [#7645] enumerate ordered list items implicitly
  Adding a new article about "Creating a Bug Reproducer"
  Fixed a syntax issue
  Use backticks
  #7311 choice_value callback argument can be null
  Fixed broken links for nginx & FastCgiExternalServer
  Update dialoghelper.rst
  ...

Author: xabbuh

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
 

components/console/helpers/dialoghelper.rst

@@ -125,7 +125,7 @@ method::
         'AcmeDemoBundle'
     );
 
-This methods has 2 new arguments, the full signature is::
+This method has 2 new arguments, the full signature is::
 
     askAndValidate(
         OutputInterface $output,

console/coloring.rst

@@ -65,6 +65,12 @@ You can also set these colors and options directly inside the tagname::
     // bold text on a yellow background
     $output->writeln('<bg=yellow;options=bold>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:

http_cache.rst

@@ -27,7 +27,7 @@ cache system.
 
 Since caching with HTTP isn't unique to Symfony, many articles already exist
 on the topic. If you're new to HTTP caching, Ryan Tomayko's article
-`Things Caches Do`_ is *highly* recommended . Another in-depth resource is Mark
+`Things Caches Do`_ is *highly* recommended. Another in-depth resource is Mark
 Nottingham's `Cache Tutorial`_.
 
 .. index::
@@ -53,7 +53,7 @@ Along the way, the cache will store each response that is deemed "cacheable"
 the cache sends the cached response to the client, ignoring your application
 entirely.
 
-This type of cache is known as a HTTP gateway cache and many exist such
+This type of cache is known as an HTTP gateway cache and many exist such
 as `Varnish`_, `Squid in reverse proxy mode`_, and the Symfony reverse proxy.
 
 .. tip::

http_cache/expiration.rst

@@ -85,5 +85,12 @@ the lifetime calculation vulnerable to clock skew. Another limitation
 of the ``Expires`` header is that the specification states that "HTTP/1.1
 servers should not send ``Expires`` dates more than one year in the future."
 
+.. note::
+
+    According to `RFC 7234 - Caching`_, the ``Expires`` header value is ignored
+    when the ``s-maxage`` or ``max-age`` directive of the ``Cache-Control``
+    header is defined.
+
 .. _`expiration model`: http://tools.ietf.org/html/rfc2616#section-13.2
 .. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
+.. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234#section-4.2.1

performance.rst

@@ -79,7 +79,7 @@ real and absolute file system paths. This increases the performance for
 applications like Symfony that open many PHP files, especially on Windows
 systems.
 
-By default PHP sets a ``realpath_cache_size`` of ``16K`` which is too low for
+By default, PHP sets a ``realpath_cache_size`` of ``16K`` which is too low for
 Symfony. Consider updating this value at least to ``4096K``. In addition, cached
 paths are only stored for ``120`` seconds by default. Consider updating this
 value too using the ``realpath_cache_ttl`` option:
@@ -195,7 +195,7 @@ Bootstrap Files and Byte Code Caches
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Even when using a byte code cache, performance will improve when using a bootstrap
-file since there will be fewer files to monitor for changes. Of course if this
+file since there will be fewer files to monitor for changes. Of course, if this
 feature is disabled in the byte code cache (e.g. ``apc.stat=0`` in APC), there
 is no longer a reason to use a bootstrap file.