[Workflow] Allow to define workflow with PHP attributes #61935

lyrixx · Oct 2, 2025

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?
Issues	Fix #58503
License	MIT

Hello folks!

I'm happy to share with you a new way to configure workflow. Please read the issue first.

Here is the new API:

<?php

namespace App\Workflow;

use App\Entity\Model\TaskStep;
use Symfony\Component\Workflow\Attribute\AsWorkflow;
use Symfony\Component\Workflow\Attribute\Transition;

#[AsWorkflow(
    name: 'task',
    supports: [\App\Entity\Task::class],
    // places: TaskStep::class, // Not needed, but works!
)]
class TaskWorkflow extends \Symfony\Component\Workflow\Workflow
{
    #[Transition(
        from: TaskStep::New,
        to: TaskStep::Processing,
    )]
    public const string START_PROCESS = 'start_process';

    #[Transition(
        from: TaskStep::Backlogged,
        to: TaskStep::Processing,
    )]
    public const string RETRY = 'retry';

    #[Transition(
        from: TaskStep::Processing,
        to: TaskStep::Backlogged,
    )]
    public const string TEMP_ERROR = 'temp_error';

    #[Transition(
        from: TaskStep::Processing,
        to: TaskStep::Failed,
    )]
    public const string PERMANENT_ERROR = 'permanent_error';

    #[Transition(
        from: TaskStep::Processing,
        to: TaskStep::Completed,
    )]
    public const string COMPLETE_WITHOUT_ERROR = 'complete_without_error';
}

As you can see, there is a new AsWorkflow Attribute. Thanks to it, you can configure everything about
the workflow (name, metatada, support, auditTrail, etc). As usual, places can be infered from the transitions (from and to)

Then, in the class, you can add constant to declare transitions.
It's possible to override the transition name in the attribute. (This could solve issue with many transition with the same name).

The PR is not finished yet. But I want to gather feedback first

GromNaN · Oct 2, 2025

src/Symfony/Component/Workflow/Tests/Configuration/AttributeReaderTest.php

+class TestArticleWorkflow
+{
+    #[Transition(
+        name: 'request_review',


The name is the same as the constant value, is it necessary?

src/Symfony/Component/Workflow/Tests/Configuration/AttributeReaderTest.php

stof · Oct 2, 2025

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

            );
        }

+        $attributeReader = new AttributeReader();


this is broken if the workflow component is not installed.

stof · Oct 2, 2025

src/Symfony/Component/Workflow/DependencyInjection/WorkflowServiceCreatorPass.php

