First a more cosmetic issue: Please add a line break after the first word that crosses the 72th character. It seems like your lines are now longer than this.

Is there any more features I should cover?

I don't know the component, but the docs you've written now are lacking some important details:

• What are all these arguments passed tonew Transaction()?
• What is theMarkingScore and what areScalarMarkingScore? (and what other marking scores are available?)
• There seems to be aRegistry to be able to use multiple workflows for different classes, let's also document this.

Do you like my blog post project?

It looks fine to me. However, maybe@lyrixx has some other opinion, as it seems like your concept of the Workflow component (as state machine) differs from his view.

At last, if you have some time, please restructure the workflow component docs in a little different way:

1. Only document how to initialize theWorkflow andRegistry class (and all other standalone specific things) in the components docs.

2. Move theusage docs to a new/workflow directory in the root. This will document framework usage (so the configuration and by using theworkflow service). We decided that component users are smart enough to transform framework-usage into component-usage.

3. Create/workflow.rst in the root, containing:

   Workflow--------..toctree:::maxdepth:1:glob:workflow/*

Oh, and completely forgot to say a big thanks for starting this! Would be great to have this component documented before the release!

Thank you for the feedback. Really appreciate that. I will update this PR accordingly. Expect an update tonight or within the next coming days.

@Nyholm last comment (I will probably be crushed for that), but I think we can't escape the explanation about what is a state machine, and how this component differs from a state machine.

I was pretty sure the component creator have explained it somewhere :) else we will have a lot of (legitimate) questions about "why not a finite state machine ?" , "why workflow and not a state machine?" etc ...

I think you are correct. I do also want to research if one can consider a state machine as a special case of a workflow.
Anyhow we should definitely have a section where we explain both state machines and workflows and how/why you can/cant use the workflow component with a state machine.

It would be nice to describe the purpose of the component more.

By now, I fail to understand the component intent: OK, it can be useful for dumping graphs. But I'm pretty sure it should not be used to describe "primary" domain logic to handle these transitions in the domain model. Model should take care of its internal state by itself:

namespaceAcme\BlogPosting;finalclass BlogPost{publicfunctionpublish() {if ($this->status->equals(PostStatus::published())) {return;        }        Assertion::true($this->status->equals(PostStatus::waitingForReview()));$this->apply(newBlogPostWasPublished($this->id));    }privatefunctionwhenBlogPostWasPublished(BlogPostWasPublished$event) {$this->status = PostStatus::published();    }}

Not sure why somebody would replace explicit model invariants with generic Symfony's component.

It's OK to handle "secondary" domain logic though (reflection of a domain model), e.g. if you want to hide some senseless transitions from UI. But it has nothing to do with domain model.

And just to be clear,example from author of the component looks like a strong anti-pattern for me. Anaemic domain model with implicitmarking property coupled with a framework. What could possibly go wrong?

I don't want to look offensive, but I hope it wouldn't be proclaimed as something like "best practice for your business logic". Because it's not.

Anaemic domain model with implicit marking property coupled with a framework.

Nothing about this property couples it to the framework...

Nothing about this property couples it to the framework...

I'm sorry, but I'm not sure I understand you correctly. Coupling with a framework is not the main issue here, but anaemia & vagueness is.

You can name this property anything you want, so that removes the vagueness? (I got your first point, but the model still is as anaemic as you want afaics)

You can name this property anything you want, so that removes the vagueness?

No, it doesn't. Still, it is either array orMarking instance. It is something that you can't really explain from domain perspective. It hides domain concepts like "article status" and probably something else. It encourages to replace statuses and flags of the model with vague array.

Further, the component raises vague events likeSymfony\Component\Workflow\Event\Event andSymfony\Component\Workflow\Event\TransitionEvent. I wonder how it can be better than explicitBlogPostWasPublished,BlogPostWasReviewed, etc.

I got your first point, but the model still is as anaemic as you want afaics

The thing is the component breaks encapsulation of the model (at least, given examples do). The component wants to control transitions of theBlogPost by changing its properties directly.BlogPost should take care of itself.

@unkind you may be interested by this study about Petri net and workflow management =>https://wwwis.win.tue.nl/~wvdaalst/publications/p53.pdf

Let's focus on docs for now :)

@unkind you may be interested by this study about Petri net and workflow management =>https://wwwis.win.tue.nl/~wvdaalst/publications/p53.pdf

How does it conflict with my observations?

Let's focus on docs for now

I won't say anything unless docs would provide wrong examples based on procedural approaches instead of object-oriented ones.

Massive thank you for the feedback. I've updated the PR accordingly.

I've splited up the docs into multiple parts. One for the component, one for "usage" and one for dumping. What this what you had in mind@wouterj?

That is great@unkind that you challenging this. I appreciate that. Though, Im not the author of the component Im happy if we discuss what the documentation and the examples in the documentations should say and not say (just as you have done so far). There are clearly right and wrong ways of using any component.

I do agree with you that models should manage their own state. But when your models grows that could be a lot of messy code. Also, the workflows may have dependencies outside of the model. Say that you not should be allowed to publish when "[external event(boss is in the office?)]" is happening. Then it is a good thing to move this code outside of the model.

I will continue this PR by filling in the placeholders (twig and state machines)

There you go. The docs does reflect the code in master

Thank you Christian

👍

Great! Thank you for your patience, Tobias!