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

* upstream/6.4: (29 commits)
  Update events.rst
  Tweaks
  Update messenger.rst
  Prefer placing services before query parameters
  Reword
  [Console] Fix a typo after symfony#18739
  Tweaks
  Tweaks
  [Console] Improve console events doc
  Add the versionadded directive
  Tweaks
  Minor tweaks
  Clearer difference with max and quiet options
  [Mailer] Fix attachment changes
  Minor tweak
  Minor tweak
  Missing information about payload in callback
  [Server] Fix typo in Symfony Local Web Server page
  [AssetMapper] Add docs for the importmap:install command
  [Validator] Deprecate annotations
  ...

Author: OskarStark

components/console/events.rst

@@ -17,7 +17,8 @@ the wheel, it uses the Symfony EventDispatcher component to do the work::
 .. caution::
 
     Console events are only triggered by the main command being executed.
-    Commands called by the main command will not trigger any event.
+    Commands called by the main command will not trigger any event, unless
+    run by the application itself, see :doc:`/console/calling_commands`.
 
 The ``ConsoleEvents::COMMAND`` Event
 ------------------------------------

components/console/helpers/formatterhelper.rst

@@ -13,7 +13,13 @@ in the default helper set and you can get it by calling
 
 The methods return a string, which you'll usually render to the console by
 passing it to the
-:method:`OutputInterface::writeln <Symfony\\Component\\Console\\Output\\OutputInterface::writeln>` method.
+:method:`OutputInterface::writeln <Symfony\\Component\\Console\\Output\\OutputInterface::writeln>`
+method.
+
+.. note::
+
+    As an alternative, consider using the
+    :ref:`SymfonyStyle <symfony-style-blocks>` to display stylized blocks.
 
 Print Messages in a Section
 ---------------------------

components/console/helpers/processhelper.rst

@@ -1,11 +1,12 @@
 Process Helper
 ==============
 
-The Process Helper shows processes as they're running and reports
-useful information about process status.
+The Process Helper shows processes as they're running and reports useful
+information about process status.
 
-To display process details, use the :class:`Symfony\\Component\\Console\\Helper\\ProcessHelper`
-and run your command with verbosity. For example, running the following code with
+To display process details, use the
+:class:`Symfony\\Component\\Console\\Helper\\ProcessHelper` and run your command
+with verbosity. For example, running the following code with
 a very verbose verbosity (e.g. ``-vv``)::
 
     use Symfony\Component\Process\Process;

components/console/helpers/progressbar.rst

@@ -6,6 +6,11 @@ information, which updates as your command runs:
 
 .. image:: /_images/components/console/progressbar.gif
 
+.. note::
+
+    As an alternative, consider using the
+    :ref:`SymfonyStyle <symfony-style-progressbar>` to display a progress bar.
+
 To display progress details, use the
 :class:`Symfony\\Component\\Console\\Helper\\ProgressBar`, pass it a total
 number of units, and advance the progress as the command executes::

components/console/helpers/questionhelper.rst

@@ -15,6 +15,11 @@ first argument, an :class:`Symfony\\Component\\Console\\Output\\OutputInterface`
 instance as the second argument and a
 :class:`Symfony\\Component\\Console\\Question\\Question` as last argument.
 
+.. note::
+
+    As an alternative, consider using the
+    :ref:`SymfonyStyle <symfony-style-questions>` to ask questions.
+
 Asking the User for Confirmation
 --------------------------------
 

components/console/helpers/table.rst

@@ -14,6 +14,11 @@ When building a console application it may be useful to display tabular data:
     | 80-902734-1-6 | And Then There Were None | Agatha Christie  |
     +---------------+--------------------------+------------------+
 
+.. note::
+
+    As an alternative, consider using the
+    :ref:`SymfonyStyle <symfony-style-content>` to display a table.
+
 To display a table, use :class:`Symfony\\Component\\Console\\Helper\\Table`,
 set the headers, set the rows and then render the table::
 
@@ -38,7 +43,7 @@ set the headers, set the rows and then render the table::
                 ])
             ;
             $table->render();
-            
+
             return Command::SUCCESS;
         }
     }
@@ -435,7 +440,7 @@ The only requirement to append rows is that the table must be rendered inside a
             $table->render();
 
             $table->appendRow(['Symfony']);
-            
+
             return Command::SUCCESS;
         }
     }

components/lock.rst

@@ -927,7 +927,7 @@ have synchronized clocks.
 PostgreSqlStore
 ~~~~~~~~~~~~~~~
 