+{
+    public function process(ContainerBuilder $container): void
+    {
+        if (!$container->hasParameter('.workflow.config')) {


this early return is broken. This compiler pass has 2 sources of definitions. The .workflow.config parameter and services tagged as .workflow.attribute. What if you don't have the parameter while still having tagged services ?

stof · Oct 2, 2025

src/Symfony/Component/Workflow/DependencyInjection/WorkflowServiceCreatorPass.php

+
+        $registryDefinition = $container->getDefinition('workflow.registry');
+
+        $config = $container->getParameter('.workflow.config');


Having a compiler pass defined in the component that processes a parameter storing the semantic configuration of FrameworkBundle leads to new BC guarantees we need to provide, as it means that this config is not purely internal anymore. It crosses a package boundary.
I would prefer keeping the FrameworkBundle config structure purely internal (we provide BC for the input of our Configuration classes, not for its output, as this would forbid us to make many changes we do when deprecating things)

stof · Oct 2, 2025

src/Symfony/Component/Workflow/DependencyInjection/WorkflowServiceCreatorPass.php

+            if (!$workflow = $attributes[0]['configuration'] ?? null) {
+                throw new LogicException(\sprintf('The service "%s" must define the "configuration" attribute on its "%s" tag.', $id, '.workflow.attribute'));
+            }
+            $serviceId = $this->createWorkflow($container, $registryDefinition, $workflow['name'], $workflow);


why is the name part of the configuration attribute while used separately, instead of being a separate tag attribute ?

stof · Oct 2, 2025

src/Symfony/Component/Workflow/DependencyInjection/WorkflowServiceCreatorPass.php

+            $serviceId = $this->createWorkflow($container, $registryDefinition, $workflow['name'], $workflow);
+            $container
+                ->getDefinition($serviceId)
+                ->clearTag('.workflow.attribute')


why clearing this tag ? That definition created just above will not have this tag.

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Attribute/AsWorkflow.php

+{
+    public function __construct(
+        public string $name,
+        public string|array $places = [],


any array should have phpdoc describing the expected type of this array (otherwise, we risk having to cover array<int|string, mixed> with BC as it won't be clear what works accidentally even if it was not intentional)

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Configuration/AttributeReader.php

+/**
+ * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ */
+class AttributeReader


should this class be @internal ?

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Configuration/AttributeReader.php

+            'supports' => $attribute->supports,
+            'places' => $attribute->places,
+            'transitions' => $this->extractTransitions($reflection),
+            'metadata' => [],


shouldn't we support defining metadata in the attribute ?

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Configuration/AttributeReader.php

+                continue;
+            }
+
+            $transition = $transitionAttributes[0]->newInstance();


this should read all transition attributes, not only the first one. Otherwise, this won't allow defining multiple transitions with the same name but distinct froms in a Workflow (which is valid in the component, even though I'm not sure it is fully supported in all the dumpers)

stof · Oct 2, 2025

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

+        $attributeReader = new AttributeReader();
+        $container->registerAttributeForAutoconfiguration(AsWorkflow::class, static function (ChildDefinition $definition, AsWorkflow $attribute, \ReflectionClass $reflection) use ($attributeReader): void {
+            $configuration = $attributeReader->extractConfiguration($attribute, $reflection);
+            $definition->addTag('.workflow.attribute', [


A way to solve my objection in https://github.com/symfony/symfony/pull/61935/files#r2399400826 would be to define the attribute as AsWorkflowDefinition instead, and register .workflow.attribute as a resource tag instead, similar to how #61563 was implemented.

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Attribute/Transition.php

+/**
+ * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ */
+#[\Attribute(\Attribute::TARGET_CLASS_CONSTANT)]


should be repeatable, to allow defining multiple transitions with the same name bit different from places

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Attribute/Transition.php

+        public ?string $name = null,
+        public array $metadata = [],
+        public ?string $guard = null,
+        public string|array|\BackedEnum $from = [],


why do we support both froms and from ? This seems bad, especially when the plural argument is silently ignored when both are provided.

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Attribute/Transition.php

+    public function __construct(
+        public string|array $froms = [],
+        public string|array $tos = [],
+        public ?string $name = null,


Do we even need a name at all ? What is the use case for defining a transition name that is not equal to the constant value (making it impossible to use the constant to reference the transition) ?

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Configuration/AttributeReader.php

+            }
+
+            $transition = $transitionAttributes[0]->newInstance();
+            $transitionName = $transition->name ?? $constant->getValue();


This must validate that the constant value is a string, providing proper error when using it in a wrong way instead of a weird failure (or an implicit cast leading to unclear transition name) later on.

stof · Oct 2, 2025

src/Symfony/Component/Workflow/Configuration/AttributeReader.php

+            $transition = $transitionAttributes[0]->newInstance();
+            $transitionName = $transition->name ?? $constant->getValue();
+
+            $transitions[$transitionName] = [


indexing the array by transition name forbids configuring multiple transitions with the same name but different from places, which is a valid configuration in the WorkflowDefinition (definition validators only enforce unique names among outgoing transitions of each place, not among all transitions)

Menelion · Oct 6, 2025

Hallelujah! Hope it will get merged soon, thanks @lyrixx for this work! I love the concept of workflows but hate the necessity to write that Yaml config.

[Workflow] Allow to define workflow with PHP attributes

e70dc8d

carsonbot added Status: Needs Review Feature Workflow labels Oct 2, 2025

carsonbot added this to the 7.4 milestone Oct 2, 2025

GromNaN reviewed Oct 2, 2025

View reviewed changes

stof reviewed Oct 2, 2025

View reviewed changes


		$registryDefinition = $container->getDefinition('workflow.registry');

		$config = $container->getParameter('.workflow.config');

Search code, repositories, users, issues, pull requests...

Uh oh!

[Workflow] Allow to define workflow with PHP attributes #61935

Are you sure you want to change the base?

[Workflow] Allow to define workflow with PHP attributes #61935

Conversation

lyrixx commented Oct 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Menelion commented Oct 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants