feature symfony#54344 [Workflow] Add EventNameTrait to compute event …

…name strings in subscribers (squrious)

This PR was squashed before being merged into the 7.1 branch.

Discussion
----------

[Workflow] Add EventNameTrait to compute event name strings in subscribers

| Q             | A
| ------------- | ---
| Branch?       | 7.1
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | N/A
| License       | MIT

Hello!

Using the event dispatcher, we usually use event's class name to configure the event to listen to. For workflow, we
still have to use raw strings:

```php
class WorkflowPostSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'workflow.post.entered.published' => 'onPublishedEntered',
        ];
    }
}
```

Using class names is more clear about what event we use (easier to know which event to use in the listener). Even if we already have attributes to define event listeners, the event subscriber way could be improved.

### Proposal

This PR adds a trait to improve DX when using workflow events in event subscribers.

```php
class WorkflowPostSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            PublishedEvent::get(workflowName: 'post', placeName: 'entered') => 'onPublishedEntered',
        ];
    }
}
```

For a better DX, the `EventNameTrait` provides two methods: `getNameForPlace` and `getNameForTransition`, so the second
argument of `::get` and its PHPDoc are consistent with the event type.

In event classes, it is used like:

```php
class EnterEvent extends Event
{
    use EventNameTrait {
        use getNameForPlace as public get;
    }

    // ...
}

```

Cheers!

Commits
-------

742221f [Workflow] Add EventNameTrait to compute event name strings in subscribers

src/Symfony/Component/Workflow/CHANGELOG.md

@@ -7,6 +7,7 @@ CHANGELOG
  * Add method `getEnabledTransition()` to `WorkflowInterface`
  * Automatically register places from transitions
  * Add support for workflows that need to store many tokens in the marking
+ * Add method `getName()` in event classes to build event names in subscribers 
 
 7.0
 ---

src/Symfony/Component/Workflow/Event/AnnounceEvent.php

