Ui Process Bundle Laravel Package

Getting Started

1. Prerequisites: Re-check requirements before upgrading:
   • PHP 8.1+.
   • Symfony 7.3+ (aligns with Laravel 10.x+ compatibility).
   • New in v3.2: cleverage/process-bundle ^5.3 is now required (needed for the stop-checker integration).
   • Install/upgrade:

     composer require cleverage/ui-process-bundle:^3.2
     

2. Run the new migrations first (v3.2 ships two):
   • Version20261013120000 — adds process_schedule.enabled (existing schedules are enabled by default).
   • Version20261014120000 — adds nullable process_execution.stop_requested_at and process_execution.heartbeat_at.

   php artisan migrate
   

3. First Use Case (new): Disable a schedule from the schedules list, or stop a running execution from the executions UI ("Stop the process", POST with confirmation). Both are the fastest way to see the new behaviour:

   php artisan cleverage:ui-process:run example   # start something
   # then hit "Stop the process" on the started execution in the UI
   

4. Key Files:
   • config/cleverage_ui_process.php — now also holds process_execution.heartbeat_interval, process_execution.stale_after, and logs.database_max_days / logs.file_max_days.
   • vendor/cleverage/ui-process-bundle/ — source for extension points (ProcessExecutionStopChecker, ProcessScheduleRepository, ProcessConfigurationsManager).
   • Publish the config if you have not already:

     php artisan vendor:publish --tag=cleverage-ui-process-config
     

Implementation Patterns

Core Workflows

1. Process Definition:

   • Define processes in config/cleverage_ui_process.php under processes.
   • Each process now accepts a new logs option to override the global retention settings:

   'processes' => [
       'example' => [
           'steps' => [
               ['command' => 'php artisan queue:work'],
               ['command' => 'php artisan cache:clear'],
           ],
           'logs' => [
               'database_max_days' => 30,
               'file_max_days' => 14,
           ],
       ],
   ],
   

2. CLI Integration:

   • Run a process:

     php artisan cleverage:ui-process:run example
     

   • Pass dynamic args via --option=value (e.g., --env=production).

3. Scheduler Behaviour (new):

   • A schedule can be disabled via ProcessSchedule::$enabled (default true) or the switch in the schedules list.
   • Disabled schedules are not loaded by the scheduler_cron worker.
   • When a schedule becomes due, CronProcessMessageHandler re-reads it from the database through ProcessScheduleRepository::findFresh() (the handler now takes optional $repository and $logger arguments), so a schedule disabled or deleted after the worker started is not run, and its current input/context is used.

4. Stopping Executions (new):

   • The "Stop the process" action records ProcessExecution::$stopRequestedAt.
   • ProcessExecutionStopChecker (tag cleverage_process.stop_checker) is consulted before each task execution, at most every process_execution.heartbeat_interval seconds (default 5, DBAL read).
   • The execution ends with ProcessExecutionStatus::Stopped; the UI shows "Stop requested" until then.
   • NotificationTrigger::Stopped exists but is not notified by default — opt in via your notification configuration.

5. Heartbeat & Stale Detection (new):

   • ProcessExecutionStopChecker refreshes ProcessExecution::$heartbeatAt.
   • A started execution with no activity for more than process_execution.stale_after seconds (default 900) shows as "Not responding".
   • Such an execution can be "Mark as failed" (POST, confirmation) — end date is its last activity, and the underlying process is not stopped. It can also still be stopped (a process blocked in a long task only stops when that call returns).
   • ProcessExecutionCrudController accepts a new optional $staleAfter constructor argument if you need a different threshold at the controller level.

6. Log Retention (new):

   • Purge old logs (executions are kept):

     php artisan cleverage:ui-process:purge-logs --dry-run   # preview
     php artisan cleverage:ui-process:purge-logs
     

   • Deletes log_record rows (in batches) older than logs.database_max_days and <code>/<uuid>.log files last modified more than logs.file_max_days days ago.
   • Both default to null (nothing deleted) — you must opt in globally or per process via the logs option (ProcessConfigurationsManager::getLogsOptions()).
   • Schedule it (e.g. via scheduler_cron or your own scheduler) as part of routine maintenance.

