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

* upstream/6.4: (81 commits)
  Minor reword
  [HttpClient] fix version added for HAR files feature
  [HTTPClient] Add documentation for `HarFileResponseFactory`
  Fix a typo making CI red
  [Serializer] Custom normalizer deprecation
  [Config] Improve adding support for XML format
  Backport #18598 to 5.4
  Fix Method 'getException' not found in ExceptionEvent
  Corrected return type of anonymous functions
  Restore some internal references
  Minor tweak
  [Form] Improve form validation section
  [OptionsResolver] Fix indentation
  [Documentation] Deprecate annotations
  [Best Practices] Remove annotations paragraph
  [Encore] Webpack Dev Server: live reload & HMR
  Minor tweak
  Update definition.rst
  Minor tweaks
  add `OptionsResolverIntrospector`usage doc
  ...

Author: OskarStark

_images/components/messenger/overview.svg

@@ -207,9 +207,6 @@ Doctrine supports several metadata formats, but it's recommended to use PHP
 attributes because they are by far the most convenient and agile way of setting
 up and looking for mapping information.
 
-If your PHP version doesn't support attributes yet, use annotations, which is
-similar but requires installing some extra dependencies in your project.
-
 Controllers
 -----------
 
@@ -227,11 +224,12 @@ nothing more than a few lines of *glue-code*, so you are not coupling the
 important parts of your application.
 
 .. _best-practice-controller-annotations:
+.. _best-practice-controller-attributes:
 
-Use Attributes or Annotations to Configure Routing, Caching, and Security
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Attributes to Configure Routing, Caching, and Security
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using attributes or annotations for routing, caching, and security simplifies
+Using attributes for routing, caching, and security simplifies
 configuration. You don't need to browse several files created with different
 formats (YAML, XML, PHP): all the configuration is just where you  require it,
 and it only uses one format.
@@ -411,15 +409,15 @@ checks that all application URLs load successfully::
         /**
          * @dataProvider urlProvider
          */
-        public function testPageIsSuccessful($url)
+        public function testPageIsSuccessful($url): void
         {
             $client = self::createClient();
             $client->request('GET', $url);
 
             $this->assertResponseIsSuccessful();
         }
 
