Merge branch '2.8' into 3.2

Author: wouterj

.platform.app.yaml

@@ -56,5 +56,5 @@ hooks:
       # Platform.sh currently sets PIP_USER=1.
       export PIP_USER=
       pip install pip==9.0.1 wheel==0.29.0
-      pip install -r requirements.txt
+      pip install -r _build/.requirements.txt
       make -C _build html

requirements.txt renamed to _build/.requirements.txt

@@ -5,8 +5,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set BUILDDIR=.
+set ALLSPHINXOPTS=-c %BUILDDIR% -d %BUILDDIR%/doctrees %SPHINXOPTS% ..
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

_build/make.bat

@@ -308,4 +308,4 @@ file:
     `LiipImagineBundle`_ community bundle.
 
 .. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html
-.. _`LiipImagineBundle`: http://knpbundles.com/liip/LiipImagineBundle
+.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle

assetic/jpeg_optimize.rst

@@ -153,6 +153,31 @@ whereas they cannot access the container parameters:
 The only notable disadvantage of using constants for this kind of configuration
 values is that you cannot redefine them easily in your tests.
 
+Parameter Naming
+----------------
+
+.. best-practice::
+
+    The name of your configuration parameters should be as short as possible and
+    should include a common prefix for the entire application.
+
+Using ``app.`` as the prefix of your parameters is a common practice to avoid
+collisions with Symfony and third-party bundles/libraries parameters. Then, use
+just one or two words to describe the purpose of the parameter:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    parameters:
+        # don't do this: 'dir' is too generic and it doesn't convey any meaning
+        app.dir: '...'
+        # do this: short but easy to understand names
+        app.contents_dir: '...'
+        # it's OK to use dots, underscores, dashes or nothing, but always
+        # be consistent and use the same format for all the parameters
+        app.dir.contents: '...'
+        app.contents-dir: '...'
+
 Semantic Configuration: Don't Do It
 -----------------------------------
 

best_practices/configuration.rst

@@ -154,7 +154,7 @@ of the most common elements of a bundle:
     Houses configuration, including routing configuration (e.g. ``routing.yml``).
 
 ``Resources/views/``
-    Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
+    Holds templates organized by controller name (e.g. ``Random/index.html.twig``).
 
 ``Resources/public/``
     Contains web assets (images, stylesheets, etc) and is copied or symbolically
