Merge branch '5.2' into 5.x

wouterj · wouterj · commit cb7f0c512420 · 2020-11-23T10:07:22.000+01:00
* 5.2: Enhancement: Streamline workflow GitHub Actions: use docker container for CI build Bus restricting with Interfaces Security: add example code which Maker Bundle generated [#14550] Reduce nr of lines used for exception Section method only in ConsoleOutputInterface
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -1,3 +1,5 @@
+name: CI
+
 on:
     push:
         branches-ignore:
@@ -6,83 +8,73 @@ on:
         branches-ignore:
             - 'github-comments'
 
-name: CI
-
 jobs:
-    build:
-        name: Build
+    sphinx-build:
+        name: Build (Sphinx)
 
         runs-on: ubuntu-latest
 
+        container: python:3.7-alpine
+
         steps:
             -   name: "Checkout"
                 uses: actions/checkout@v2
 
-            -   name: "Set up Python 3.7"
-                uses: actions/setup-python@v1
-                with:
-                    python-version: '3.7' # Semantic version range syntax or exact version of a Python version
-
             -   name: "Display Python version"
                 run: python -c "import sys; print(sys.version)"
 
-            -   name: "Install Sphinx dependencies"
-                run: sudo apt-get install python-dev build-essential
+            -   name: "Install Sphinx"
+                run: pip install --user sphinx
 
-            -   name: "Cache pip"
-                uses: actions/cache@v2
-                with:
-                    path: ~/.cache/pip
-                    key: ${{ runner.os }}-pip-${{ hashFiles('_build/.requirements.txt') }}
-                    restore-keys: |
-                        ${{ runner.os }}-pip-
+            -   name: "Install dependencies"
+                run: apk add --no-cache git make
 
-            -   name: "Install Sphinx + requirements via pip"
+            -   name: "Install custom requirements via pip"
                 run: pip install -r _build/.requirements.txt
 
             -   name: "Build documentation"
                 run: make -C _build SPHINXOPTS="-nqW -j auto" html
 
-    build-php:
-        name: Symfony doc builder
+    symfony-docs-builder-build:
+        name: Build (symfony/docs-builder)
 
         runs-on: ubuntu-latest
 
         continue-on-error: true
 
         steps:
-            - name: "Checkout"
-              uses: actions/checkout@v2
-
-            - name: "Set-up PHP"
-              uses: shivammathur/setup-php@v2
-              with:
-                  php-version: 7.2
-                  coverage: none
-                  tools: "composer:v2"
-
-            - name: Get composer cache directory
-              id: composercache
-              working-directory: _build
-              run: echo "::set-output name=dir::$(composer config cache-files-dir)"
-
-            - name: Cache dependencies
-              uses: actions/cache@v2
-              with:
-                  path: ${{ steps.composercache.outputs.dir }}
-                  key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
-                  restore-keys: ${{ runner.os }}-composer-
-
-            - name: "Install dependencies"
-              working-directory: _build
-              run: composer install --prefer-dist --no-progress
-
-            - name: "Build the docs"
-              working-directory: _build
-              run: php build.php -vvv
+            -   name: "Checkout"
+                uses: actions/checkout@v2
+
+            -   name: "Set-up PHP"
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: 7.2
+                    coverage: none
+                    tools: "composer:v2"
+
+            -   name: Get composer cache directory
+                id: composercache
+                working-directory: _build
+                run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+            -   name: Cache dependencies
+                uses: actions/cache@v2
+                with:
+                    path: ${{ steps.composercache.outputs.dir }}
+                    key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+                    restore-keys: ${{ runner.os }}-composer-
+
+            -   name: "Install dependencies"
+                working-directory: _build
+                run: composer install --prefer-dist --no-progress
+
+            -   name: "Build the docs"
+                working-directory: _build
+                run: php build.php -vvv
 
     doctor-rst:
-        name: DOCtor-RST
+        name: Lint (DOCtor-RST)
 
         runs-on: ubuntu-latest
 
diff --git a/console.rst b/console.rst
@@ -187,16 +187,24 @@ called "output sections". Create one or more of these sections when you need to
 clear and overwrite the output information.
 
 Sections are created with the
-:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method,
-which returns an instance of
+:method:`ConsoleOutput::section() <Symfony\\Component\\Console\\Output\\ConsoleOutput::section>`
+method, which returns an instance of
 :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`::
 
+    // ...
+    use Symfony\Component\Console\Output\ConsoleOutputInterface;
+
     class MyCommand extends Command
     {
         protected function execute(InputInterface $input, OutputInterface $output)
         {
+            if (!$output instanceof ConsoleOutputInterface) {
+                throw new \LogicException('This command accepts only an instance of "ConsoleOutputInterface".');
+            }
+
             $section1 = $output->section();
             $section2 = $output->section();
+
             $section1->writeln('Hello');
             $section2->writeln('World!');
             // Output displays "Hello\nWorld!\n"
diff --git a/messenger/multiple_buses.rst b/messenger/multiple_buses.rst
@@ -150,30 +150,30 @@ you can restrict each handler to a specific bus using the ``messenger.message_ha
 This way, the ``App\MessageHandler\SomeCommandHandler`` handler will only be
 known by the ``command.bus`` bus.
 
-You can also automatically add this tag to a number of classes by following
-a naming convention and registering all of the handler services by name with
-the correct tag:
+You can also automatically add this tag to a number of classes by using
+the :ref:`_instanceof service configuration <di-instanceof>`. Using this,
+you can determine the message bus based on an implemented interface:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/services.yaml
+        services:
+            # ...
+
+            _instanceof:
+                # all services implementing the CommandHandlerInterface
+                # will be registered on the command.bus bus
+                App\MessageHandler\CommandHandlerInterface:
+                    tags:
+                        - { name: messenger.message_handler, bus: command.bus }
 
-        # put this after the "App\" line that registers all your services
-        command_handlers:
-            namespace: App\MessageHandler\
-            resource: '%kernel.project_dir%/src/MessageHandler/*CommandHandler.php'
-            autoconfigure: false
-            tags:
-                - { name: messenger.message_handler, bus: command.bus }
-
-        query_handlers:
-            namespace: App\MessageHandler\
-            resource: '%kernel.project_dir%/src/MessageHandler/*QueryHandler.php'
-            autoconfigure: false
-            tags:
-                - { name: messenger.message_handler, bus: query.bus }
+                # while those implementing QueryHandlerInterface will be
+                # registered on the query.bus bus
+                App\MessageHandler\QueryHandlerInterface:
+                    tags:
+                        - { name: messenger.message_handler, bus: query.bus }
 
     .. code-block:: xml
 
@@ -185,32 +185,45 @@ the correct tag:
                 https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <!-- command handlers -->
-                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*CommandHandler.php" autoconfigure="false">
+                <!-- ... -->
+
+                <!-- all services implementing the CommandHandlerInterface
+                     will be registered on the command.bus bus -->
+                <instanceof id="App\MessageHandler\CommandHandlerInterface">
                     <tag name="messenger.message_handler" bus="command.bus"/>
-                </prototype>
-                <!-- query handlers -->
-                <prototype namespace="App\MessageHandler\" resource="%kernel.project_dir%/src/MessageHandler/*QueryHandler.php" autoconfigure="false">
+                </instanceof>
+
+                <!-- while those implementing QueryHandlerInterface will be
+                     registered on the query.bus bus -->
+                <instanceof id="App\MessageHandler\QueryHandlerInterface">
                     <tag name="messenger.message_handler" bus="query.bus"/>
-                </prototype>
+                </instanceof>
             </services>
         </container>
 
     .. code-block:: php
 
         // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-        // Command handlers
-        $container->services()
-            ->load('App\MessageHandler\\', '%kernel.project_dir%/src/MessageHandler/*CommandHandler.php')
-            ->autoconfigure(false)
-            ->tag('messenger.message_handler', ['bus' => 'command.bus']);
+        use App\MessageHandler\CommandHandlerInterface;
+        use App\MessageHandler\QueryHandlerInterface;
 
-        // Query handlers
-        $container->services()
-            ->load('App\MessageHandler\\', '%kernel.project_dir%/src/MessageHandler/*QueryHandler.php')
-            ->autoconfigure(false)
-            ->tag('messenger.message_handler', ['bus' => 'query.bus']);
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            // ...
+
+            // all services implementing the CommandHandlerInterface
+            // will be registered on the command.bus bus
+            $services->instanceof(CommandHandlerInterface::class)
+                ->tag('messenger.message_handler', ['bus' => 'command.bus']);
+
+            // while those implementing QueryHandlerInterface will be
+            // registered on the query.bus bus
+            $services->instanceof(QueryHandlerInterface::class)
+                ->tag('messenger.message_handler', ['bus' => 'query.bus']);
+        };
 
 Debugging the Buses
 -------------------
diff --git a/security.rst b/security.rst
@@ -139,7 +139,59 @@ optional features, like :doc:`remember me </security/remember_me>` and
 :doc:`impersonation </security/impersonating_user>`.
 
 Fortunately, the ``make:user`` command already configured one for you in your
-``security.yaml`` file under the ``providers`` key.
+``security.yaml`` file under the ``providers`` key:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            providers:
+                # used to reload user from session & other features (e.g. switch_user)
+                app_user_provider:
+                    entity:
+                        class: App\Entity\User
+                        property: email
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- used to reload user from session & other features (e.g. switch-user) -->
+                <provider name="app_user_provider">
+                    <entity class="App\Entity\User" property="email"/>
+                </provider>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Entity\User;
+
+        $container->loadFromExtension('security', [
+            // ...
+
+            'providers' => [
+                // used to reload user from session & other features (e.g. switch_user)
+                'app_user_provider' => [
+                    'entity' => [
+                        'class' => User::class,
+                        'property' => 'email',
+                    ],
+                ],
+            ],
+        ]);
 
 If your ``User`` class is an entity, you don't need to do anything else. But if
 your class is *not* an entity, then ``make:user`` will also have generated a
diff --git a/service_container/tags.rst b/service_container/tags.rst
@@ -60,6 +60,8 @@ and many tags require additional arguments (beyond the ``name`` parameter).
 **For most users, this is all you need to know**. If you want to go further and
 learn how to create your own custom tags, keep reading.
 
+.. _di-instanceof:
+
 Autoconfiguring Tags
 --------------------
 
