README.md

Yokai Sonata Workflow

Introduction

This library add Symfony Workflow component integration within Sonata Admin.

Features

• add a menu dropdown to your admin detail pages on which you have buttons to apply available transitions
• ship a controller to apply transition
• allow to hook into the apply transition process to show an intermediate page

Code

• a Sonata Admin Extension : WorkflowExtension
• a Controller trait : WorkflowControllerTrait
• a Controller : WorkflowController

Installation

$ composer require yokai/sonata-workflow

Configuration

Let say that you have an entity named PullRequest that is under workflow and for which you have an admin.

# config/packages/workflow.yml
framework:
    workflows:
        pull_request:
            type: state_machine
            marking_store:
                type: state_machine
                property: status
            supports:
                - App\Entity\PullRequest
            places:
                - opened
                - pending_review
                - merged
                - closed
            initial_marking:
                - opened
            transitions:
                start_review:
                    from: opened
                    to:   pending_review
                merge:
                    from: pending_review
                    to:   merged
                close:
                    from: pending_review
                    to:   closed

One extension for everything

The extension is usable for many entities and with no configuration.

You only need to create a service for it, configure the controller that will handle the transition action and configure on which admin you want it available.

For instance :

# config/packages/sonata_admin.yml
services:
    admin.pull_request:
        class: App\Admin\PullRequestAdmin
        public: true
        arguments: [~, App\Entity\PullRequest, Yokai\SonataWorkflow\Controller\WorkflowController]
        tags:
            - { name: 'sonata.admin', manager_type: orm, label: PullRequest }
    admin.extension.workflow:
        class: Yokai\SonataWorkflow\Admin\Extension\WorkflowExtension
        public: true
        arguments:
            - '@workflow.registry'
    Yokai\SonataWorkflow\Controller\WorkflowController:
        autowire: true
        tags: ['controller.service_arguments']

sonata_admin:
    extensions:
        admin.extension.workflow:
            admins:
                - admin.pull_request

note: You may noticed that we also registered the controller Yokai\SonataWorkflow\Controller\WorkflowController as a service. It is important, because it needs the workflow registry service to work.

More specific extension per admin

But the extension accepts many options if you wish to customize the behavior.

For instance :

# config/packages/sonata_admin.yml
services:
    admin.pull_request:
        class: App\Admin\PullRequestAdmin
        public: true
        arguments: [~, App\Entity\PullRequest, 'Yokai\SonataWorkflow\Controller\WorkflowController']
        tags:
            - { name: 'sonata.admin', manager_type: orm, label: PullRequest }
    admin.extension.pull_request_workflow:
        class: Yokai\SonataWorkflow\Admin\Extension\WorkflowExtension
        public: true
        arguments:
            - '@workflow.registry'
            - render_actions: [show]
              workflow_name: pull_request
              no_transition_label: No transition for pull request
              no_transition_icon: fa fa-times
              dropdown_transitions_label: Pull request transitions
              dropdown_transitions_icon: fa fa-archive
              transitions_default_icon: fa fa-step-forward
              transitions_icons:
                  start_review: fa fa-search
                  merge: fa fa-check
                  close: fa fa-times
    Yokai\SonataWorkflow\Controller\WorkflowController:
        autowire: true
        tags: ['controller.service_arguments']

sonata_admin:
    extensions:
        admin.extension.pull_request_workflow:
            admins:
                - admin.pull_request

What are these options ?

• render_actions : Admin action names on which the extension should render its menu (defaults to [show, edit])
• workflow_name : The name of the Workflow to handle (defaults to null)
• no_transition_display : Whether or not to display a button when no transition is enabled (defaults to false)
• no_transition_label : The button label when no transition is enabled (defaults to workflow_transitions_empty)
• no_transition_icon : The button icon when no transition is enabled (defaults to fa fa-code-fork)
• dropdown_transitions_label : The dropdown button label when there is transitions enabled (defaults to workflow_transitions)
• dropdown_transitions_icon : The dropdown button icon when there is transitions enabled (defaults to fa fa-code-fork)
• transitions_default_icon : The default transition icon for all transition (defaults to null : no icon)
• transitions_icons : A hash with transition name as key and icon as value (defaults to [])

Hook into the transition process

Let say that when you start a review for a pull request, as a user, you will be asked to enter which users are involved in the review.

To achieve this, you will be asked to fill a dedicated form.

You only need to create a custom controller for your entity admin :

# config/packages/sonata_admin.yml
services:
    admin.pull_request:
        class: App\Admin\PullRequestAdmin
        public: true
        arguments: [~, App\Entity\PullRequest, App\Admin\Controller\PullRequestController]
        tags:
            - { name: 'sonata.admin', manager_type: orm, label: PullRequest }

<?php
// src/Admin/Controller/PullRequestController.php

declare(strict_types=1);

namespace App\Admin\Controller;

use App\Entity\PullRequest;
use App\Form\PullRequest\StartReviewType;
use Sonata\AdminBundle\Controller\CRUDController;
use Symfony\Component\HttpFoundation\Response;
use Yokai\SonataWorkflow\Controller\WorkflowControllerTrait;

class PullRequestController extends CRUDController
{
    use WorkflowControllerTrait;

    protected function preApplyTransition(object $object, string $transition): ?Response
    {
        switch ($transition) {
            case 'start_review':
                return $this->startReview($object, $transition);
        }

        return null;
    }

    protected function startReview(PullRequest $object, string $transition): ?Response
    {
        $form = $this->createForm(
            StartReviewType::class,
            [],
            [
                'action' => $this->admin->generateObjectUrl(
                    'workflow_apply_transition',
                    $object,
                    ['transition' => $transition]
                ),
            ]
        );

        $form->handleRequest($this->getRequest());

        if (!$form->isSubmitted() || !$form->isValid()) {
            $formView = $form->createView();

            return $this->renderWithExtraParams('admin/pull-request/start-review.html.twig', [
                'action' => 'edit',
                'form' => $formView,
                'object' => $object,
                'objectId' => $this->admin->getNormalizedIdentifier($object),
            ], null);
        }

        $data = $form->getData();
        // do something with the submitted data before returning null to continue applying transition

        return null;
    }
}

MIT License

License can be found here.

Authors

The library was originally created by Yann Eugoné. See the list of contributors.

---

Thank's to Prestaconcept for supporting this library.