-The PdoStore relies on the `Advisory Locks`_ properties of the PostgreSQL
+The PostgreSqlStore relies on the `Advisory Locks`_ properties of the PostgreSQL
 database. That means that by using :ref:`PostgreSqlStore <lock-store-pgsql>`
 the locks will be automatically released at the end of the session in case the
 client cannot unlock for any reason.

components/phpunit_bridge.rst

@@ -215,6 +215,8 @@ message, enclosed with ``/``. For example, with:
 `PHPUnit`_ will stop your test suite once a deprecation notice is triggered whose
 message contains the ``"foobar"`` string.
 
+.. _making-tests-fail:
+
 Making Tests Fail
 ~~~~~~~~~~~~~~~~~
 
@@ -349,6 +351,10 @@ It's also possible to change verbosity per deprecation type. For example, using
 ``quiet[]=indirect&quiet[]=other`` will hide details for deprecations of types
 "indirect" and "other".
 
+The ``quiet`` option hides details for the specified deprecation types, but will
+not change the outcome in terms of exit code. That's what :ref:`max <making-tests-fail>`
+is for, and both settings are orthogonal.
+
 Disabling the Deprecation Helper
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

components/validator/resources.rst

@@ -86,7 +86,14 @@ configure the locations of these files::
 The AnnotationLoader
 --------------------
 
-At last, the component provides an
+.. deprecated:: 6.4
+
+    The :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`
+    is deprecated since Symfony 6.4, use the
+    :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AttributeLoader`
+    instead.
+
+The component provides an
 :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader` to get
 the metadata from the annotations of the class. Annotations are defined as ``@``
 prefixed classes included in doc block comments (``/** ... */``). For example::
@@ -121,8 +128,44 @@ If you use annotations instead of attributes, it's also required to call
 To disable the annotation loader after it was enabled, call
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
 
+.. deprecated:: 6.4
+
+    The :method:`Symfony\\Component\\Validator\\ValidatorBuilder::enableAnnotationMapping`
+    and :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`
+    methods are deprecated since Symfony 6.4, use the
+    :method:`Symfony\\Component\\Validator\\ValidatorBuilder::enableAttributeMapping`
+    and :method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAttributeMapping`
+    methods instead.
+
 .. include:: /_includes/_annotation_loader_tip.rst.inc
 
+The AttributeLoader
+-------------------
+
+.. versionadded:: 6.4
+
+    The :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AttributeLoader`
+    was introduced in Symfony 6.4.
+
+The component provides an
+:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AttributeLoader` to get
+the metadata from the attributes of the class. For example::
+
+    use Symfony\Component\Validator\Constraints as Assert;
+    // ...
+
+    class User
+    {
+        #[Assert\NotBlank]
+        protected string $name;
+    }
+
+To enable the attribute loader, call the
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::enableAttributeMapping` method.
+
+To disable the annotation loader after it was enabled, call
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAttributeMapping`.
+
 Using Multiple Loaders
 ----------------------
 
@@ -136,8 +179,7 @@ multiple mappings::
     use Symfony\Component\Validator\Validation;
 
     $validator = Validation::createValidatorBuilder()
-        ->enableAnnotationMapping(true)
-        ->addDefaultDoctrineAnnotationReader()
+        ->enableAttributeMapping()
         ->addMethodMapping('loadValidatorMetadata')
         ->addXmlMapping('validator/validation.xml')
         ->getValidator();

console.rst

@@ -577,6 +577,12 @@ registers an :doc:`event subscriber </event_dispatcher>` to listen to the
 :ref:`ConsoleEvents::TERMINATE event <console-events-terminate>` and adds a log
 message whenever a command doesn't finish with the ``0`` `exit status`_.
 
+Using Events And Handling Signals
+---------------------------------
+
+When a command is running, many events are dispatched, one of them allows to
+react to signals, read more in :doc:`this section </components/console/events>`.
+
 Learn More
 ----------
 
@@ -596,6 +602,7 @@ tools capable of helping you with different tasks:
 * :doc:`/components/console/helpers/table`: displays tabular data as a table
 * :doc:`/components/console/helpers/debug_formatter`: provides functions to
   output debug information when running an external program
+* :doc:`/components/console/helpers/processhelper`: allows to run processes using ``DebugFormatterHelper``
 * :doc:`/components/console/helpers/cursor`: allows to manipulate the cursor in the terminal
 
 .. _`exit status`: https://en.wikipedia.org/wiki/Exit_status

console/calling_commands.rst

@@ -8,13 +8,13 @@ or if you want to create a "meta" command that runs a bunch of other commands
 changed on the production servers: clearing the cache, generating Doctrine
 proxies, dumping web assets, ...).
 
-Use the :method:`Symfony\\Component\\Console\\Application::find` method to
-find the command you want to run by passing the command name. Then, create a
-new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the
-arguments and options you want to pass to the command.
+Use the :method:`Symfony\\Component\\Console\\Application::doRun`. Then, create
+a new :class:`Symfony\\Component\\Console\\Input\\ArrayInput` with the
+arguments and options you want to pass to the command. The command name must be
+the first argument.
 
-Eventually, calling the ``run()`` method actually runs the command and returns
-the returned code from the command (return value from command's ``execute()``
+Eventually, calling the ``doRun()`` method actually runs the command and returns
+the returned code from the command (return value from command ``execute()``
 method)::
 
     // ...
@@ -29,15 +29,14 @@ method)::
 
         protected function execute(InputInterface $input, OutputInterface $output): int
         {
-            $command = $this->getApplication()->find('demo:greet');
-
-            $arguments = [
+            $greetInput = new ArrayInput([
+                // the command name is passed as first argument
+                'command' => 'demo:greet',
                 'name'    => 'Fabien',
                 '--yell'  => true,
-            ];
+            ]);
 
-            $greetInput = new ArrayInput($arguments);
-            $returnCode = $command->run($greetInput, $output);
+            $returnCode = $this->getApplication()->doRun($greetInput, $output);
 
             // ...
         }
@@ -47,7 +46,16 @@ method)::
 
     If you want to suppress the output of the executed command, pass a
     :class:`Symfony\\Component\\Console\\Output\\NullOutput` as the second
-    argument to ``$command->run()``.
+    argument to ``$application->doRun()``.
+
+.. note::
+
+    Using ``doRun()`` instead of ``run()`` prevents autoexiting and allows to
+    return the exit code instead.
+
+    Also, using ``$this->getApplication()->doRun()`` instead of
+    ``$this->getApplication()->find('demo:greet')->run()`` will allow proper
+    events to be dispatched for that inner command as well.
 
 .. caution::
 

console/style.rst

@@ -96,6 +96,8 @@ Titling Methods
 
         // ...
 
+.. _symfony-style-content:
+
 Content Methods
 ~~~~~~~~~~~~~~~
 
@@ -215,6 +217,8 @@ Admonition Methods
             'Aenean sit amet arcu vitae sem faucibus porta',
         ]);
 
+.. _symfony-style-progressbar:
+
 Progress Bar Methods
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -259,6 +263,8 @@ Progress Bar Methods
     Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\ProgressBar`
     styled according to the Symfony Style Guide.
 
