Merge branch '2.7' into fix_7530

Author: HeahDude

best_practices/controllers.rst

@@ -95,6 +95,7 @@ for the homepage of our app:
 
     namespace AppBundle\Controller;
 
+    use AppBundle\Entity\Post;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
@@ -106,7 +107,7 @@ for the homepage of our app:
         public function indexAction()
         {
             $posts = $this->getDoctrine()
-                ->getRepository('AppBundle:Post')
+                ->getRepository(Post::class)
                 ->findLatest();
 
             return $this->render('default/index.html.twig', array(
@@ -170,7 +171,7 @@ manually. In our application, we have this situation in ``CommentController``:
     public function newAction(Request $request, $postSlug)
     {
         $post = $this->getDoctrine()
-            ->getRepository('AppBundle:Post')
+            ->getRepository(Post::class)
             ->findOneBy(array('slug' => $postSlug));
 
         if (!$post) {

best_practices/security.rst

@@ -226,7 +226,7 @@ more advanced use-case, you can always do the same security check in PHP:
      */
     public function editAction($id)
     {
-        $post = $this->getDoctrine()->getRepository('AppBundle:Post')
+        $post = $this->getDoctrine()->getRepository(Post::class)
             ->find($id);
 
         if (!$post) {

best_practices/templates.rst

@@ -30,22 +30,20 @@ Template Locations
     Store all your application's templates in ``app/Resources/views/`` directory.
 
 Traditionally, Symfony developers stored the application templates in the
-``Resources/views/`` directory of each bundle. Then they used the logical name
-to refer to them (e.g. ``AcmeDemoBundle:Default:index.html.twig``).
+``Resources/views/`` directory of each bundle. Then they used the Twig namespaced
+path to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``).
 
 But for the templates used in your application, it's much more convenient
 to store them in the ``app/Resources/views/`` directory. For starters, this
 drastically simplifies their logical names:
 
-=================================================  ==================================
-Templates Stored inside Bundles                    Templates Stored in ``app/``
-=================================================  ==================================
-``AcmeDemoBundle:Default:index.html.twig``         ``default/index.html.twig``
-``::layout.html.twig``                             ``layout.html.twig``
-``AcmeDemoBundle::index.html.twig``                ``index.html.twig``
-``AcmeDemoBundle:Default:subdir/index.html.twig``  ``default/subdir/index.html.twig``
-``AcmeDemoBundle:Default/subdir:index.html.twig``  ``default/subdir/index.html.twig``
-=================================================  ==================================
+============================================  ==================================
+Templates Stored inside Bundles               Templates Stored in ``app/``
+============================================  ==================================
+``@AcmeDemo/index.html.twig``                 ``index.html.twig``
+``@AcmeDemo/Default/index.html.twig``         ``default/index.html.twig``
+``@AcmeDemo/Default/subdir/index.html.twig``  ``default/subdir/index.html.twig``
+============================================  ==================================
 
 Another advantage is that centralizing your templates simplifies the work
 of your designers. They don't need to look for templates in lots of directories
@@ -131,7 +129,7 @@ service in the constructor of the Twig extension:
                 new \Twig_SimpleFilter(
                     'md2html',
                     array($this, 'markdownToHtml'),
-                    array('is_safe' => array('html'))
+                    array('is_safe' => array('html'), 'pre_escape' => 'html')
                 ),
             );
         }

bundles/best_practices.rst

@@ -471,6 +471,21 @@ API is being used. The following code, would work for *all* users::
         }
     }
 
+Resources
+---------
+
+If the bundle references any resources (config files, translation files, etc.),
+don't use physical paths (e.g. ``__DIR__/config/services.xml``) but logical
+paths (e.g. ``@AppBundle/Resources/config/services.xml``).
+
+The logical paths are required because of the bundle overriding mechanism that
+lets you override any resource/file of any bundle. See :ref:`http-kernel-resource-locator`
+for more details about transforming physical paths into logical paths.
+
+Beware that templates use a simplified version of the logical path shown above.
+For example, an ``index.html.twig`` template located in the ``Resources/views/Default/``
+directory of the AppBundle, is referenced as ``@App/Default/index.html.twig``.
+
 Learn more
 ----------
 

bundles/override.rst

@@ -7,6 +7,14 @@ How to Override any Part of a Bundle
 This document is a quick reference for how to override different parts of
 third-party bundles.
 
+.. tip::
+
+    The bundle overriding mechanism means that you cannot use physical paths to
+    refer to bundle's resources (e.g. ``__DIR__/config/services.xml``). Always
+    use logical paths in your bundles (e.g. ``@AppBundle/Resources/config/services.xml``)
+    and call the :ref:`locateResource() method <http-kernel-resource-locator>`
+    to turn them into physical paths when needed.
+
 Templates
 ---------
 

components/console/helpers/dialoghelper.rst

@@ -142,11 +142,15 @@ in the console, so it is a good practice to put some useful information in it. T
 function should also return the value of the user's input if the validation was successful.
 
 You can set the max number of times to ask in the ``$attempts`` argument.
-If you reach this max number it will use the default value.
 Using ``false`` means the amount of attempts is infinite.
 The user will be asked as long as they provide an invalid answer and will only
 be able to proceed if their input is valid.
 
+Each time the user is asked the question, the default one is used if no answer
+is supplied (and validated with the ``$validator`` callback). If the last
+attempt is reached, the application will throw an exception and ends its
+execution.
+
 Validating a Hidden Response
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

components/dom_crawler.rst

@@ -338,10 +338,19 @@ given text. This method is especially useful because you can use it to return
 a :class:`Symfony\\Component\\DomCrawler\\Form` object that represents the
 form that the button lives in::
 
-    $form = $crawler->selectButton('validate')->form();
+    // button example: <button id="my-super-button" type="submit">My super button</button>
+    
+    // you can get button by its label
+    $form = $crawler->selectButton('My super button')->form();
+    
+    // or by button id (#my-super-button) if the button doesn't have a label
+    $form = $crawler->selectButton('my-super-button')->form();
+    
+    // or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
+    $crawler->filter('.form-vertical')->form();
 
     // or "fill" the form fields with data
-    $form = $crawler->selectButton('validate')->form(array(
+    $form = $crawler->selectButton('my-super-button')->form(array(
         'name' => 'Ryan',
     ));
 

components/form.rst

@@ -408,7 +408,7 @@ is created from the form factory.
                     ->add('dueDate', 'date')
                     ->getForm();
 
-                return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
+                return $this->render('@AcmeTask/Default/new.html.twig', array(
                     'form' => $form->createView(),
                 ));
             }

components/http_foundation.rst

@@ -468,8 +468,12 @@ represented by a PHP callable instead of a string::
     you must call ``ob_flush()`` before ``flush()``.
 
     Additionally, PHP isn't the only layer that can buffer output. Your web
-    server might also buffer based on its configuration. What's more, if you
-    use FastCGI, buffering can't be disabled at all.
+    server might also buffer based on its configuration. Some servers, such as
+    Nginx, let you disable buffering at config level or adding a special HTTP
+    header in the response::
+
+        // disables FastCGI buffering in Nginx only for this response
+        $response->headers->set('X-Accel-Buffering', 'no')
 
 .. _component-http-foundation-serving-files:
 

components/http_kernel.rst

@@ -592,7 +592,7 @@ each event has their own event object:
 =====================  ================================  ===================================================================================
 Name                   ``KernelEvents`` Constant         Argument passed to the listener
 =====================  ================================  ===================================================================================
-kernel.request         ``KernelEvents::REQUEST``         :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`                    
+kernel.request         ``KernelEvents::REQUEST``         :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`
 kernel.controller      ``KernelEvents::CONTROLLER``      :class:`Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent`
 kernel.view            ``KernelEvents::VIEW``            :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForControllerResultEvent`
 kernel.response        ``KernelEvents::RESPONSE``        :class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`
@@ -701,6 +701,32 @@ look like this::
         // ...
     }
 
+.. _http-kernel-resource-locator:
+
+Locating Resources
+------------------
+
+The HttpKernel component is responsible of the bundle mechanism used in Symfony
+applications. The key feature of the bundles is that they allow to override any
+resource used by the application (config files, templates, controllers,
+translation files, etc.)
+
+This overriding mechanism works because resources are referenced not by their
+physical path but by their logical path. For example, the ``services.xml`` file
+stored in the ``Resources/config/`` directory of a bundle called AppBundle is
+referenced as ``@AppBundle/Resources/config/services.xml``. This logical path
+will work when the application overrides that file and even if you change the
+directory of AppBundle.
+
+The HttpKernel component provides a method called :method:`Symfony\\Component\\HttpKernel\\Kernel::locateResource`
+which can be used to transform logical paths into physical paths::
+
+    use Symfony\Component\HttpKernel\HttpKernel;
+
+    // ...
+    $kernel = new HttpKernel($dispatcher, $resolver);
+    $path = $kernel->locateResource('@AppBundle/Resources/config/services.xml');
+
 Learn more
 ----------
 

components/phpunit_bridge.rst

@@ -37,10 +37,16 @@ You can install the component in 2 different ways:
 Usage
 -----
 
-Once the component is installed, it automatically registers a
-`PHPUnit event listener`_ which in turn registers a `PHP error handler`_
-called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`. After
-running your PHPUnit tests, you will get a report similar to this one:
+Once the component is installed, a ``simple-phpunit`` script is created in the
+``vendor/`` directory to run tests. This script wraps the original PHPUnit binary
+to provide more features:
+
+.. code-block:: terminal
+
+    $ cd my-project/
+    $ ./vendor/bin/simple-phpunit
+
+After running your PHPUnit tests, you will get a report similar to this one:
 
 .. image:: /_images/components/phpunit_bridge/report.png
 
@@ -57,6 +63,21 @@ The summary includes:
     Deprecation notices are all other (non-legacy) notices, grouped by message,
     test class and method.
 
+.. note::
+
+    If you don't want to use the ``simple-phpunit`` script, register the following
+    `PHPUnit event listener`_ in your PHPUnit configuration file to get the same
+    report about deprecations (which is created by a `PHP error handler`_
+    called :class:`Symfony\\Bridge\\PhpUnit\\DeprecationErrorHandler`):
+
+    .. code-block:: xml
+
+        <!-- phpunit.xml.dist -->
+        <!-- ... -->
+        <listeners>
+            <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+        </listeners>
+
 Trigger Deprecation Notices
 ---------------------------
 

components/security/authorization.rst

@@ -122,7 +122,7 @@ on a "remember-me" cookie, or even authenticated anonymously?
     use Symfony\Component\Security\Core\Authentication\Token\RememberMeToken;
 
     $anonymousClass = AnonymousToken::class;
-    $rememberMeClass = RememberMeToken::Class;
+    $rememberMeClass = RememberMeToken::class;
 
     $trustResolver = new AuthenticationTrustResolver($anonymousClass, $rememberMeClass);
 

components/validator.rst

@@ -46,6 +46,8 @@ characters long::
         }
     }
 
+The validator returns the list of violations.
+
 Retrieving a Validator Instance
 -------------------------------
 

configuration/multiple_kernels.rst

@@ -178,6 +178,43 @@ In order to solve this issue, add the following configuration to your kernel:
             # allows to use app/Resources/views/ templates in the ApiKernel
             "%kernel.root_dir%/../app/Resources/views": ~
 
+Running Tests Using a Different Kernel
+--------------------------------------
+
+In Symfony applications, functional tests extend by default from the
+:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase` class. Inside that
+class, a method called ``getKernelClass()`` tries to find the class of the kernel
+to use to run the application during tests. The logic of this method does not
+support multiple kernel applications, so your tests won't use the right kernel.
+
+The solution is to create a custom base class for functional tests extending
+from ``WebTestCase`` class and overriding the ``getKernelClass()`` method to
+return the fully qualified class name of the kernel to use::
+
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+
+    // tests needing the ApiKernel to work, now must extend this
+    // ApiTestCase class instead of the default WebTestCase class
+    class ApiTestCase extends WebTestCase
+    {
+        protected static function getKernelClass()
+        {
+            return 'ApiKernel';
+        }
+
+        // this is needed because the KernelTestCase class keeps a reference to
+        // the previously created kernel in its static $kernel property. Thus,
+        // if your functional tests do not run in isolated processes, a later run
+        // test for a different kernel will reuse the previously created instance,
+        // which points to a different kernel
+        protected function tearDown()
+        {
+            parent::tearDown();
+
+            static::$class = null;
+        }
+    }
+
 Adding more Kernels to the Application
 --------------------------------------
 

console/input.rst

@@ -91,11 +91,12 @@ There are three argument variants you can use:
     provided;
 
 ``InputArgument::OPTIONAL``
-    The argument is optional and therefore can be omitted;
+    The argument is optional and therefore can be omitted. This is the default
+    behavior of arguments;
 
 ``InputArgument::IS_ARRAY``
     The argument can contain any number of values. For that reason, it must be
-    used at the end of the argument list
+    used at the end of the argument list.
 
 You can combine ``IS_ARRAY`` with ``REQUIRED`` and ``OPTIONAL`` like this::
 
@@ -177,11 +178,15 @@ There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
     This option accepts multiple values (e.g. ``--dir=/foo --dir=/bar``);
+
 ``InputOption::VALUE_NONE``
-    Do not accept input for this option (e.g. ``--yell``);
+    Do not accept input for this option (e.g. ``--yell``). This is the default
+    behavior of options;
+
 ``InputOption::VALUE_REQUIRED``
     This value is required (e.g. ``--iterations=5``), the option itself is
     still optional;
+
 ``InputOption::VALUE_OPTIONAL``
     This option may or may not have a value (e.g. ``--yell`` or
     ``--yell=loud``).