Merge remote-tracking branch 'upstream/master'

* upstream/master:
  Remove old deprecated directive
  Add missing deprecated directive for kernel.log_dir parameter
  Correct log dir parameter
  s/bahavior/behavior
  Use uppercase in title
  Fix XML syntax
  removing notes about doctrine_clear_entity_manager middleware
  There is no handler file in storage
  Missing closing parentheses and closing bracket
  Remove unused imports
  Add missing semicolon
  User double \ instead of four \ in expression service
  [PHPUnit Bridge] Minor tweaks related to polyfills
  Fix DOCtor-RST build on master
  Complete doc for 4.4 features
  Adapted the HTTPlug integration docs to Async Client

Author: javiereguiluz

.doctor-rst.yaml

@@ -82,3 +82,4 @@ whitelist:
         - '$var .= "Because of this `\xE9` octet (\\xE9),\n";'
         - "`Deploying Symfony 4 Apps on Heroku`_."
         - ".. _`Deploying Symfony 4 Apps on Heroku`: https://devcenter.heroku.com/articles/deploying-symfony4"
+        - "//                  224, 165, 141, 224, 164, 164, 224, 165, 135])"

bundles/extension.rst

@@ -119,10 +119,6 @@ they are compiled when generating the application cache to improve the overall
 performance. Define the list of annotated classes to compile in the
 ``addAnnotatedClassesToCompile()`` method::
 
