Merge branch '5.1' into 5.x

* 5.1:
  Clarify how workflow can be injected
  Update form_customization.rst
  add _failure_path option to reference
  Clarify authentication entry point and access denied handler

Author: wouterj

form/bootstrap4.rst

@@ -77,6 +77,8 @@ If you prefer to apply the Bootstrap styles on a form to form basis, include the
         {{ form(form) }}
     {% endblock %}
 
+.. _reference-forms-bootstrap-error-messages:
+
 Error Messages
 --------------
 

form/form_customization.rst

@@ -255,6 +255,11 @@ Renders any errors for the given field.
     {# render any "global" errors not associated to any form field #}
     {{ form_errors(form) }}
 
+.. caution::
+
+    In the Bootstrap 4 form theme, ``form_errors()`` is already included
+    in ``form_label()``, see ":ref:`reference-forms-bootstrap-error-messages`"
+
 .. _reference-forms-twig-widget:
 
 form_widget(form_view, variables)

reference/configuration/security.rst

@@ -504,6 +504,14 @@ target_path_parameter
 When using a login form, if you include an HTML element to set the target path,
 this option lets you change the name of the HTML element itself.
 
+failure_path_parameter
+......................
+
+**type**: ``string`` **default**: ``_failure_path``
+
+When using a login form, if you include an HTML element to set the failure path,
+this option lets you change the name of the HTML element itself.
+
 use_referer
 ...........
 

security/access_denied_handler.rst

@@ -1,17 +1,116 @@
 .. index::
     single: Security; Creating a Custom Access Denied Handler
 
-How to Create a Custom Access Denied Handler
-============================================
+How to Customize Access Denied Responses
+========================================
 
-When your application throws an ``AccessDeniedException``, you can handle this exception
-with a service to return a custom response.
+In Symfony, you can throw an
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
+to disallow access to the user. Symfony will handle this exception and
+generates a response based on the authentication state:
 
-First, create a class that implements
+* **If the user is not authenticated** (or authenticated anonymously), an
+  authentication entry point is used to generated a response (typically
+  a redirect to the login page or an *401 Unauthorized* response);
+* **If the user is authenticated, but does not have the required
+  permissions**, a *403 Forbidden* response is generated.
+
+Customize the Unauthorized Response
+-----------------------------------
+
+You need to create a class that implements
+:class:`Symfony\\Component\\Security\\Http\\EntryPoint\\AuthenticationEntryPointInterface`.
+This interface has one method (``start()``) that is called whenever an
+unauthenticated user tries to access a protected resource::
+
+    // src/Security/AuthenticationEntryPoint.php
+    namespace App\Security;
+
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Session\SessionInterface;
+    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
+
+    class AuthenticationEntryPoint implements AuthenticationEntryPointInterface
+    {
+        private $urlGenerator;
+        private $session;
+
+        public function __construct(UrlGeneratorInterface $urlGenerator, SessionInterface $session)
+        {
+            $this->urlGenerator = $urlGenerator;
+            $this->session = $session;
+        }
+
+        public function start(Request $request, AuthenticationException $authException = null): RedirectResponse
+        {
+            // add a custom flash message and redirect to the login page
+            $this->session->getFlashBag()->add('note', 'You have to login in order to access this page.');
+
+            return new RedirectResponse($this->urlGenerator->generate('security_login'));
+        }
+    }
+
+That's it if you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`.
+Otherwise, you have to register this service in the container.
+
+Now, configure this service ID as the entry point for the firewall:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        firewalls:
+            # ...
+
+            main:
+                # ...
+                entry_point: App\Security\AuthenticationEntryPoint
+
+    .. 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>
+                <firewall name="main"
+                    entry-point="App\Security\AuthenticationEntryPoint"
+                >
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Security\AuthenticationEntryPoint;
+
+        $container->loadFromExtension('security', [
+            'firewalls' => [
+                'main' => [
+                    // ...
+                    'entry_point' => AuthenticationEntryPoint::class,
+                ],
+            ],
+        ]);
+
+Customize the Forbidden Response
+--------------------------------
+
+Create a class that implements
 :class:`Symfony\\Component\\Security\\Http\\Authorization\\AccessDeniedHandlerInterface`.
-This interface defines one method called ``handle()`` where you can implement whatever
-logic that should run when access is denied for the current user (e.g. send a
-mail, log a message, or generally return a custom response)::
+This interface defines one method called ``handle()`` where you can
+implement whatever logic that should execute when access is denied for the
+current user (e.g. send a mail, log a message, or generally return a custom
+response)::
 
     // src/Security/AccessDeniedHandler.php
     namespace App\Security;
@@ -50,11 +149,21 @@ configure it under your firewall:
     .. code-block:: xml
 
         <!-- config/packages/security.xml -->
-        <config>
-            <firewall name="main">
-                <access-denied-handler>App\Security\AccessDeniedHandler</access-denied-handler>
-            </firewall>
-        </config>
+        <?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>
+                <firewall name="main"
+                    access-denied-handler="App\Security\AccessDeniedHandler"
+                >
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
 
     .. code-block:: php
 
@@ -70,5 +179,47 @@ configure it under your firewall:
             ],
         ]);
 