-        public function urlProvider()
+        public function urlProvider(): \Generator
         {
             yield ['/'];
             yield ['/posts'];

_images/components/serializer/serializer_workflow.svg

@@ -123,8 +123,8 @@ Event Listeners                                      ``src/EventListener/``
 Configuration (routes, services, etc.)               ``config/``
 Web Assets (CSS, JS, images)                         ``public/``
 Translation files                                    ``translations/``
-Validation (when not using annotations)              ``config/validation/``
-Serialization (when not using annotations)           ``config/serialization/``
+Validation (when not using attributes)               ``config/validation/``
+Serialization (when not using attributes)            ``config/serialization/``
 Templates                                            ``templates/``
 Unit and Functional Tests                            ``tests/``
 ===================================================  ========================================
@@ -163,7 +163,7 @@ If the bundle includes Doctrine ORM entities and/or ODM documents, it's
 recommended to define their mapping using XML files stored in
 ``config/doctrine/``. This allows to override that mapping using the
 :doc:`standard Symfony mechanism to override bundle parts </bundles/override>`.
-This is not possible when using annotations/attributes to define the mapping.
+This is not possible when using attributes to define the mapping.
 
 Tests
 -----

_images/sources/components/messenger/overview.dia

@@ -183,7 +183,7 @@ The ``Configuration`` class to handle the sample configuration looks like::
 
     class Configuration implements ConfigurationInterface
     {
-        public function getConfigTreeBuilder()
+        public function getConfigTreeBuilder(): TreeBuilder
         {
             $treeBuilder = new TreeBuilder('acme_social');
 
@@ -217,7 +217,7 @@ force validation (e.g. if an additional option was passed, an exception will be
 thrown)::
 
     // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php
-    public function load(array $configs, ContainerBuilder $container)
+    public function load(array $configs, ContainerBuilder $container): void
     {
         $configuration = new Configuration();
 
@@ -259,7 +259,7 @@ In your extension, you can load this and dynamically set its arguments::
     use Symfony\Component\Config\FileLocator;
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
-    public function load(array $configs, ContainerBuilder $container)
+    public function load(array $configs, ContainerBuilder $container): void
     {
         $loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
         $loader->load('services.xml');
@@ -288,7 +288,7 @@ In your extension, you can load this and dynamically set its arguments::
         class AcmeHelloExtension extends ConfigurableExtension
         {
             // note that this method is called loadInternal and not load
-            protected function loadInternal(array $mergedConfig, ContainerBuilder $container)
+            protected function loadInternal(array $mergedConfig, ContainerBuilder $container): void
             {
                 // ...
             }
@@ -304,7 +304,7 @@ In your extension, you can load this and dynamically set its arguments::
     (e.g. by overriding configurations and using :phpfunction:`isset` to check
     for the existence of a value). Be aware that it'll be very hard to support XML::
 
-        public function load(array $configs, ContainerBuilder $container)
+        public function load(array $configs, ContainerBuilder $container): void
         {
             $config = [];
             // let resources override the previous set value
@@ -458,7 +458,7 @@ the extension. You might want to change this to a more professional URL::
     {
         // ...
 
-        public function getNamespace()
+        public function getNamespace(): string
         {
             return 'http://acme_company.com/schema/dic/hello';
         }
@@ -490,7 +490,7 @@ can place it anywhere you like. You should return this path as the base path::
     {
         // ...
 
-        public function getXsdValidationBasePath()
+        public function getXsdValidationBasePath(): string
         {
             return __DIR__.'/../Resources/config/schema';
         }

_images/sources/components/serializer/serializer_workflow.dia

@@ -34,7 +34,7 @@ This is how the extension of an AcmeHelloBundle should look like::
 
     class AcmeHelloExtension extends Extension
     {
-        public function load(array $configs, ContainerBuilder $container)
+        public function load(array $configs, ContainerBuilder $container): void
         {
             // ... you'll load the files here later
         }
@@ -90,7 +90,7 @@ For instance, assume you have a file called ``services.xml`` in the
     use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 
     // ...
-    public function load(array $configs, ContainerBuilder $container)
+    public function load(array $configs, ContainerBuilder $container): void
     {
         $loader = new XmlFileLoader(
             $container,
@@ -167,7 +167,7 @@ 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::
 
-    public function load(array $configs, ContainerBuilder $container)
+    public function load(array $configs, ContainerBuilder $container): void
     {
         // ...
 

best_practices.rst

@@ -31,7 +31,7 @@ To give an Extension the power to do this, it needs to implement
     {
         // ...
 
-        public function prepend(ContainerBuilder $container)
+        public function prepend(ContainerBuilder $container): void
         {
             // ...
         }
@@ -52,7 +52,7 @@ a configuration setting in multiple bundles as well as disable a flag in multipl
 in case a specific other bundle is not registered::
 
     // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
-    public function prepend(ContainerBuilder $container)
+    public function prepend(ContainerBuilder $container): void
     {
         // get all bundles
         $bundles = $container->getParameter('kernel.bundles');

bundles/best_practices.rst

@@ -307,9 +307,10 @@ with either :class:`Symfony\\Contracts\\Cache\\CacheInterface` or
 ``Psr\Cache\CacheItemPoolInterface``::
 
     use Symfony\Contracts\Cache\CacheInterface;
+    // ...
 
     // from a controller method
-    public function listProducts(CacheInterface $customThingCache)
+    public function listProducts(CacheInterface $customThingCache): Response
     {
         // ...
     }
@@ -555,7 +556,7 @@ the same key could be invalidated with one function call::
         ) {
         }
 
-        public function someMethod()
+        public function someMethod(): void
         {
             $value0 = $this->myCachePool->get('item_0', function (ItemInterface $item): string {
                 $item->tag(['foo', 'bar']);