@@ -181,4 +181,4 @@ Learn more
 
     bundles/*
 
-_`third-party bundles`: http://knpbundles.com
+_`third-party bundles`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

bundles.rst

@@ -26,8 +26,7 @@ the bundle on the `Packagist.org`_ site.
 
 .. tip::
 
-    Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
-    archive of Symfony Bundles.
+    Looking for bundles? Try searching for `symfony-bundle topic on GitHub`_.
 
 2) Install the Bundle via Composer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -142,5 +141,5 @@ what to do next. Have fun!
 .. _their documentation: https://getcomposer.org/doc/00-intro.md
 .. _Packagist.org:       https://packagist.org
 .. _FOSUserBundle:       https://github.com/FriendsOfSymfony/FOSUserBundle
-.. _KnpBundles.com:      http://knpbundles.com/
 .. _`composer require`:  https://getcomposer.org/doc/03-cli.md#require
+.. _`symfony-bundle topic on GitHub`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

bundles/installation.rst

@@ -4,11 +4,10 @@
 Container Building Workflow
 ===========================
 
-In the preceding pages of this section, there has been little to say about
-where the various files and classes should be located. This is because this
-depends on the application, library or framework in which you want to use
-the container. Looking at how the container is configured and built in the
-Symfony full-stack Framework will help you see how this all fits together,
+The location of the files and classes related to the Dependency Injection
+component depends on the application, library or framework in which you want
+to use the container. Looking at how the container is configured and built
+in the Symfony full-stack Framework will help you see how this all fits together,
 whether you are using the full-stack framework or looking to use the service
 container in another application.
 

components/dependency_injection/workflow.rst

@@ -81,7 +81,7 @@ This allows you to use jQuery-like selectors to traverse::
 
     $crawler = $crawler->filter('body > p');
 
-Anonymous function can be used to filter with more complex criteria::
+An anonymous function can be used to filter with more complex criteria::
 
     use Symfony\Component\DomCrawler\Crawler;
     // ...

components/dom_crawler.rst

@@ -460,19 +460,29 @@ builder:
 
     .. code-block:: php-symfony
 
+        // src/Acme/TaskBundle/Controller/DefaultController.php
+        namespace Acme\TaskBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
         use Symfony\Component\Form\Extension\Core\Type\TextType;
         use Symfony\Component\Form\Extension\Core\Type\DateType;
 
-        // ...
+        class DefaultController extends Controller
+        {
+            public function newAction(Request $request)
+            {
+                $defaults = array(
+                    'dueDate' => new \DateTime('tomorrow'),
+                );
 
-        $defaults = array(
-            'dueDate' => new \DateTime('tomorrow'),
-        );
+                $form = $this->createFormBuilder($defaults)
+		    ->add('task', TextType::class)
+		    ->add('dueDate', DateType::class)
+                    ->getForm();
 
-        $form = $this->createFormBuilder($defaults)
-            ->add('task', TextType::class)
-            ->add('dueDate', DateType::class)
-            ->getForm();
+                // ...
+            }
+        }
 
 .. tip::
 
@@ -532,18 +542,23 @@ by ``handleRequest()`` to determine whether a form has been submitted):
 
     .. code-block:: php-symfony
 
-        use Symfony\Component\Form\Extension\Core\Type\FormType;
+        // src/Acme/TaskBundle/Controller/DefaultController.php
+        namespace Acme\TaskBundle\Controller;
 
-        // ...
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Symfony\Component\Form\Extension\Core\Type\FormType;
 
-        public function searchAction()
+        class DefaultController extends Controller
         {
-            $formBuilder = $this->createFormBuilder(null, array(
-                'action' => '/search',
-                'method' => 'GET',
-            ));
+            public function searchAction()
+            {
+                $formBuilder = $this->createFormBuilder(null, array(
+                    'action' => '/search',
+                    'method' => 'GET',
+                ));
 
-            // ...
+                // ...
+            }
         }
 
 .. _component-form-intro-handling-submission:
@@ -560,8 +575,8 @@ method:
 
         use Symfony\Component\HttpFoundation\Request;
         use Symfony\Component\HttpFoundation\RedirectResponse;
-        use Symfony\Component\Form\Extension\Core\Type\TextType;
         use Symfony\Component\Form\Extension\Core\Type\DateType;
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
 
         // ...
 
@@ -589,29 +604,34 @@ method:
 
     .. code-block:: php-symfony
 
-        use Symfony\Component\Form\Extension\Core\Type\TextType;
-        use Symfony\Component\Form\Extension\Core\Type\DateType;
+        // src/Acme/TaskBundle/Controller/DefaultController.php
+        namespace Acme\TaskBundle\Controller;
 
-        // ...
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+        use Symfony\Component\Form\Extension\Core\Type\DateType;
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
 
-        public function newAction(Request $request)
+        class DefaultController extends Controller
         {
-            $form = $this->createFormBuilder()
-                ->add('task', TextType::class)
-                ->add('dueDate', DateType::class)
-                ->getForm();
+            public function newAction(Request $request)
+            {
+                $form = $this->createFormBuilder()
+		    ->add('task', TextType::class)
+		    ->add('dueDate', DateType::class)
+                    ->getForm();
 
-            $form->handleRequest($request);
+                $form->handleRequest($request);
 
-            if ($form->isSubmitted() && $form->isValid()) {
-                $data = $form->getData();
+                if ($form->isSubmitted() && $form->isValid()) {
+                    $data = $form->getData();
 
-                // ... perform some action, such as saving the data to the database
+                    // ... perform some action, such as saving the data to the database
 
-                return $this->redirectToRoute('task_success');
-            }
+                    return $this->redirectToRoute('task_success');
+                }
 
-            // ...
+                // ...
+            }
         }
 
 This defines a common form "workflow", which contains 3 different possibilities:
@@ -660,22 +680,33 @@ option when building each field:
 
     .. code-block:: php-symfony
 
+        // src/Acme/TaskBundle/Controller/DefaultController.php
+        namespace Acme\TaskBundle\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\Controller;
         use Symfony\Component\Validator\Constraints\NotBlank;
         use Symfony\Component\Validator\Constraints\Type;
-        use Symfony\Component\Form\Extension\Core\Type\TextType;
         use Symfony\Component\Form\Extension\Core\Type\DateType;
+        use Symfony\Component\Form\Extension\Core\Type\TextType;
 
-        $form = $this->createFormBuilder()
-            ->add('task', TextType::class, array(
-                'constraints' => new NotBlank(),
-            ))
-            ->add('dueDate', DateType::class, array(
-                'constraints' => array(
-                    new NotBlank(),
-                    new Type(\DateTime::class),
-                )
-            ))
-            ->getForm();
+        class DefaultController extends Controller
+        {
+            public function newAction(Request $request)
+            {
+                $form = $this->createFormBuilder()
+		    ->add('task', TextType::class, array(
+                        'constraints' => new NotBlank(),
+                    ))
+		    ->add('dueDate', DateType::class, array(
+                        'constraints' => array(
+                            new NotBlank(),
+                            new Type(\DateTime::class),
+                        )
+                    ))
+                    ->getForm();
+                // ...
+            }
+        }
 
 When the form is bound, these validation constraints will be applied automatically
 and the errors will display next to the fields on error.

components/form.rst

@@ -285,6 +285,7 @@ represents an HTTP message. But when moving from a legacy system, adding
 methods or changing some default behavior might help. In that case, register a
 PHP callable that is able to create an instance of your ``Request`` class::
 
+    use AppBundle\Http\SpecialRequest;
     use Symfony\Component\HttpFoundation\Request;
 
     Request::setFactory(function (

components/http_foundation.rst

@@ -143,6 +143,26 @@ are done doing other stuff::
     which means that your code will halt at this line until the external
     process is completed.
 
+.. note::
+
+    If a ``Response`` is sent **before** a child process had a chance to complete,
+    the server process will be killed (depending on your OS). It means that
+    your task will be stopped right away. Running an asynchronous process
+    is not the same as running a process that survives its parent process.
+
+    If you want your process to survive the request/response cycle, you can
+    take advantage of the ``kernel.terminate`` event, and run your command
+    **synchronously** inside this event. Be aware that ``kernel.terminate``
+    is called only if you use PHP-FPM.
+
+.. caution::
+
+    Beware also that if you do that, the said PHP-FPM process will not be
+    available to serve any new request until the subprocess is finished. This
+    means you can quickly block your FPM pool if you're not careful enough.
+    That is why it's generally way better not to do any fancy things even
+    after the request is sent, but to use a job queue instead.
+
 :method:`Symfony\\Component\\Process\\Process::wait` takes one optional argument:
 a callback that is called repeatedly whilst the process is still running, passing
 in the output and its type::

components/process.rst

@@ -280,7 +280,20 @@ has one file in it::
 
 Template files should live in the ``Resources/views`` directory of whatever directory
 your *kernel* lives in. Since ``AppKernel`` lives in ``app/``, this template lives
-at ``app/Resources/views/micro/random.html.twig``.
+at ``app/Resources/views/micro/random.html.twig``:
+
+.. code-block:: html+twig
+
+    <!-- app/Resources/views/micro/random.html.twig -->
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <title>Random action</title>
+        </head>
+        <body>
+            <p>{{ number }}</p>
+        </body>
+    </html>
 
 Finally, you need a front controller to boot and run the application. Create a
 ``web/index.php``::
@@ -309,7 +322,6 @@ this:
     │  ├─ config/
     │  └─ Resources
     |     └─ views
-    |        ├─ base.html.twig
     |        └─ micro
     |           └─ random.html.twig
     ├─ src/

configuration/micro_kernel_trait.rst

@@ -237,7 +237,7 @@ console::
                 // pass arguments to the helper
                 'username' => 'Wouter',
 
-                // prefix the key with a double slash when passing options,
+                // prefix the key with two dashes when passing options,
                 // e.g: '--some-option' => 'option_value',
             ));
 

console.rst

@@ -12,4 +12,4 @@ these additional resources:
 .. _pull requests:         https://github.com/symfony/symfony/pulls
 .. _commits:               https://github.com/symfony/symfony/commits/master
 .. _bugs and enhancements: https://github.com/symfony/symfony/issues
-.. _bundles:               http://knpbundles.com/
+.. _bundles:               https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories

contributing/community/other.rst

@@ -279,13 +279,9 @@ purposes following these steps:
 
    .. code-block:: terminal
 
-       # Linux and macOS
        $ cd _build/
        $ make html
 
-       # Windows
-       $ _build\make html
-
 The generated documentation is available in the ``_build/html`` directory.
 
 Frequently Asked Questions

contributing/documentation/overview.rst

@@ -203,7 +203,7 @@ other potential things like pushing assets to a CDN (see `Common Post-Deployment
 .. _`Fabric`: http://www.fabfile.org/
 .. _`Magallanes`: https://github.com/andres-montanez/Magallanes
 .. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant
-.. _`bundles that add deployment features`: http://knpbundles.com/search?q=deploy
+.. _`bundles that add deployment features`: https://github.com/search?utf8=✓&q=topic%3Asymfony-bundle+topic%3Adeploy&type=Repositories&ref=searchresults
 .. _`Memcached`: http://memcached.org/
 .. _`Redis`: http://redis.io/
 .. _`Symfony plugin`: https://github.com/capistrano/symfony/

deployment.rst

@@ -245,6 +245,6 @@ Microsoft SQL Server
     If the application stores large amounts of session data, this problem can
     be solved by increasing the column size (use ``BLOB`` or even ``MEDIUMBLOB``).
     When using MySQL as the database engine, you can also enable the `strict SQL mode`_
-    to get noticed when such an error happens.
+    to be notified when such an error happens.
 
 .. _`strict SQL mode`: https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html