From 0212af4d9eace00d3ba4d39480631af5521a47c1 Mon Sep 17 00:00:00 2001
From: Peter Bowyer <peter@mapledesign.co.uk>
Date: Sat, 23 Mar 2019 15:17:40 +0000
Subject: [PATCH 1/3] Document Transition Blockers. Explanation needs expanding
 - there is not enough detail.

---
 workflow/usage.rst | 67 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/workflow/usage.rst b/workflow/usage.rst
index 44451510ba1..286dc4ec5b1 100644
--- a/workflow/usage.rst
+++ b/workflow/usage.rst
@@ -475,3 +475,70 @@ The following example shows these functions in action:
     {% if 'waiting_some_approval' in workflow_marked_places(post) %}
         <span class="label">PENDING</span>
     {% endif %}
+
+Transition Blockers
+-------------------
+
+.. versionadded:: 4.1
+    Transition Blockers were introduced in Symfony 4.1.
+
+Transition Blockers provide a simple way to return a human-readable message for why a transition
+was blocked. You can access the message from Twig. Here's an example:
+
+
+.. code-block:: php
+
+    use Symfony\Component\Workflow\Event\GuardEvent;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+    class BlogPostPublishListener implements EventSubscriberInterface
+    {
+        public function guardPublish(GuardEvent $event)
+        {
+            /** @var \App\Entity\BlogPost $post */
+            $post = $event->getSubject();
+
+            // If it's after 9pm, prevent publication
+            if (date('H') > 21) {
+                $event->addTransitionBlocker(
+                    new TransitionBlocker(
+                        "You can not publish this blog post because it's too late. Try again tomorrow morning."
+                    )
+                );
+            }
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return array(
+                'workflow.blogpost.guard.to_publish' => array('guardPublish'),
+            );
+        }
+    }
+
+.. code-block:: html+twig
+
+    <h2>Publication was blocked because:</h2>
+    <ul>
+        {% for transition in workflow_all_transitions(article) %}
+            {% if not workflow_can(article, transition.name) %}
+                <li>
+                    <strong>{{ transition.name }}</strong>:
+                    <ul>
+                    {% for blocker in workflow_build_transition_blocker_list(article, transition.name) %}
+                        <li>
+                            {{ blocker.message }}
+                            {% if blocker.parameters.expression is defined %}
+                                <code>{{ blocker.parameters.expression }}</code>
+                            {% endif %}
+                        </li>
+                    {% endfor %}
+                    </ul>
+                </li>
+            {% endif %}
+        {% endfor %}
+    </ul>
+
+Don't need a human-readable message? You can still use::
+
+    $event->setBlocked('true');

From 64179f9c5a6b786211f061488d1375f6ee2043ec Mon Sep 17 00:00:00 2001
From: Peter Bowyer <peter@mapledesign.co.uk>
Date: Sat, 23 Mar 2019 15:45:32 +0000
Subject: [PATCH 2/3] Fix transition name

---
 workflow/usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/workflow/usage.rst b/workflow/usage.rst
index 286dc4ec5b1..e887275b711 100644
--- a/workflow/usage.rst
+++ b/workflow/usage.rst
@@ -511,7 +511,7 @@ was blocked. You can access the message from Twig. Here's an example:
         public static function getSubscribedEvents()
         {
             return array(
-                'workflow.blogpost.guard.to_publish' => array('guardPublish'),
+                'workflow.blogpost.guard.publish' => array('guardPublish'),
             );
         }
     }

From db5cb1540230d7e8e03fa428e5b58b0df0157d97 Mon Sep 17 00:00:00 2001
From: Peter Bowyer <peter@mapledesign.co.uk>
Date: Sat, 23 Mar 2019 15:46:24 +0000
Subject: [PATCH 3/3] Update arrays to use short syntax

---
 workflow/usage.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/workflow/usage.rst b/workflow/usage.rst
index e887275b711..7be2a9ddc44 100644
--- a/workflow/usage.rst
+++ b/workflow/usage.rst
@@ -510,9 +510,9 @@ was blocked. You can access the message from Twig. Here's an example:
 
         public static function getSubscribedEvents()
         {
-            return array(
-                'workflow.blogpost.guard.publish' => array('guardPublish'),
-            );
+            return [
+                'workflow.blogpost.guard.publish' => ['guardPublish'],
+            ];
         }
     }