Ui Process Bundle Laravel Package

Technical Evaluation

Architecture Fit

The Cleverage UI Process Bundle (v3.2) remains a Laravel-compatible package that extends Symfony-based process management workflows with a UI layer. It now adds scheduling control, manual process termination, stale execution detection, and log retention, making it more suitable for production-grade workflow automation. The package still leverages Symfony components (Process, Workflow, Messenger) and integrates with Laravel via service providers and Artisan commands.

However, v3.2 introduces a major dependency shift: it requires cleverage/process-bundle ^5.3 (previously ^2.0). This version of the process bundle likely requires newer Symfony and PHP versions (e.g., Symfony 7.3+, PHP 8.2+), which may not be compatible with older Laravel installations. The new features (stop checker, heartbeat, stale detection) rely on database reads/writes and DBAL, introducing tighter coupling between the UI bundle and the process execution database schema.

Integration Feasibility

• Dependency upgrade required: cleverage/process-bundle must be upgraded to ^5.3, which may itself require a newer Symfony version and PHP 8.2+.
• New migrations: Two new migrations (Version20261013120000 adding process_schedule.enabled; Version20261014120000 adding process_execution.stop_requested_at and heartbeat_at) must be run.
• New configuration: process_execution.heartbeat_interval (default 5s), process_execution.stale_after (default 900s), logs.database_max_days, and logs.file_max_days (default null) need to be published and tuned.
• New command: cleverage:ui-process:purge-logs (with --dry-run) should be scheduled for log retention.
• Backward compatibility: No breaking changes at the bundle API level (new constructor arguments are optional), but the process-bundle dependency bump is a breaking change for existing installations that cannot upgrade.

Technical Risk

Key Questions

1. What is the current cleverage/process-bundle version?
   • Must be ^5.3 for v3.2. If not, plan an upgrade path (may require Symfony/PHP upgrades).
2. What PHP and Symfony versions are in use?
   • process-bundle 5.3 likely requires PHP 8.2+ and Symfony 7.3+. Confirm Laravel compatibility.
3. Are there existing scheduled processes?
   • The enabled flag defaults to true; migrating existing schedules is safe. Test disabling/re-enabling with worker restarts.
4. How will log retention be managed?
   • Decide logs.database_max_days and logs.file_max_days. Schedule the purge command daily. Ensure the logs option per process is set if overrides needed.
5. What is the expected longest task duration?
   • Set process_execution.stale_after to exceed it (default 900s). Adjust heartbeat interval if DB load is a concern.
6. Who can stop or mark executions as failed?
   • Ensure authorization (Laravel Gates/Policies) for the new POST actions on the UI.

Integration Approach

Stack Fit

Migration Path

1. Pre-Integration Checks:
   • Confirm composer.json allows cleverage/process-bundle:^5.3.
   • Run composer why-not cleverage/process-bundle:^5.3 to identify conflicts.
   • Verify Symfony/PHP versions match process-bundle 5.3 requirements (check its composer.json).
2. Upgrade process-bundle:

   composer require cleverage/process-bundle:^5.3 --with-dependencies
   

   • Run any process-bundle migrations first.
3. Install UI Process Bundle v3.2:

   composer require cleverage/ui-process-bundle:^3.2
   php artisan vendor:publish --provider="Cleverage\UiProcessBundle\UiProcessBundle" --tag="config"
   php artisan migrate
   

4. Configuration:
   • Publish and update config/ui_process.php with new options:
     • process_execution.heartbeat_interval (default 5)
     • process_execution.stale_after (default 900)
     • logs.database_max_days (default null)
     • logs.file_max_days (default null)
   • Register service provider if not auto-discovered.
5. Testing:
   • Test new UI actions: “Stop the process” (on started executions), “Mark as failed” (on non-responding executions).
   • Test scheduler disable/enable (requires worker restart for enable).
   • Test purge-logs --dry-run and then with a short retention window.
   • Verify stop checker: start a long process, stop it from UI, confirm status becomes stopped.
6. Schedule purge command:

   // In app/Console/Kernel.php
   $schedule->command('cleverage:ui-process:purge-logs')->daily();
   

Compatibility

