Guarding an Order State Transition with Symfony's Workflow Component and a Guard Listener

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Order
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 20)]
    private string $currentState = 'cart';

    #[ORM\Column]
    private int $total = 0;

    #[ORM\Column(nullable: true)]
    private ?string $paymentReference = null;

    #[ORM\Column(nullable: true)]
    private ?string $shippingAddress = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getCurrentState(): string
    {
        return $this->currentState;
    }

    public function setCurrentState(string $state): self
    {
        $this->currentState = $state;

        return $this;
    }

    public function getTotal(): int
    {
        return $this->total;
    }

    public function getPaymentReference(): ?string
    {
        return $this->paymentReference;
    }

    public function getShippingAddress(): ?string
    {
        return $this->shippingAddress;
    }
}

<?php

namespace App\Workflow;

use App\Entity\Order;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Workflow\Event\GuardEvent;

class OrderTransitionGuard implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'workflow.order.guard.pay' => 'guardPay',
            'workflow.order.guard.ship' => 'guardShip',
        ];
    }

    public function guardPay(GuardEvent $event): void
    {
        /** @var Order $order */
        $order = $event->getSubject();

        if ($order->getTotal() <= 0) {
            $event->setBlocked(true, 'Order total must be greater than zero.');

            return;
        }

        if (null === $order->getPaymentReference()) {
            $event->setBlocked(true, 'A payment reference is required before paying.');
        }
    }

    public function guardShip(GuardEvent $event): void
    {
        /** @var Order $order */
        $order = $event->getSubject();

        if (null === $order->getShippingAddress()) {
            $event->setBlocked(true, 'Cannot ship an order without a shipping address.');
        }
    }
}

<?php

namespace App\Controller;

use App\Entity\Order;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\DependencyInjection\Attribute\Target;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Workflow\Exception\NotEnabledTransition;
use Symfony\Component\Workflow\WorkflowInterface;

class OrderController extends AbstractController
{
    #[Route('/orders/{id}/transition/{transition}', methods: ['POST'])]
    public function transition(
        Order $order,
        string $transition,
        #[Target('order')] WorkflowInterface $orderWorkflow,
        EntityManagerInterface $em,
    ): JsonResponse {
        if (!$orderWorkflow->can($order, $transition)) {
            $blockers = $orderWorkflow->buildTransitionBlockerList($order, $transition);
            $reasons = [];
            foreach ($blockers as $blocker) {
                $reasons[] = $blocker->getMessage();
            }

            return $this->json([
                'error' => 'Transition not allowed',
                'reasons' => $reasons ?: ['No path from current state.'],
            ], 422);
        }

        try {
            $orderWorkflow->apply($order, $transition);
        } catch (NotEnabledTransition $e) {
            return $this->json(['error' => 'State changed, retry.'], 409);
        }

        $em->flush();

        return $this->json(['state' => $order->getCurrentState()]);
    }
}