@@ -17,6 +17,9 @@
 
 final class AnnounceEvent extends Event
 {
+    use EventNameTrait {
+        getNameForTransition as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Event/CompletedEvent.php

@@ -17,6 +17,9 @@
 
 final class CompletedEvent extends Event
 {
+    use EventNameTrait {
+        getNameForTransition as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Event/EnterEvent.php

@@ -17,6 +17,9 @@
 
 final class EnterEvent extends Event
 {
+    use EventNameTrait {
+        getNameForPlace as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Event/EnteredEvent.php

@@ -17,6 +17,9 @@
 
 final class EnteredEvent extends Event
 {
+    use EventNameTrait {
+        getNameForPlace as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Event/EventNameTrait.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Workflow\Event;
+
+use Symfony\Component\Workflow\Exception\InvalidArgumentException;
+
+/**
+ * @author Nicolas Rigaud <squrious@protonmail.com>
+ *
+ * @internal
+ */
+trait EventNameTrait
+{
+    /**
+     * Gets the event name for workflow and transition.
+     *
+     * @throws InvalidArgumentException If $transitionName is provided without $workflowName
+     */
+    private static function getNameForTransition(?string $workflowName, ?string $transitionName): string
+    {
+        return self::computeName($workflowName, $transitionName);
+    }
+
+    /**
+     * Gets the event name for workflow and place.
+     *
+     * @throws InvalidArgumentException If $placeName is provided without $workflowName
+     */
+    private static function getNameForPlace(?string $workflowName, ?string $placeName): string
+    {
+        return self::computeName($workflowName, $placeName);
+    }
+
+    private static function computeName(?string $workflowName, ?string $transitionOrPlaceName): string
+    {
+        $eventName = strtolower(basename(str_replace('\\', '/', static::class), 'Event'));
+
+        if (null === $workflowName) {
+            if (null !== $transitionOrPlaceName) {
+                throw new \InvalidArgumentException('Missing workflow name.');
+            }
+
+            return sprintf('workflow.%s', $eventName);
+        }
+
+        if (null === $transitionOrPlaceName) {
+            return sprintf('workflow.%s.%s', $workflowName, $eventName);
+        }
+
+        return sprintf('workflow.%s.%s.%s', $workflowName, $eventName, $transitionOrPlaceName);
+    }
+}

src/Symfony/Component/Workflow/Event/GuardEvent.php

@@ -23,6 +23,10 @@
  */
 final class GuardEvent extends Event
 {
+    use EventNameTrait {
+        getNameForTransition as public getName;
+    }
+
     private TransitionBlockerList $transitionBlockerList;
 
     public function __construct(object $subject, Marking $marking, Transition $transition, ?WorkflowInterface $workflow = null)

src/Symfony/Component/Workflow/Event/LeaveEvent.php

@@ -17,6 +17,9 @@
 
 final class LeaveEvent extends Event
 {
+    use EventNameTrait {
+        getNameForPlace as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Event/TransitionEvent.php

@@ -17,6 +17,9 @@
 
 final class TransitionEvent extends Event
 {
+    use EventNameTrait {
+        getNameForTransition as public getName;
+    }
     use HasContextTrait;
 
     public function __construct(object $subject, Marking $marking, ?Transition $transition = null, ?WorkflowInterface $workflow = null, array $context = [])

src/Symfony/Component/Workflow/Tests/Event/EventNameTraitTest.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Workflow\Tests\Event;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Workflow\Event\AnnounceEvent;
+use Symfony\Component\Workflow\Event\CompletedEvent;
+use Symfony\Component\Workflow\Event\EnteredEvent;
+use Symfony\Component\Workflow\Event\EnterEvent;
+use Symfony\Component\Workflow\Event\GuardEvent;
+use Symfony\Component\Workflow\Event\LeaveEvent;
+use Symfony\Component\Workflow\Event\TransitionEvent;
+
+class EventNameTraitTest extends TestCase
+{
+    /**
+     * @dataProvider getEvents
+     *
+     * @param class-string $class
+     */
+    public function testEventNames(string $class, ?string $workflowName, ?string $transitionOrPlaceName, string $expected)
+    {
+        $name = $class::getName($workflowName, $transitionOrPlaceName);
+        $this->assertEquals($expected, $name);
+    }
+
+    public static function getEvents(): iterable
+    {
+        yield [AnnounceEvent::class, null, null, 'workflow.announce'];
+        yield [AnnounceEvent::class, 'post', null, 'workflow.post.announce'];
+        yield [AnnounceEvent::class, 'post', 'publish', 'workflow.post.announce.publish'];
+
+        yield [CompletedEvent::class, null, null, 'workflow.completed'];
+        yield [CompletedEvent::class, 'post', null, 'workflow.post.completed'];
+        yield [CompletedEvent::class, 'post', 'publish', 'workflow.post.completed.publish'];
+
+        yield [EnteredEvent::class, null, null, 'workflow.entered'];
+        yield [EnteredEvent::class, 'post', null, 'workflow.post.entered'];
+        yield [EnteredEvent::class, 'post', 'published', 'workflow.post.entered.published'];
+
+        yield [EnterEvent::class, null, null, 'workflow.enter'];
+        yield [EnterEvent::class, 'post', null, 'workflow.post.enter'];
+        yield [EnterEvent::class, 'post', 'published', 'workflow.post.enter.published'];
+
+        yield [GuardEvent::class, null, null, 'workflow.guard'];
+        yield [GuardEvent::class, 'post', null, 'workflow.post.guard'];
+        yield [GuardEvent::class, 'post', 'publish', 'workflow.post.guard.publish'];
+
+        yield [LeaveEvent::class, null, null, 'workflow.leave'];
+        yield [LeaveEvent::class, 'post', null, 'workflow.post.leave'];
+        yield [LeaveEvent::class, 'post', 'published', 'workflow.post.leave.published'];
+
+        yield [TransitionEvent::class, null, null, 'workflow.transition'];
+        yield [TransitionEvent::class, 'post', null, 'workflow.post.transition'];
+        yield [TransitionEvent::class, 'post', 'publish', 'workflow.post.transition.publish'];
+    }
+
+    public function testInvalidArgumentExceptionIsThrownIfWorkflowNameIsMissing()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        EnterEvent::getName(null, 'place');
+    }
+}