• Backward Compatibility: API changes are additive (optional constructor args), but the process-bundle major version bump is a hard break. If you cannot upgrade process-bundle, do not upgrade to v3.2.
• Rollback: After upgrading process-bundle, rolling back UI bundle to v2.3 is not supported. Plan a full-stack upgrade (PHP, Symfony, Laravel) together.
• Forward Compatibility: v3.2 targets current LTS versions (Laravel 11, Symfony 7.3). Future Symfony 8 may require another process-bundle upgrade.

Sequencing

1. Phase 1: Dependency Upgrade
   • Upgrade PHP to 8.2+ and Symfony to 7.3+ if needed.
   • Upgrade cleverage/process-bundle to ^5.3; run its migrations.
2. Phase 2: Bundle Integration
   • Install v3.2; publish config; run new migrations.
   • Configure heartbeat_interval, stale_after, and log retention values.
3. Phase 3: Feature Validation
   • Test new UI actions (stop, mark failed) in staging.
   • Verify stop checker and heartbeat behavior with long-running processes.
   • Validate schedule enable/disable (including worker restart).
4. Phase 4: Operational Readiness
   • Schedule purge-logs and monitor its output.
   • Update runbooks for stopping executions and handling “Not responding” statuses.
   • Set up alerts for stale executions (e.g., query process_execution where heartbeat_at < now() - stale_after).

Operational Impact

Maintenance

• Dependency upgrades: process-bundle ^5.3 is a major version; track its releases for further breaking changes (e.g., Symfony 8 support). Use composer update --with-dependencies cautiously.
• Configuration drift: New settings (heartbeat_interval, stale_after, log retention) must be maintained in version control. Document per-process logs overrides.
• Log retention: Schedule purge-logs daily. After the first large purge, run the recommended database maintenance (e.g., OPTIMIZE TABLE for MySQL, VACUUM for PostgreSQL) to reclaim disk space.
• Schedule worker restarts: Enabling a previously disabled schedule requires restarting the scheduler_cron worker. Document this and consider automating via deployment hooks.

Support

• Debugging stop requests: Check process_execution.stop_requested_at and heartbeat_at columns. Logs from ProcessExecutionStopChecker (tag cleverage_process.stop_checker) indicate when a stop is detected.
• Stale executions: “Not responding” executions have heartbeat_at older than stale_after. Use “Mark as failed” (POST) if the process is unrecoverable; note that it does not stop the underlying process.
• Log purge issues: Run cleverage:ui-process:purge-logs --dry-run to see what would be deleted. Ensure logs.file_max_days is set if you want file cleanup.
• Common pitfalls:
  • Stop request only checked every heartbeat_interval seconds; long tasks may delay stopping.
  • Enabling a disabled schedule does not take effect until worker restart.
  • Log purge deletes log_record and <code>/<uuid>.log files but keeps executions; adjust retention to meet audit needs.

Scaling

• Heartbeat writes: The stop checker updates heartbeat_at at most every heartbeat_interval (default 5s) per running execution. For dozens of concurrent executions this is negligible; for hundreds, monitor DB write load.
• Stop checker reads: Each task execution reads stop_requested_at via DBAL. Optimize with indexing on process_execution.id (primary key) – no extra index needed.
• Scheduler: Disabled schedules are not loaded by the worker, reducing overhead. Re-enabling requires restart, so batch enable/disable operations during maintenance windows.
• Log purge: Run during low-traffic periods. Use --dry-run first. For large tables, batch deletes (built-in) avoid long locks.

Failure Modes

Ramp-Up

• Developer training:
  • New UI actions: stop execution (POST with confirmation), mark as failed.
  • Schedule management: toggle enabled flag, understand worker restart requirement.
  • Log retention: configure logs options and schedule purge command.
• Operations training:
  • How to interpret “Not responding” status and when to mark as failed vs. stop.
  • How to run purge-logs safely and reclaim database space.
  • Monitoring: alert on stale executions (heartbeat_at < now() - stale_after) and failed stop requests.
• Estimated ramp-up: 1–2 days for developers familiar with Laravel/Symfony; add 1 day for operations to update runbooks and monitoring.