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

* upstream/7.0: (98 commits)
  Minor reword
  [HttpClient] fix version added for HAR files feature
  [HTTPClient] Add documentation for `HarFileResponseFactory`
  Fix a typo making CI red
  [Security] Remove deprecated XML config
  [Serializer] Custom normalizer deprecation
  [Serializer] Custom normalizer update
  [Config] Improve adding support for XML format
  Backport symfony#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
  ...

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']);

bundles/configuration.rst

@@ -203,19 +203,19 @@ every day::
 
     class DateVersionStrategy implements VersionStrategyInterface
     {
-        private $version;
+        private \DateTimeInterface $version;
 
         public function __construct()
         {
             $this->version = date('Ymd');
         }
 
-        public function getVersion(string $path)
+        public function getVersion(string $path): \DateTimeInterface
         {
             return $this->version;
         }
 
-        public function applyVersion(string $path)
+        public function applyVersion(string $path): string
         {
             return sprintf('%s?v=%s', $path, $this->getVersion($path));
         }

bundles/extension.rst

@@ -38,7 +38,7 @@ This method accepts a request and should return a response::
 
     class Client extends AbstractBrowser
     {
-        protected function doRequest($request)
+        protected function doRequest($request): Response
         {
             // ... convert request into a response
 

bundles/prepend_extension.rst

@@ -54,7 +54,7 @@ implements the :class:`Symfony\\Component\\Config\\Definition\\ConfigurationInte
 
     class DatabaseConfiguration implements ConfigurationInterface
     {
-        public function getConfigTreeBuilder()
+        public function getConfigTreeBuilder(): TreeBuilder
         {
             $treeBuilder = new TreeBuilder('database');
 
@@ -568,7 +568,9 @@ be large and you may want to split it up into sections. You can do this
 by making a section a separate node and then appending it into the main
 tree with ``append()``::
 
-    public function getConfigTreeBuilder()
+    use Symfony\Component\Config\Definition\Builder\NodeDefinition;
+
+    public function getConfigTreeBuilder(): TreeBuilder
     {
         $treeBuilder = new TreeBuilder('database');
 
@@ -597,7 +599,7 @@ tree with ``append()``::
         return $treeBuilder;
     }
 
-    public function addParametersNode()
+    public function addParametersNode(): NodeDefinition
     {
         $treeBuilder = new TreeBuilder('parameters');
 
@@ -891,3 +893,8 @@ Otherwise the result is a clean array of configuration values::
         $databaseConfiguration,
         $configs
     );
+
+.. caution::
+
+    When processing the configuration tree, the processor assumes that the top
+    level array key (which matches the extension name) is already stripped off.

cache.rst

@@ -30,7 +30,7 @@ an array containing all matches.
 Resource Loaders
 ----------------
 
-For each type of resource (YAML, XML, annotation, etc.) a loader must be
+For each type of resource (YAML, XML, attributes, etc.) a loader must be
 defined. Each loader should implement
 :class:`Symfony\\Component\\Config\\Loader\\LoaderInterface` or extend the
 abstract :class:`Symfony\\Component\\Config\\Loader\\FileLoader` class,
@@ -43,7 +43,7 @@ which allows for recursively importing other resources::
 
     class YamlUserLoader extends FileLoader
     {
-        public function load($resource, $type = null)
+        public function load($resource, $type = null): void
         {
             $configValues = Yaml::parse(file_get_contents($resource));
 
@@ -54,7 +54,7 @@ which allows for recursively importing other resources::
             // $this->import('extra_users.yaml');
         }
 
-        public function supports($resource, $type = null)
+        public function supports($resource, $type = null): bool
         {
             return is_string($resource) && 'yaml' === pathinfo(
                 $resource,

components/asset.rst

@@ -15,14 +15,16 @@ name to the ``setDefaultCommand()`` method::
     #[AsCommand(name: 'hello:world')]
     class HelloWorldCommand extends Command
     {
-        protected function configure()
+        protected function configure(): void
         {
             $this->setDescription('Outputs "Hello World"');
         }
 
-        protected function execute(InputInterface $input, OutputInterface $output)
+        protected function execute(InputInterface $input, OutputInterface $output): int
         {
             $output->writeln('Hello World');
+
+            return Command::SUCCESS;
         }
     }
 

components/browser_kit.rst

@@ -22,7 +22,7 @@ Have a look at the following command that has three options::
     #[AsCommand(name: 'demo:args', description: 'Describe args behaviors')]
     class DemoArgsCommand extends Command
     {
-        protected function configure()
+        protected function configure(): void
         {
             $this
                 ->setDefinition(
@@ -34,7 +34,7 @@ Have a look at the following command that has three options::
                 );
         }
 
-        protected function execute(InputInterface $input, OutputInterface $output)
+        protected function execute(InputInterface $input, OutputInterface $output): int
         {
             // ...
         }

components/config/definition.rst

@@ -97,6 +97,12 @@ The progress will then be displayed as a throbber:
      1/3 [=========>------------------]  33%
      3/3 [============================] 100%
 
+.. tip::
+
+    An alternative to this is to use a
+    :doc:`/components/console/helpers/progressindicator` instead of a
+    progress bar.
+
 Whenever your task is finished, don't forget to call
 :method:`Symfony\\Component\\Console\\Helper\\ProgressBar::finish` to ensure
 that the progress bar display is refreshed with a 100% completion.