[Workflow] Added Definition builder #20451

Nyholm · 2016-11-08T19:04:41Z

Q	A
Branch?	"master"
Bug fix?	no
New feature?	yes
BC breaks?	yes (in un-released branch)
Deprecations?	no
Tests pass?	yes
Fixed tickets	Related to #20441
License	MIT
Doc PR	n/a

Make the Definition immutable and add a DefinitionBuilder.

I basically broke up the Definition class into an immutable class and one builder.

fabpot · 2016-11-08T19:15:16Z

src/Symfony/Component/Workflow/Definition.php

     */
-    public function __construct(array $places = array(), array $transitions = array())
+    public function __construct(array $places = array(), array $transitions = array(), $initialPlace)


I suppose that the default values for $places and $transitions can be removed, right?

Yes, you are correct

Nyholm · 2016-11-08T19:35:10Z

src/Symfony/Component/Workflow/Definition.php

 */
-class Definition
+final class Definition


Are we okey with making this final?

Please next time don't ever do this without providing abstraction that final class implements.

Because then there is neither a way how to switch nor extend implementation.

https://ocramius.github.io/blog/when-to-declare-classes-final/

This is not an answer. Sometimes you don't need to "switch" or extend implementation.

If there is no such need, it means there is no need to make it final.

Edit: To not seem snarky: Marking the class as final is used to force user of the class to use composition over inheritance. If you don't provide abstraction (interface), he can't do that. If it's obvious there is never a need to switch/extend the implementation, keyword final doesn't change the thing. But if it turns out you are wrong and there is single case in world where it makes sense, poor sob who needs it can't do it and needs to wait for upstream to change this, which can take a while.

A: Hey, guys, this class is self-sufficient and we don't see sense in other implementations. Also, we want to encourage to use composition over inheritance. Let's mark it final.
B: Don't use final.
A: Why?
B: Because it makes impossible to extend this class nor replace implementation.
A: ... That's the point. You shouldn't do it.

Our dialog looks like above as long as you don't provide real use case when you need to inherit this class. It's perfectly fine to have the only implementation sometimes, especially for VOs.

Because then there is neither a way how to switch nor extend implementation.

It's like saying that poison shouldn't be marked with "don't eat it" label, because you want to eat it. Well, that's not the purpose of the object. Don't ~~eat~~ extend it.

If it's obvious there is never a need to switch/extend the implementation, keyword final doesn't change the thing

If someone needs to replace/extend implementation, it doesn't mean he is right and extending is correct. He should find better ways to solve his issue. You are as a vendor know how to use your tool and you are allowed to introduce some impediments to avoid incorrect usage of your product.

Nyholm · 2016-11-08T19:48:07Z

Im done with this implementation now.

lyrixx · 2016-11-09T09:23:05Z

LGTM

lyrixx · 2016-11-09T09:24:21Z

Actually, I have one question: I don't really like the idea to define the Definition as a service. What about adding Workflow::getDefinition() and to remove it from the DIC?

Nyholm · 2016-11-09T09:33:38Z

