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.