-That's it! Any ``AccessDeniedException`` thrown by code under the ``main`` firewall
-will now be handled by your service.
+Customizing All Access Denied Responses
+---------------------------------------
+
+In some cases, you might want to customize both responses or do a specific
+action (e.g. logging) for each ``AccessDeniedException``. In this case,
+configure a :ref:`kernel.exception listener <use-kernel-exception-event>`::
+
+    // src/EventListener/AccessDeniedListener.php
+    namespace App\EventListener;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
+    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+
+    class AccessDeniedListener implements EventSubscriberInterface
+    {
+        public static function getSubscribedEvents(): array
+        {
+            return [
+                // the priority must be greater than the Security HTTP
+                // ExceptionListener, to make sure it's called before
+                // the default exception listener
+                KernelEvents::EXCEPTION => ['onKernelException', 2],
+            ];
+        }
+
+        public function onKernelException(ExceptionEvent $event): void
+        {
+            $exception = $event->getException();
+            if (!$exception instanceof AccessDeniedException) {
+                return;
+            }
+
+            // ... perform some action (e.g. logging)
+
+            // optionally set the custom response
+            $event->setResponse(new Response(null, 403));
+
+            // or stop propagation (prevents the next exception listeners from being called)
+            //$event->stopPropagation();
+        }
+    }

workflow.rst

@@ -236,35 +236,62 @@ what actions are allowed on a blog post::
 Accessing the Workflow in a Class
 ---------------------------------
 
-To access workflow inside a class, use dependency injection and inject the
-registry in the constructor::
+You can use the workflow inside a class by using
+:doc:`service autowiring </service_container/autowiring>` and using
+``camelCased workflow name + Workflow`` as parameter name::
 
     use App\Entity\BlogPost;
-    use Symfony\Component\Workflow\Registry;
+    use Symfony\Component\Workflow\WorkflowInterface;
 
     class MyClass
     {
-        private $workflowRegistry;
+        private $blogPublishingWorkflow;
 
-        public function __construct(Registry $workflowRegistry)
+        // this injects the blog_publishing workflow configured before
+        public function __construct(WorkflowInterface $blogPublishingWorkflow)
         {
-            $this->workflowRegistry = $workflowRegistry;
+            $this->blogPublishingWorkflow = $blogPublishingWorkflow;
         }
 
         public function toReview(BlogPost $post)
         {
-            $workflow = $this->workflowRegistry->get($post);
-
             // Update the currentState on the post
             try {
-                $workflow->apply($post, 'to_review');
+                $this->blogPublishingWorkflow->apply($post, 'to_review');
             } catch (LogicException $exception) {
                 // ...
             }
             // ...
         }
     }
 
+Alternatively, use the registry::
+
+    use App\Entity\BlogPost;
+    use Symfony\Component\Workflow\Registry;
+
+    class MyClass
+    {
+        private $workflowRegistry;
+
+        public function __construct(Registry $workflowRegistry)
+        {
+            $this->workflowRegistry = $workflowRegistry;
+        }
+
+        public function toReview(BlogPost $post)
+        {
+            $blogPublishingWorkflow = $this->workflowRegistry->get($post);
+
+            // ...
+        }
+    }
+
+.. tip::
+
+    You can find the list of available workflow services with the
+    ``php bin/console debug:autowiring workflow`` command.
+
 Using Events
 ------------
 
@@ -928,25 +955,23 @@ Then you can access this metadata in your controller as follows::
 
     // src/App/Controller/BlogPostController.php
     use App\Entity\BlogPost;
-    use Symfony\Component\Workflow\Registry;
+    use Symfony\Component\Workflow\WorkflowInterface;
     // ...
 
-    public function myAction(Registry $registry, BlogPost $post)
+    public function myAction(WorkflowInterface $blogPublishingWorkflow, BlogPost $post)
     {
-        $workflow = $registry->get($post);
-
-        $title = $workflow
+        $title = $blogPublishingWorkflow
             ->getMetadataStore()
             ->getWorkflowMetadata()['title'] ?? 'Default title'
         ;
 
-        $maxNumOfWords = $workflow
+        $maxNumOfWords = $blogPublishingWorkflow
             ->getMetadataStore()
             ->getPlaceMetadata('draft')['max_num_of_words'] ?? 500
         ;
 
-        $aTransition = $workflow->getDefinition()->getTransitions()[0];
-        $priority = $workflow
+        $aTransition = $blogPublishingWorkflow->getDefinition()->getTransitions()[0];
+        $priority = $blogPublishingWorkflow
             ->getMetadataStore()
             ->getTransitionMetadata($aTransition)['priority'] ?? 0
         ;
@@ -969,7 +994,7 @@ In a :ref:`flash message <flash-messages>` in your controller::
 
     // $transition = ...; (an instance of Transition)
 
-    // $workflow is a Workflow instance retrieved from the Registry (see above)
+    // $workflow is a Workflow instance retrieved from the Registry or injected directly (see above)
     $title = $workflow->getMetadataStore()->getMetadata('title', $transition);
     $this->addFlash('info', "You have successfully applied the transition with title: '$title'");