Process Ui Bundle Laravel Package

Getting Started

Minimal Setup

1. Replace the Deprecated Bundle First, replace cleverage/process-ui-bundle with the active fork:

   composer require cleverage/ui-process-bundle
   

2. Import Routes Add the bundle’s routes to config/routes.yaml:

   process_ui:
       resource: '@CleverAgeUiProcessBundle/Resources/config/routes.yaml'
   

3. Run Migrations Execute the migrations to set up the required database tables:

   php bin/console doctrine:migrations:migrate
   

4. Create a Process UI User Generate an admin user via the CLI:

   php bin/console cleverage:ui-process:user-create
   

5. Access the UI Visit /process in your browser to see the Process UI dashboard.

First Use Case: Visualizing Workflows

• Navigate to Process > History to view active/inactive processes.
• Use the Process > Monitor tab to track real-time process execution.
• Click on a process ID to inspect its state, transitions, and metadata.

Implementation Patterns

Core Workflows

1. Integrating with EasyAdmin Extend the bundle’s CRUD functionality into your existing EasyAdmin dashboard:

   use CleverAge\UiProcessBundle\EasyAdmin\ProcessCrudController;
   
   class CustomProcessCrudController extends ProcessCrudController {
       public static function getEntityFqcn(): string {
           return YourProcessEntity::class;
       }
   }
   

   Register it in your EasyAdmin config:

   # config/packages/easy_admin.yaml
   easy_admin:
       crud:
           - CleverAge\UiProcessBundle\EasyAdmin\ProcessCrudController
   

2. Customizing Process Views Override Twig templates in templates/CleverAgeUiProcessBundle/ to modify:

   • Process history tables.
   • Transition buttons.
   • Status badges.

3. Async Log Indexing Configure Messenger for background log indexing (as shown in README) to avoid UI lag during searches.

Integration Tips

• Process Entities Ensure your ProcessEntity implements CleverAge\ProcessBundle\Model\ProcessInterface:

  use CleverAge\ProcessBundle\Model\ProcessInterface;
  
  class YourProcess implements ProcessInterface {
      // Required methods: getId(), getState(), etc.
  }
  

• Event Listeners Hook into process lifecycle events (e.g., ProcessStartedEvent) to update UI dynamically:

  use CleverAge\ProcessBundle\Event\ProcessStartedEvent;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class ProcessUiSubscriber implements EventSubscriberInterface {
      public static function getSubscribedEvents() {
          return [
              ProcessStartedEvent::class => 'onProcessStarted',
          ];
      }
  
      public function onProcessStarted(ProcessStartedEvent $event) {
          // Trigger UI refresh or log indexing
      }
  }
  

• Security Restrict access to /process via firewall rules or role-based ACLs:

  # config/packages/security.yaml
  access_control:
      - { path: ^/process, roles: ROLE_PROCESS_ADMIN }
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning The original cleverage/process-ui-bundle is archived. Always use cleverage/ui-process-bundle to avoid broken dependencies.

2. Messenger Configuration

   • Forgetting to run messenger:consume for log_index will block log searches.
   • Use a process manager (e.g., Supervisor) to keep the consumer alive:

     supervisorctl reread
     supervisorctl update
     supervisorctl start cleverage_log_indexer
     

3. EasyAdmin Version Conflicts The bundle targets EasyAdmin 3.x. If using EasyAdmin 4+, check for compatibility or patch the bundle’s ProcessCrudController.

4. Log Indexing Overhead Indexing large log files synchronously may time out. Use async messaging and monitor memory limits (--memory-limit=256M if needed).

Debugging

• Process Not Appearing in UI? Verify:

  • The entity implements ProcessInterface.
  • The process is persisted before the UI checks for it.
  • No Doctrine event listeners are filtering out the process.

• Blank UI Pages Clear cache and check for Twig errors:

  php bin/console cache:clear
  php bin/console debug:twig
  

• Permission Issues Ensure the user created via cleverage:ui-process:user-create has the correct roles (e.g., ROLE_PROCESS_ADMIN).

Extension Points

1. Custom Process States Extend the bundle’s state machine by overriding the process_state table or using Doctrine extensions:

   // src/Entity/ProcessStateExtension.php
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class ProcessStateExtension {
       #[ORM\Column(type: 'string', nullable: true)]
       private ?string $customMetadata = null;
   }
   

2. Dynamic UI Filters Add custom filters to the Process > History page by extending the ProcessCrudController:

   public function configureFields(string $pageName): iterable {
       yield FilterField::new('customField')
           ->setFormTypeOption('placeholder', 'Filter by custom field...');
   }
   

3. Webhook Triggers Use Symfony’s HttpClient to notify external systems when processes transition:

   use CleverAge\ProcessBundle\Event\ProcessTransitionEvent;
   
   public function onProcessTransition(ProcessTransitionEvent $event) {
       $client = new Client();
       $client->request('POST', 'https://external-api.com/webhook', [
           'json' => ['process_id' => $event->getProcess()->getId()]
       ]);
   }
   

4. Performance Tuning
   • Pagination: Add ->paginate(20) to queries in ProcessCrudController to limit loaded processes.
   • Lazy Loading: Use fetch: 'LAZY' for process relationships in Doctrine mappings to reduce N+1 queries.