The definition is not a service... or not a public service. (https://github.com/symfony/symfony/pull/20451/files#diff-0e793081ceb720201745c982a568903fR426)

I agree with your arguments before saying that the definition is an value object.

What about adding Workflow::getDefinition() and to remove it from the DIC?

I agree. I did not add it here because I thought that would be a separate PR. But I add it now.

lyrixx · 2016-11-09T09:41:14Z

src/Symfony/Component/Workflow/DefinitionBuilder.php

+     */
+    public function build()
+    {
+        return new Definition($this->places, $this->transitions, $this->initialPlace);


What about reseting $this->places, $this->transitions, $this->initialPlace in order to be able to re-use the Builder to build another Definition?

Im not sure about that. One might want to have definition A and B where A is a subset of B.
If we automatically reset the builder one have to add places and transaction twice.

How do you feel about adding DefinitionBuilder::reset()?

ok for reset ;)

Awesome. I've updated the PR.

Should I change my doc PR to use the builder?

I would prefer if you put it in a new PR. The current doc PR is already pretty big and I would like to merge it as quick as possible.

stloyd · 2016-11-09T09:39:59Z

src/Symfony/Component/Workflow/DefinitionBuilder.php

+            throw new InvalidArgumentException(sprintf('The place "%s" contains invalid characters.', $place));
+        }
+
+        if (!count($this->places)) {


As this is always array this can be just:

if (!$this->places) {}

stloyd · 2016-11-09T09:40:31Z

src/Symfony/Component/Workflow/Tests/Dumper/GraphvizDumperTest.php

@@ -59,30 +59,30 @@ public function provideWorkflowDefinitionWithoutMarking()

    public function createprovideComplexWorkflowDefinition()


provideComplexWorkflowDefinition

Thank you. I've updated the PR to comply with your suggestions

stof · 2016-11-09T10:22:21Z

src/Symfony/Component/Workflow/Definition.php

@@ -29,18 +30,28 @@ class Definition
     *
     * @param string[]     $places
     * @param Transition[] $transitions
+     * @param string       $initialPlace


string|null

unkind · 2016-11-09T13:19:40Z

From design point of view, the idea of DI-service DefinitionBuilder is dangerous.

If you really want to have a builder, why not just instantiate new builder every time you want to build Definition:

$builder = new DefinitionBuilder();
$definition = $builder->...->build();

This logic is static in fact (that's why it perfectly can be moved to the Definition class itself).

I call this idea dangerous, because it makes mutable service.
Just imagine case, when you need to make very complex building like that:

$this->builder->reset();
$this->builder->addState('foo')->addState($this->stateProvider->getBar())->build();

What if stateProvider uses for some reason builder inside and resets it? It introduces a bug.
Moreover, user can simply forget to call reset somewhere (but he has to do it every time).

After all, what's the benefit of this complexity?

lyrixx · 2016-11-09T13:21:45Z

Hello @unkind

I'm not sure to understand your comment, and what you propose.

After all, what's the benefit of this complexity?

Which complexity are you talking about?

Nyholm · 2016-11-09T13:22:35Z

The builder is not a public service so you can not use it like in your examples.

unkind · 2016-11-09T13:26:50Z

The builder is not a public service so you can not use it like in your examples.

Ah, you mean it is inlined? My bad.

Which complexity are you talking about?

I'm talking about introducing new entity rather than moving this logic to the Definition class itself:

$definition = Definition::withInitialState(..., 'bar');
$definition = $definition->withNewState('foo');

stof · 2016-11-09T13:30:05Z

@unkind using methods returning a new mutated instance rather than mutating the existing one makes things harder for the DIC registration, as we still need to have a way to build the whole object without having to replace it by a different object in the meantime (unless we want to build a chain of private services being the factory for the next one, which becomes a nightmare)

unkind · 2016-11-09T13:38:08Z

as we still need to have a way to build the whole object without having to replace it by a different object in the meantime

You still can have a factory just for DIC:

public function createDefinition()
{
    $definition = ...;

    foreach ($this->transitions as ...) {
        $definition = ...;    
    }    

    return $definition;
}

lyrixx · 2016-11-09T13:58:09Z

@unkind I really prefer the build way here. And as @stof said, it's much easier with the DIC.

@Nyholm Sorry, but I just merge #20460 so you have to rebase and fix WorkflowDumpCommand.

Nyholm · 2016-11-09T14:04:04Z

I missed that PR. Good!

I've rebased my PR now.

lyrixx

one Little things to remove, another one to try to remove and then It will be good.

lyrixx · 2016-11-09T14:06:22Z

src/Symfony/Bundle/FrameworkBundle/Command/WorkflowDumpCommand.php

        foreach ($input->getArgument('marking') as $place) {
            $marking->mark($place);
        }

-        $output->writeln($dumper->dump($definition, $marking));
+        $output->writeln($dumper->dump($workflow->getDefinition(), $marking));
    }

    private function getProperty($object, $property)


You forgot to remove this method.

lyrixx · 2016-11-09T14:09:31Z

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

            $container->setDefinition($workflowId, $workflowDefinition);
+            $container->setDefinition(sprintf('%s.definition', $workflowId), $definitionDefinition);


There is no need to store it with an id, right? (ie, juste remove just line, everything should be OK)

We need this line or else we can grab it from the container in the compiler pass.

Indeed. I Though the service was in-lined later ;)

lyrixx · 2016-11-09T14:18:33Z

👍

fabpot · 2016-11-09T15:19:21Z

👍

lyrixx · 2016-11-09T15:20:54Z

Thanks Tobias for working on this feature, this is much appreciated.

Nyholm · 2016-11-09T15:22:14Z

Every time I submit a PR to Symfony I get great response no matter if my PR is good or not.

Thank you!

HeahDude · 2016-11-09T15:33:34Z

src/Symfony/Bundle/FrameworkBundle/Command/WorkflowDumpCommand.php

-        $reflectionProperty->setAccessible(true);
-
-        return $reflectionProperty->getValue($object);
+        $output->writeln($dumper->dump($workflow->getDefinition(), $marking));


xabbuh · 2016-11-10T14:03:02Z

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

-            $definitionDefinition = new Definition(Workflow\Definition::class);
-            $definitionDefinition->addMethodCall('addPlaces', array($workflow['places']));
+            // Create a DefinitionBuilder
+            $definitionBuilderDefinition = new Definition(Workflow\DefinitionBuilder::class);