-    use App\Manager\UserManager;
-    use App\Utils\Slugger;
-
-    // ...
     public function load(array $configs, ContainerBuilder $container)
     {
         // ...

components/http_client.rst

@@ -124,8 +124,8 @@ The HTTP client supports different authentication mechanisms. They can be
 defined globally when creating the client (to apply it to all requests) and to
 each request (which overrides any global authentication)::
 
-    // Use the same authentication for all requests
-    $client = HttpClient::create([
+    // Use the same authentication for all requests to https://example.com/
+    $client = HttpClient::createForBaseUri('https://example.com/', [
         // HTTP Basic authentication (there are multiple ways of configuring it)
         'auth_basic' => ['the-username'],
         'auth_basic' => ['the-username', 'the-password'],
@@ -150,6 +150,8 @@ each request (which overrides any global authentication)::
 .. note::
 
     The NTLM authentication mechanism requires using the cURL transport.
+    By using ``HttpClient::createForBaseUri()``, we ensure that the auth credentials
+    won't be sent to any other hosts than https://example.com/.
 
 Query String Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -366,10 +368,7 @@ Call the ``stream()`` method of the HTTP client to get *chunks* of the
 response sequentially instead of waiting for the entire response::
 
     $url = 'https://releases.ubuntu.com/18.04.1/ubuntu-18.04.1-desktop-amd64.iso';
-    $response = $client->request('GET', $url, [
-        // optional: if you don't want to buffer the response in memory
-        'buffer' => false,
-    ]);
+    $response = $client->request('GET', $url);
 
     // Responses are lazy: this code is executed as soon as headers are received
     if (200 !== $response->getStatusCode()) {
@@ -383,6 +382,14 @@ response sequentially instead of waiting for the entire response::
         fwrite($fileHandler, $chunk->getContent());
     }
 
+.. note::
+
+    By default, ``text/*``, JSON and XML response bodies are buffered in a local
+    ``php://temp`` stream. You can control this behavior by using the ``buffer``
+    option: set it to ``true``/``false`` to enable/disable buffering, or to a
+    closure that should return the same based on the response headers it receives
+    as argument.
+
 Canceling Responses
 ~~~~~~~~~~~~~~~~~~~
 
@@ -525,6 +532,8 @@ response and get remaining contents that might come back in a new timeout, etc.
     is idle*. Big responses can last as long as needed to complete, provided they
     remain active during the transfer and never pause for longer than specified.
 
+    Use the ``max_duration`` option to limit the time a full request/response can last.
+
 Dealing with Network Errors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -650,15 +659,15 @@ or if it matches the ``https://api.github.com/`` base URI.
 Interoperability
 ----------------
 
-The component is interoperable with three different abstractions for HTTP
-clients: `Symfony Contracts`_, `PSR-18`_ and `HTTPlug`_ v1 and v2. If your
-application uses libraries that need any of them, the component is compatible
+The component is interoperable with four different abstractions for HTTP
+clients: `Symfony Contracts`_, `PSR-18`_, `HTTPlug`_ v1/v2 and native PHP streams.
+If your application uses libraries that need any of them, the component is compatible
 with all of them. They also benefit from :ref:`autowiring aliases <service-autowiring-alias>`
 when the :ref:`framework bundle <framework-bundle-configuration>` is used.
 
 If you are writing or maintaining a library that makes HTTP requests, you can
 decouple it from any specific HTTP client implementations by coding against
-either Symfony Contracts (recommended) or PSR-18 (which superseded HTTPlug).
+either Symfony Contracts (recommended), PSR-18 or HTTPlug v2.
 
 Symfony Contracts
 ~~~~~~~~~~~~~~~~~
@@ -676,7 +685,7 @@ interface you need to code against when a client is needed::
 
         public function __construct(HttpClientInterface $client)
         {
-            $this->client = $client
+            $this->client = $client;
         }
 
         // [...]
@@ -685,7 +694,7 @@ interface you need to code against when a client is needed::
 All request options mentioned above (e.g. timeout management) are also defined
 in the wordings of the interface, so that any compliant implementations (like
 this component) is guaranteed to provide them. That's a major difference with
-the PSR-18 abstraction, which provides none related to the transport itself.
+the other abstractions, which provide none related to the transport itself.
 
 Another major feature covered by the Symfony Contracts is async/multiplexing,
 as described in the previous sections.
@@ -710,6 +719,10 @@ To use it, you need the ``psr/http-client`` package and a `PSR-17`_ implementati
     # with autowiring aliases provided by Symfony Flex
     $ composer require nyholm/psr7
 
+    # alternatively, install the php-http/discovery package to auto-discover
+    # any already installed implementations from common vendors:
+    # composer require php-http/discovery
+
 Now you can make HTTP requests with the PSR-18 client as follows::
 
     use Symfony\Component\HttpClient\Psr18Client;
@@ -725,27 +738,26 @@ Now you can make HTTP requests with the PSR-18 client as follows::
 HTTPlug
 ~~~~~~~
 
-The `HTTPlug`_ specification was published before PSR-18 and is superseded by
-it. As such, you should not use it in newly written code. Yet, many libraries
-still require v1 or v2 of it. The component is interoperable with them thanks to
-the ``HttplugClient`` adapter class. Similarly to ``Psr18Client`` implementing
-relevant parts of PSR-17, ``HttplugClient`` also implements the factory methods
-defined in the related ``php-http/message-factory`` package.
-
-Internally, the implementation relies on the ``Psr18Client``, so that the
-``psr/http-client`` package is needed to use this class:
+The `HTTPlug`_ v1 specification was published before PSR-18 and is superseded by
+it. As such, you should not use it in newly written code. The component is still
+interoperable with libraries that require it thanks to the
+:class:`Symfony\\Component\\HttpClient\\HttplugClient` class. Similarly to
+``Psr18Client`` implementing relevant parts of PSR-17, ``HttplugClient`` also
+implements the factory methods defined in the related ``php-http/message-factory``
+package.
 
 .. code-block:: terminal
 
     # Let's suppose php-http/httplug is already required by the lib you want to use
 
-    # installs the PSR-18 ClientInterface
-    $ composer require psr/http-client
-
     # installs an efficient implementation of response and stream factories
     # with autowiring aliases provided by Symfony Flex
     $ composer require nyholm/psr7
 
+    # alternatively, install the php-http/discovery package to auto-discover
+    # any already installed implementations from common vendors:
+    # composer require php-http/discovery
+
 Let's say you want to instantiate a class with the following constructor,
 that requires HTTPlug dependencies::
 
@@ -770,6 +782,72 @@ Because ``HttplugClient`` implements the three interfaces, you can use it this w
     $httpClient = new HttplugClient();
     $apiClient = new SomeSdk($httpClient, $httpClient, $httpClient);
 
+If you'd like to work with promises, ``HttplugClient`` also implements the
+``HttpAsyncClient`` interface. To use it, you need to install the
+``guzzlehttp/promises`` package:
+
+.. code-block:: terminal
+
+    $ composer require guzzlehttp/promises
+
+Then you're ready to go::
+
+    use Psr\Http\Message\ResponseInterface;
+    use Symfony\Component\HttpClient\HttplugClient;
+
+    $httpClient = new HttplugClient();
+    $request = $httpClient->createRequest('GET', 'https://my.api.com/');
+    $promise = $httpClient->sendRequest($request)
+        ->then(
+            function (ResponseInterface $response) {
+                echo 'Got status '.$response->getStatusCode();
+
+                return $response;
+            },
+            function (\Throwable $exception) {
+                echo 'Error: '.$exception->getMessage();
+
+                throw $exception;
+            }
+        );
+
+    // after you're done with sending several requests,
+    // you must wait for them to complete concurrently
+
+    // wait for a specific promise to resolve while monitoring them all
+    $response = $promise->wait();
+
+    // wait maximum 1 second for pending promises to resolve
+    $httpClient->wait(1.0);
+
+    // wait for all remaining promises to resolve
+    $httpClient->wait();
+
+Native PHP Streams
+~~~~~~~~~~~~~~~~~~
+
+Responses implementing :class:`Symfony\\Contracts\\HttpClient\\ResponseInterface`
+can be cast to native PHP streams with
+:method:`Symfony\\Component\\HttpClient\\Response\\StreamWrapper::createResource``.
+This allows using them where native PHP streams are needed::
+
+    use Symfony\Component\HttpClient\HttpClient;
+    use Symfony\Component\HttpClient\Response\StreamWrapper;
+
+    $client = HttpClient::create();
+    $response = $client->request('GET', 'https://symfony.com/versions.json');
+
+    $streamResource = StreamWrapper::createResource($response, $client);
+
+    // alternatively and contrary to the previous one, this returns
+    // a resource that is seekable and potentially stream_select()-able
+    $streamResource = $response->toStream();
+
+    echo stream_get_contents($streamResource); // outputs the content of the response
+
+    // later on if you need to, you can access the response from the stream
+    $response = stream_get_meta_data($streamResource)['wrapper_data']->getResponse();
+
 Symfony Framework Integration
 -----------------------------
 

components/messenger.rst

@@ -296,7 +296,7 @@ do is to write your own CSV receiver::
                 throw $exception;
             }
 
-            return [$envelope->with(new CustomStamp($yourEnvelope['id']);
+            return [$envelope->with(new CustomStamp($yourEnvelope['id']))];
         }
 
         public function ack(Envelope $envelope): void

components/phpunit_bridge.rst

@@ -389,7 +389,7 @@ Polyfills for the Unavailable Methods
 
 When using the ``simple-phpunit`` script, PHPUnit Bridge injects polyfills for
 most methods of the ``TestCase`` and ``Assert`` classes (e.g. ``expectException()``,
-``expectExcpetionMessage()``, ``assertContainsEquals``, etc.). This allows writing
+``expectExceptionMessage()``, ``assertContainsEquals()``, etc.). This allows writing
 test cases using the latest best practices while still remaining compatible with
 older PHPUnit versions.
 
@@ -413,18 +413,18 @@ call to the ``doSetUp()``, ``doTearDown()``, ``doSetUpBeforeClass()`` and
 
     class MyTest extends TestCase
     {
+        // when using the SetUpTearDownTrait, methods like doSetup() can
+        // be defined with and without the 'void' return type, as you wish
         use SetUpTearDownTrait;
 
-        private $state;
-
         private function doSetup()
         {
-            $this->state = 'demo';
+            // ...
         }
 
         protected function doSetup(): void
         {
-            // visibility and return type-hint of method is free
+            // ...
         }
     }
 
@@ -686,7 +686,7 @@ toggle a behavior::
         public function hello(): string
         {
             if (class_exists(DependencyClass::class)) {
-                return 'The dependency bahavior.';
+                return 'The dependency behavior.';
             }
 
             return 'The default behavior.';
@@ -704,7 +704,7 @@ are installed during tests) would look like::
         public function testHello()
         {
             $class = new MyClass();
-            $result = $class->hello(); // "The dependency bahavior."
+            $result = $class->hello(); // "The dependency behavior."
 
             // ...
         }
@@ -728,7 +728,7 @@ classes, interfaces and/or traits for the code to run::
             ClassExistsMock::withMockedClasses([DependencyClass::class => false]);
 
             $class = new MyClass();
-            $result = $class->hello(); // "The default bahavior."
+            $result = $class->hello(); // "The default behavior."
 
             // ...
         }

doctrine/pdo_session_storage.rst

@@ -184,7 +184,7 @@ Preparing the Database to Store Sessions
 
 Before storing sessions in the database, you must create the table that stores
 the information. The session handler provides a method called
-:method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler::createTable`
+:method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\PdoSessionHandler::createTable`
 to set up this table for you according to the database engine used::
 
     try {

messenger.rst

@@ -1379,11 +1379,6 @@ may want to use:
                             # or pass a different entity manager to any
                             #- doctrine_transaction: ['custom']
 
-                            # After handling, the clear() method is executed in the
-                            # entity manager, which reduces the memory consumption and
-                            # avoids side-effects related to unrefreshed entities
-                            - doctrine_clear_entity_manager
-
     .. code-block:: xml
 
         <!-- config/packages/messenger.xml -->
@@ -1409,8 +1404,6 @@ may want to use:
                             <framework:argument>custom</framework:argument>
                         </framework:middleware>
                         -->
-
-                        <framework:middleware id="doctrine_clear_entity_manager"/>
                     </framework:bus>
                 </framework:messenger>
             </framework:config>
@@ -1429,7 +1422,6 @@ may want to use:
                             'doctrine_close_connection',
                             // Using another entity manager
                             ['id' => 'doctrine_transaction', 'arguments' => ['custom']],
-                            'doctrine_clear_entity_manager',
                         ],
                     ],
                 ],

reference/configuration/kernel.rst

@@ -107,7 +107,7 @@ This returns the absolute path of the log directory of your Symfony project.
 It's calculated automatically based on the current
 :ref:`environment <configuration-environments>`.
 
-This value is exposed via the ``kernel.log_dir`` configuration parameter and
+This value is exposed via the ``kernel.logs_dir`` configuration parameter and
 the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. To
 change this setting, override the ``getLogDir()`` method to return the right
 log directory.

routing.rst

@@ -431,7 +431,6 @@ defined as ``/blog/{slug}``:
 
             <route id="blog_show" path="/blog/{slug}"
                    controller="App\Controller\BlogController::show"/>
-            </route>
         </routes>
 
     .. code-block:: php
@@ -525,7 +524,6 @@ the ``{page}`` parameter using the ``requirements`` option:
 
             <route id="blog_show" path="/blog/{slug}"
                    controller="App\Controller\BlogController::show"/>
-            </route>
         </routes>
 
     .. code-block:: php

service_container/expression_language.rst

@@ -28,7 +28,9 @@ to another service: ``App\Mailer``. One way to do this is with an expression:
             App\Mail\MailerConfiguration: ~
 
             App\Mailer:
-                arguments: ["@=service('App\\\\Mail\\\\MailerConfiguration').getMailerMethod()"]
+                arguments: ['@=service("App\\Mail\\MailerConfiguration").getMailerMethod()']
+                # when using double-quoted strings, the backslash needs to be escaped twice (see https://yaml.org/spec/1.2/spec.html#id2787109)
+                # arguments: ["@=service('App\\\\Mail\\\\MailerConfiguration').getMailerMethod()"]
 
     .. code-block:: xml