Ui Process Bundle Laravel Package

Product Decisions This Supports

• Operational Control as a Feature: v3.2 turns the package from a "workflow UI" into a run-time operations console. PMs can now scope an "Ops/Supervisor" capability — stop a running execution with confirmation (ProcessExecution::$stopRequestedAt), surface a stopped status, and mark dead executions as failed — rather than treating process control as CLI-only engineering work.
• Reliability & Incident Response (New Roadmap Theme): Heartbeat-based staleness detection (process_execution.stale_after, default 900s) plus a "Not responding" UI state and "Mark as failed" action directly supports SLO/incident workflows: users can identify and clean up orphaned executions without engineering intervention.
• Scheduler Governance: Per-schedule enable/disable (ProcessSchedule::$enabled, switch in the schedules list) moves schedule management from deploy-time config to a product-facing toggle. Note the constraint for planning: disabling is safe at any time because due schedules are re-read from the DB (findFresh()), but re-enabling requires a worker restart — factor this into support docs and SLAs.
• Cost & Compliance Governance (Build vs. Buy): The cleverage:ui-process:purge-logs command with --dry-run and per-process logs overrides (database_max_days / file_max_days, both default null = retained) is a buy-not-build win: retention policy, storage reclamation, and data-minimization for logs are handled without custom jobs. Executions are intentionally preserved — useful for audit.
• Feature Expansion: Execution lifecycle is now observable and interruptible from the UI (started → stop requested → stopped / failed), which unblocks dashboards for long-running batch jobs, approvals, and data pipelines.
• Use Cases:
  • Admin/ops dashboards for user and role provisioning.
  • Long-running workflows needing a kill switch (imports, syncs, report generation).
  • Scheduler management for recurring business jobs (billing runs, nightly exports).
  • Log retention/storage-cost control and data-minimization initiatives.

When to Consider This Package

Adopt if:

• You are on (or migrating to) Symfony 7.x / PHP 8.1+ as established for this bundle line — but explicitly re-verify platform versions and the v2 → v3 upgrade path, since v3.2 is a major-version bump that may carry breaking changes beyond the feature set below.
• You can satisfy the new hard dependency: cleverage/process-bundle ^5.3 (required by the stop-checker integration).
• Your product needs operational controls on long-running processes: stop with confirmation, stale/"Not responding" detection, mark-as-failed cleanup.
• You want scheduler toggles in the UI without redeploying, and accept that re-enabling a schedule requires a worker restart.
• You have log growth or retention/compliance requirements and want a maintained purge command rather than a bespoke cron job.
• Your team lacks frontend/ops-tooling capacity but needs credible admin interfaces for backend operations.

Look elsewhere if:

• You are on v2.x and cannot absorb a major-version upgrade (two new migrations: process_schedule.enabled; process_execution.stop_requested_at / heartbeat_at) or cannot upgrade cleverage/process-bundle to ^5.3.
• You need immediate, hard process termination: stopping is cooperative — the stop checker reads the DB at most every process_execution.heartbeat_interval seconds (default 5) and only halts between task executions; a process blocked in a long task call stops only when that call returns. Set expectations accordingly.
• Your runtime cannot tolerate extra DBAL reads per execution heartbeat, or your executions are extremely short-lived (overhead outweighs benefit).
• Your workflows demand highly customized UIs (real-time collaboration, complex drag-and-drop) or a headless API-first architecture.
• You require multi-tenancy or microservice-scale orchestration.
• You need automated retention by default: logs.database_max_days / file_max_days ship as null (retained), so purge is opt-in and must be scheduled by you.

How to Pitch It (Stakeholders)

For Executives: "v3.2 upgrades this from an admin UI to an operations control plane — and it's mostly about risk and cost, not features. Three things matter commercially: (1) Incident response — staff can stop a runaway process from the UI with a confirmation step, and orphaned jobs are flagged 'Not responding' and can be closed out, so bad runs stop burning compute and don't block downstream reporting; (2) Cost control — a built-in, dry-runnable log purge with per-process retention settings lets us enforce a data-retention policy and reclaim storage without custom engineering, while keeping execution records for audit; (3) Fewer deploys — schedules can be toggled on/off in the UI, so pausing a recurring job is no longer an engineering ticket. Costs to plan for: a major-version upgrade (v2 → v3.2) with two database migrations, a required bump to cleverage/process-bundle ^5.3, and one operational caveat: re-enabling a schedule needs a worker restart, and 'stop' is cooperative — it lands between tasks, not mid-task. Net: low incremental spend, measurable savings in compute and storage, and materially better operational maturity."

For Engineering: *"v3.2 is a major release — treat it as an upgrade project, not a patch. Scope:

• Upgrade prerequisites: bump cleverage/process-bundle to ^5.3 (the stop checker depends on cleverage/process-bundle#266, service tag cleverage_process.stop_checker). Run two migrations: Version20261013120000 (process_schedule.enabled, existing schedules backfilled enabled) and Version20261014120000 (process_execution.stop_requested_at, process_execution.heartbeat_at, both nullable). Re-verify Symfony/PHP support against your runtime rather than assuming v2.3's matrix.
• Stop path: "Stop the process" is a POST with confirmation on started executions; it records a stop request, and ProcessExecutionStopChecker polls via DBAL before each task execution, throttled to process_execution.heartbeat_interval (default 5s). New ProcessExecutionStatus::Stopped and NotificationTrigger::Stopped (not notified by default — wire it if you need alerting). It's cooperative: long task calls must return before the stop takes effect.
• Staleness: the checker also writes heartbeatAt; a started execution idle beyond process_execution.stale_after (default 900s) renders as "Not responding" and can be marked failed (POST + confirmation; end date = last activity; the underlying process is not stopped). ProcessExecutionCrudController gains an optional $staleAfter argument — useful for tuning per environment and for tests.
• Scheduler: ProcessSchedule::$enabled (default true) with a list switch; the scheduler_cron worker skips disabled schedules, and CronProcessMessageHandler re-reads due schedules from the DB (new optional $repository / $logger args, ProcessScheduleRepository::findFresh()) so post-start disables/deletes are honored and current input/context is used. Re-enabling still requires a worker restart — document this for support.
• Retention: cleverage:ui-process:purge-logs [--dry-run] batch-deletes log_record older than logs.database_max_days and <code>/<uuid>.log files older than logs.file_max_days (both default null = keep), overridable per process via ProcessConfigurationsManager::getLogsOptions(). Executions are retained. Read the docs on reclaiming DB space after the first purge; schedule it via cron and run --dry-run first.
• Tradeoffs: heartbeat polling adds a DBAL read per execution interval (negligible for long jobs, measurable for very short ones), docs remain sparse, and the major-version jump means a real regression-test cycle — budget roughly a sprint for upgrade + scaffolding a basic ops UI."*