Laravel Workflow

In a multi-state workflow, you can define transitions based on whether a subject must be in exactly multiple places or either of multiple places.

• Exactly multiple places: To require a subject to be in multiple places simultaneously (e.g., both content_approved AND legal_approved), nest the array of places inside another array in the from key: ['from' => [['place1', 'place2']]].
• Either of multiple places: To allow a transition from any one of several places (e.g., content_approved OR legal_approved), provide a flat array in the from key: ['from' => ['place1', 'place2']].

<?php

// Example 1: Exactly two places transition to one (Nested array)
'transitions' => [
    'publish' => [
        'from' => [ 
            ['content_review', 'legal_review']
        ],
        'to' => 'published'
    ],
],

// Example 2: Either of two places transition to one (Flat array)
'transitions' => [
    'publish' => [
        'from' => [
            'content_review',
            'legal_review'
        ],
        'to' => 'published'
    ],
]

After installing, publish the configuration file using Artisan:

php artisan vendor:publish --provider="ZeroDaHero
LaravelWorkflow//WorkflowServiceProvider"

Workflows are defined in config/workflow.php. Each top-level key in the array represents a unique workflow name.

Key Configuration Options:

• type: Either 'workflow' (multiple states allowed) or 'state_machine' (single state). Defaults to 'workflow'.
• marking_store: Defines how the state is stored on the model.
  • property: The attribute name on the model (defaults to 'marking').
  • class: The marking store class (defaults to EloquentMethodMarkingStore for Eloquent models).
• supports: An array of class names (e.g., ['App\BlogPost']) that this workflow applies to.
• places: An array of available states/places.
• initial_places: The starting state(s). Defaults to the first element in places if omitted.
• transitions: An array defining how to move between places. Each transition requires a from and to key.
• events_to_dispatch: (Only for workflow type) An array of Symfony\Component\Workflow\WorkflowEvents constants to trigger. Setting to null dispatches all; [] dispatches none.
• metadata: Optional metadata that can be attached at the workflow, place, or transition level.

return [
    'straight' => [
        'type' => 'workflow',
        'marking_store' => [
            'property' => 'marking',
            'class' => MethodMarkingStore::class,
        ],
        'supports' => ['App\BlogPost'],
        'places' => ['draft', 'review', 'rejected', 'published'],
        'initial_places' => ['draft'],
        'transitions' => [
            'to_review' => [
                'from' => 'draft',
                'to' => 'review',
            ],
            'publish' => [
                'from' => 'review',
                'to' => 'published'
            ],
        ],
    ]
];

The package provides several events fired during transitions. It is highly recommended to use Symfony's dot syntax style for event emission. This provides precision and prevents receiving the same event class multiple times for the 'same' event, which can happen if you only listen by class name in Laravel.

<?php

namespace App\Listeners;

use ZeroDaHero\LaravelWorkflow\Events\GuardEvent;

class BlogPostWorkflowSubscriber
{
    public function subscribe($events)
    {
        // Format: workflow.[workflow name].[event type].[optional transition/place name]
        
        // workflow.guard
        $events->listen('workflow.straight.guard', 'App\Listeners\BlogPostWorkflowSubscriber@onGuard');

        // workflow.leave
        $events->listen('workflow.straight.leave', 'App\Listeners\BlogPostWorkflowSubscriber@onLeave');

        // workflow.transition
        $events->listen('workflow.straight.transition', 'App\Listeners\BlogPostWorkflowSubscriber@onTransition');

        // workflow.enter
        $events->listen('workflow.straight.enter', 'App\Listeners\BlogPostWorkflowSubscriber@onEnter');

        // workflow.entered
        $events->listen('workflow.straight.entered', 'App\Listeners\BlogPostWorkflowSubscriber@onEntered');

        // workflow.completed
        $events->listen('workflow.straight.completed', 'App\Listeners\BlogPostWorkflowSubscriber@onCompleted');

        // workflow.announce
        $events->listen('workflow.straight.announce', 'App\Listeners\BlogPostWorkflowSubscriber@onAnnounce');
    }
}

If you want to perform custom logic (like logging, triggering side effects, or complex casting) whenever a workflow marking is updated, you can define a mutator on your Eloquent model.

The EloquentMarkingStore will automatically detect and use a method named set{PropertyName}Attribute.

For a property named marking, the method signature should be: public function setMarkingAttribute($marking, array $context = [])

class Order extends //Illuminate\Database\Eloquent\Model
{
    // The property where marking is stored
    protected $marking = [];

    /**
     * Custom mutator called by EloquentMarkingStore
     */
    public function setMarkingAttribute($marking, array $context = [])
    {
        // $marking is the array of places
        // $context contains additional workflow context
        $this->attributes['marking'] = json_encode($marking);
        
        // Perform custom logic here
        logger("Workflow moved to: " . implode(', ', $marking));
    }
}