Integration Tips

• Laravel Events: Keep dispatching processes on domain events; hooks like ProcessStarted/ProcessFailed still apply, and you can now add a Stopped handler.
• Queue Workers: The scheduler worker and the handler read state from the DB, so a queue restart is not needed for disabling — but see gotchas.
• Custom stop logic: Implement/override a stop checker and tag it cleverage_process.stop_checker if you need extra conditions beyond stopRequestedAt/heartbeat.
• Observability: Wire the new stopped notification status into your notifiers so stopping is visible in the same channel as success/failure.

Gotchas and Tips

Breaking / Migration Notes (v3.2)

1. cleverage/process-bundle ^5.3 required:
   • Impact: Composer update fails or the stop checker is not registered on older versions.
   • Fix: composer require cleverage/process-bundle:^5.3 and clear caches.
2. Two new migrations:
   • Impact: Missing columns → runtime SQL errors on the schedules list ("Not responding" never appears) and stop requests never recorded.
   • Fix: Run php artisan migrate on every environment, including workers.
3. Re-enabling a schedule requires a worker restart:
   • Disabling works live (the handler re-reads from DB); enabling a previously disabled schedule does not — the scheduler_cron worker only loads enabled schedules at boot. Restart it after re-enabling.
4. stopped is not notified by default:
   • Fix: Explicitly enable NotificationTrigger::Stopped in your notification configuration if you want parity with success/failure.

Common Pitfalls

• Tuning heartbeat_interval: It is both the stop-check DB-read cadence and the "how fast does Stop take effect" knob. Default 5s is fine for most apps; lower means more DB queries per running execution.
• Confusing "Not responding" with failed: Stale does not mean stopped. "Mark as failed" only closes the record (end date = last activity) — the OS process may still be alive. Combine with the stop action if needed.
• Long-running tasks: A process blocked in a single long task cannot be interrupted mid-call; it stops at the next task boundary. Design step granularity accordingly.
• Retention defaults to null: Logs are kept forever until you set logs.database_max_days / logs.file_max_days. Set both — a database-only policy will leave files on disk.
• First purge reclaims no disk immediately: After the first large log_record delete, run a VACUUM (PostgreSQL) / table optimize (MySQL) — see the package docs on giving space back after the first purge.
• --dry-run before production: Always preview cleverage:ui-process:purge-logs once to confirm your retention windows behave as expected.
• CLI Argument Parsing: Use --help for command-specific args (e.g. php artisan cleverage:ui-process:purge-logs --help).

Extension Points

1. Custom Commands:

   php artisan make:command CustomProcessCommand
   

   Inject Cleverage\UiProcessBundle\Command\ProcessRunner to reuse logic.
2. Stop Checkers: Implement the cleverage_process.stop_checker tag to add custom abort conditions (the built-in ProcessExecutionStopChecker is a good reference; it uses DBAL for a lightweight heartbeat/stop-request read).
3. Schedule Repository: Override or decorate ProcessScheduleRepository (notably findFresh()) if your schedules come from a non-default source; CronProcessMessageHandler accepts it as an optional constructor argument.
4. Event Listeners: Listen for ProcessStarted / ProcessFailed / Stopped for pre/post hooks:

   public function handle(ProcessStarted $event) {
       Log::info('Process ID: '.$event->getProcess()->getId());
   }
   

5. Configuration Overrides: Publish config and override process_execution.heartbeat_interval, process_execution.stale_after, logs.*, and per-process logs.

Debugging Tips

• Verbose Output: Add -vvv to CLI commands for Symfony debug logs.
• Process Logs: Check storage/logs/laravel.log for subprocess errors; per-execution files live at <code>/<uuid>.log (these are what file_max_days targets).
• Stop not taking effect? Verify the worker runs process-bundle ^5.3, that the migration ran, that stop_requested_at is actually set in the DB, and that the execution is in a state where a task boundary will be reached.
• Stale flag never appears? Confirm the heartbeat column is being written (process_execution.heartbeat_at) and that stale_after is smaller than your longest expected idle gap.