Merge remote-tracking branch 'upstream/3.3' into 3.3

Author: javiereguiluz

_images/controller/error_pages/exceptions-in-dev-environment.png

@@ -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(
@@ -186,7 +187,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) {

_images/install/deprecations-in-profiler.png

@@ -204,7 +204,6 @@ and a ``createAction()`` that *only* processes the form submit. Both those
 actions will be almost identical. So it's much simpler to let ``newAction()``
 handle everything.
 
-Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
-for clarity. This isn't technically needed, since ``isValid()`` first calls
-``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
-like the form is *always* processed (even on the GET request).
+Second, is it required to call ``$form->isSubmitted()`` in the ``if`` statement
+before calling ``isValid()``. Calling ``isValid()`` with an unsubmitted form
+is deprecated since version 3.2 and will throw an exception in 4.0.

best_practices/controllers.rst

@@ -227,7 +227,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')
+            ->getRepository(Post::class)
             ->find($id);
 
         if (!$post) {

best_practices/forms.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
@@ -121,7 +119,7 @@ class 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')
                 ),
             );
         }

best_practices/security.rst

@@ -429,6 +429,21 @@ The ``composer.json`` file should include at least the following metadata:
 In order to make it easier for developers to find your bundle, register it on
 `Packagist`_, the official repository for Composer packages.
 
+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
 ----------
 

best_practices/templates.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
 ---------
 

bundles/best_practices.rst

@@ -212,14 +212,15 @@ convenient for passwords::
     On Windows systems, this ``stty`` command may generate gibberish output and
     mangle the input text. If that's your case, disable it with this command::
 
+        use Symfony\Component\Console\Helper\QuestionHelper;
         use Symfony\Component\Console\Question\ChoiceQuestion;
 
         // ...
         public function execute(InputInterface $input, OutputInterface $output)
         {
             // ...
             $helper = $this->getHelper('question');
-            $helper->disableStty();
+            QuestionHelper::disableStty();
 
             // ...
         }

bundles/override.rst

@@ -396,10 +396,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/console/helpers/questionhelper.rst

@@ -21,7 +21,7 @@ method after parsing any expression to get its AST::
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
     $ast = (new ExpressionLanguage())
-        ->parse('1 + 2')
+        ->parse('1 + 2', array())
         ->getNodes()
     ;
 
@@ -41,7 +41,7 @@ method to turn the AST into an array::
     // ...
 
     $astAsArray = (new ExpressionLanguage())
-        ->parse('1 + 2')
+        ->parse('1 + 2', array())
         ->getNodes()
         ->toArray()
     ;

components/dom_crawler.rst

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

components/expression_language/ast.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/form.rst

@@ -742,6 +742,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/http_foundation.rst

@@ -56,10 +56,16 @@ to register a new `test listener`_ called ``SymfonyTestsListener``:
 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
 
@@ -76,6 +82,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/http_kernel.rst

@@ -348,8 +348,17 @@ Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\R
 provides list, type and access information from setter and accessor methods.
 It can also provide return and scalar types for PHP 7+.
 
-This service is automatically registered with the ``property_info`` service in
-the Symfony Framework.
+.. note::
+
+    When using the Symfony framework, this service is automatically registered
+    when the ``property_info`` feature is enabled:
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            property_info:
+                enabled: true
 
 .. code-block:: php
 

components/phpunit_bridge.rst

@@ -110,7 +110,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/property_info.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.project_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
 --------------------------------------
 

components/security/authorization.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``).

configuration/multiple_kernels.rst

@@ -30,7 +30,7 @@ that adds two convenient methods to lock and release commands::
             }
 
             // If you prefer to wait until the lock is released, use this:
-            // $this->lock(true);
+            // $this->lock(null, true);
 
             // ...