Why do we make use of the DefinitionBuilder in the container extension? While I agree that the builder is useful in userland code, I do not see the added value here. On the downside, it just adds another level of indirection that is not really needed, is it?

There is no real reason. I can try to remove it.

@xabbuh

This PR was squashed before being merged into the 3.2-dev branch (closes #20478). Discussion ---------- [Workflow] Removed definition builder | Q | A | ------------- | --- | Branch? | "master" | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | n/a | License | MIT | Doc PR | n/a As of @xabbuh comment in #20451 (comment) We do not really need the definition builder here. Commits ------- caa3d6f [Workflow] Removed definition builder

carsonbot added Status: Needs Review Workflow Feature BC Break labels Nov 8, 2016

Nyholm mentioned this pull request Nov 8, 2016

[Workflow] Added DefinitionInterface #20441

Closed

fabpot reviewed Nov 8, 2016

View reviewed changes

Nyholm commented Nov 8, 2016

View reviewed changes

lyrixx reviewed Nov 9, 2016

View reviewed changes

stloyd suggested changes Nov 9, 2016

View reviewed changes

stof reviewed Nov 9, 2016

View reviewed changes

Nyholm mentioned this pull request Nov 9, 2016

Added docs for Workflow component symfony/symfony-docs#6871

Closed

Nyholm added 8 commits November 9, 2016 15:02

Added Definition builder

4d58b59

code style

ad2257f

Removed default values for places and transitions

cfcf8d3

Fixed tests

b6e028a

Code style

e708be3

Do not use abstract service definition

591e40b

Added test for addPlace

777add5

Make initial place mandatory

dc39f10

Nyholm added 5 commits November 9, 2016 15:02

refactor

02addd6

Added Workflow::getDefinition

8319f8e

Minor improvements

aeba77d

dockblock fix

a5dce04

added reset function

096a85f

Nyholm force-pushed the definition-builder branch from b0f1152 to 096a85f Compare November 9, 2016 14:03

lyrixx requested changes Nov 9, 2016

View reviewed changes

Removed method

7a66875

lyrixx approved these changes Nov 9, 2016

View reviewed changes

lyrixx added Status: Reviewed and removed Status: Needs Review BC Break labels Nov 9, 2016

javiereguiluz added this to the 3.2 milestone Nov 9, 2016

lyrixx closed this in 61b1334 Nov 9, 2016

Nyholm deleted the definition-builder branch November 9, 2016 15:21

HeahDude reviewed Nov 9, 2016

View reviewed changes

xabbuh reviewed Nov 10, 2016

View reviewed changes

Nyholm mentioned this pull request Nov 10, 2016

[Workflow] Removed definition builder #20478

Closed

HeahDude mentioned this pull request Nov 12, 2016

[Workflow] added a TransitionsCollectionBuilder so DefinitionBuilder doesn't need Transition objects #20498

Closed

fabpot mentioned this pull request Nov 17, 2016

Release v3.2.0-RC1 #20552

Merged

		@@ -59,30 +59,30 @@ public function provideWorkflowDefinitionWithoutMarking()

		public function createprovideComplexWorkflowDefinition()

		$container->setDefinition($workflowId, $workflowDefinition);
		$container->setDefinition(sprintf('%s.definition', $workflowId), $definitionDefinition);

[Workflow] Added Definition builder #20451

[Workflow] Added Definition builder #20451

Conversation

Nyholm commented Nov 8, 2016 • edited by lyrixx Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ostrolucky Jun 29, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

unkind Jun 29, 2017 • edited Loading

Choose a reason for hiding this comment

Nyholm commented Nov 8, 2016

lyrixx commented Nov 9, 2016 • edited Loading

lyrixx commented Nov 9, 2016

Nyholm commented Nov 9, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

unkind commented Nov 9, 2016 • edited Loading

lyrixx commented Nov 9, 2016

Nyholm commented Nov 9, 2016

unkind commented Nov 9, 2016 • edited Loading

stof commented Nov 9, 2016

unkind commented Nov 9, 2016 • edited Loading

lyrixx commented Nov 9, 2016

Nyholm commented Nov 9, 2016

lyrixx left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lyrixx commented Nov 9, 2016

fabpot commented Nov 9, 2016

lyrixx commented Nov 9, 2016

Nyholm commented Nov 9, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Nyholm commented Nov 8, 2016 •

edited by lyrixx

Loading

ostrolucky Jun 29, 2017 •

edited

Loading

unkind Jun 29, 2017 •

edited

Loading

lyrixx commented Nov 9, 2016 •

edited

Loading

unkind commented Nov 9, 2016 •

edited

Loading

unkind commented Nov 9, 2016 •

edited

Loading

unkind commented Nov 9, 2016 •

edited

Loading