README

Use the Symfony Workflow component in Laravel.

Installation

composer require j0hnys/trident-workflow

Add the Workflow facade to your facades array:

<?php
    ...
    'Workflow' => J0hnys\TridentWorkflow\Facades\WorkflowFacade::class,

Configuration

Publish the config file

    php artisan vendor:publish --provider="J0hnys\TridentWorkflow\WorkflowServiceProvider"

Configure your workflow in config/workflow.php

<?php

return [
    'straight'   => [
        'type'          => 'workflow',
        'marking_store' => [
            'type'      => 'single_state',
            'arguments' => ['currentPlace']
        ],
        'supports'      => ['App\BlogPost'],
        'places'        => ['draft', 'review', 'rejected', 'published'],
        'transitions'   => [
            'to_review' => [
                'from' => 'draft',
                'to'   => 'review'
            ],
            'publish' => [
                'from' => 'review',
                'to'   => 'published'
            ],
            'reject' => [
                'from' => 'review',
                'to'   => 'rejected'
            ]
        ],
    ]
];

Use the WorkflowTrait inside supported classes

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use J0hnys\TridentWorkflow\Traits\WorkflowTrait;

class BlogPost extends Model
{
  use WorkflowTrait;

}

Usage

<?php

use App\BlogPost;
use J0hnys\TridentWorkflow\WorkflowRegistry;

$workflow_name = 'straight';
$configuration = config('workflow')[$workflow_name];

$workflow_configuration = app()->make('J0hnys\TridentWorkflow\PackageProviders\Configuration');
$workflow_configuration->setWorkflow($workflow_name, $configuration);
$workflow_registry = new WorkflowRegistry($workflow_name);

$post = BlogPost::find(1);
$workflow = $workflow_registry->get($post);

$workflow->can($post, 'publish'); // False
$workflow->can($post, 'to_review'); // True
$transitions = $workflow->getEnabledTransitions($post);

// Apply a transition
$workflow->apply($post, 'to_review');
$post->save(); // Don't forget to persist the state

Use the events

This package provides a list of events fired during a transition

    J0hnys\TridentWorkflow\Events\Guard
    J0hnys\TridentWorkflow\Events\Leave
    J0hnys\TridentWorkflow\Events\Transition
    J0hnys\TridentWorkflow\Events\Enter
    J0hnys\TridentWorkflow\Events\Entered

You can subscribe to an event

<?php

namespace App\Listeners;

use J0hnys\TridentWorkflow\Events\GuardEvent;

class BlogPostWorkflowSubscriber
{
    /**
     * Handle workflow guard events.
     */
    public function onGuard(GuardEvent $event) {
        /** Symfony\Component\Workflow\Event\GuardEvent */
        $originalEvent = $event->getOriginalEvent();

        /** @var App\BlogPost $post */
        $post = $originalEvent->getSubject();
        $title = $post->title;

        if (empty($title)) {
            // Posts with no title should not be allowed
            $originalEvent->setBlocked(true);
        }
    }

    /**
     * Handle workflow leave event.
     */
    public function onLeave($event) {}

    /**
     * Handle workflow transition event.
     */
    public function onTransition($event) {}

    /**
     * Handle workflow enter event.
     */
    public function onEnter($event) {}

    /**
     * Handle workflow entered event.
     */
    public function onEntered($event) {}

    /**
     * Register the listeners for the subscriber.
     *
     * @param  Illuminate\Events\Dispatcher  $events
     */
    public function subscribe($events)
    {
        $events->listen(
            'J0hnys\TridentWorkflow\Events\GuardEvent',
            'App\Listeners\BlogPostWorkflowSubscriber@onGuard'
        );

        $events->listen(
            'J0hnys\TridentWorkflow\Events\LeaveEvent',
            'App\Listeners\BlogPostWorkflowSubscriber@onLeave'
        );

        $events->listen(
            'J0hnys\TridentWorkflow\Events\TransitionEvent',
            'App\Listeners\BlogPostWorkflowSubscriber@onTransition'
        );

        $events->listen(
            'J0hnys\TridentWorkflow\Events\EnterEvent',
            'App\Listeners\BlogPostWorkflowSubscriber@onEnter'
        );

        $events->listen(
            'J0hnys\TridentWorkflow\Events\EnteredEvent',
            'App\Listeners\BlogPostWorkflowSubscriber@onEntered'
        );
    }

}

Dump Workflows

Symfony workflow uses GraphvizDumper to create the workflow image. You may need to install the dot command of Graphviz

php artisan workflow:dump workflow_name --class App\\BlogPost

You can change the image format with the --format option. By default the format is png.

php artisan workflow:dump workflow_name --format=jpg