+.. _symfony-style-questions:
+
 User Input Methods
 ~~~~~~~~~~~~~~~~~~
 
@@ -331,6 +337,8 @@ User Input Methods
 
     The ``multiSelect`` option of ``choice()`` was introduced in Symfony 6.2.
 
+.. _symfony-style-blocks:
+
 Result Methods
 ~~~~~~~~~~~~~~
 

doctrine.rst

@@ -539,7 +539,7 @@ and injected by the dependency injection container::
     class ProductController extends AbstractController
     {
         #[Route('/product/{id}', name: 'product_show')]
-        public function show(int $id, ProductRepository $productRepository): Response
+        public function show(ProductRepository $productRepository, int $id): Response
         {
             $product = $productRepository
                 ->find($id);

doctrine/events.rst

@@ -173,7 +173,7 @@ listener in the Symfony application by creating a new service for it and
 
     .. code-block:: php-attributes
 
-        // src/App/EventListener/SearchIndexer.php
+        // src/EventListener/SearchIndexer.php
         namespace App\EventListener;
 
         use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;

form/unit_testing.rst

@@ -216,7 +216,7 @@ allows you to return a list of extensions to register::
 
             // or if you also need to read constraints from annotations
             $validator = Validation::createValidatorBuilder()
-                ->enableAnnotationMapping(true)
+                ->enableAttributeMapping()
                 ->getValidator();
 
             return [

frontend/asset_mapper.rst

@@ -233,8 +233,14 @@ If you want to download the package locally, use the ``--download`` option:
     $ php bin/console importmap:require bootstrap --download
 
 This will download the package into an ``assets/vendor/`` directory and update
-the ``importmap.php`` file to point to it. You *should* commit this file to
-your repository.
+the ``importmap.php`` file to point to it. It's recommended to ignore this
+directory and not commit it to your repository. Therefore, you'll need to run the
+``php bin/console importmap:install`` command to download the files on other
+computers if some files are missing.
+
+.. versionadded:: 6.4
+
+    The ``importmap:install`` command was introduced in Symfony 6.4.
 
 .. note::