Search by

adachsoft / workflow-launcher

Arkadiusz Adach

Launches adachsoft/workflow runs in detached child processes with concurrency, budget, and idempotency guards.

Package info

gitlab.com/a.adach/workflow-launcher

Issues

pkg:composer/adachsoft/workflow-launcher

Statistics

Installs: 32

Dependents: 1

Suggesters: 0

Stars: 0

v0.3.0 2026-11-21 10:14 UTC

This package is auto-updated.

Last update: 2026-11-21 09:14:49 UTC


README

A PHP library for starting adachsoft/workflow runs in detached child processes. It coordinates workflow launch requests and applies optional budget, concurrency, and idempotency guards.

Features

  • Launch workflows asynchronously through a detached console process.
  • Enforce per-workflow concurrency limits using expiring lease locks.
  • Deduplicate requests with an idempotency key.
  • Persist a private launch envelope for the child process to consume.
  • Start detached child processes using adachsoft/command-executor-lib.
  • Provide extension points for run identifiers, launch policies, and storage.

Requirements

  • PHP 8.3 or later.
  • An application using adachsoft/workflow with the workflow runtime and launch infrastructure services configured.

Starting detached processes

DetachedConsoleRunProcessStarter delegates detached process execution to AdachSoft\CommandExecutorLib\DetachedCommandExecutorInterface; configure AdachSoft\CommandExecutorLib\SimpleDetachedCommandExecutor as its implementation. The starter escapes each command argument separately and writes the child process output to a private per-run log file.

An empty environment array makes the executor inherit the complete current process environment. This allows process-level variables, including secrets that are not present in $_SERVER, to reach the child. A non-empty array replaces the inherited environment.

Installation

composer require adachsoft/workflow-launcher

The application must also provide the workflow runtime and implementations of the launch budget, concurrency policy, concurrency slot, idempotency, envelope storage, and run process starter dependencies. See the launch example for the request API and the required application wiring.

Usage

Inject AdachSoft\WorkflowLauncher\DirectWorkflowLauncher into the application service that handles launch requests, then create a WorkflowLaunchRequestDto and call launch(). The result reports whether the run started, was rejected, or matched a previous idempotent request.

Resuming runs in the background

Inject AdachSoft\WorkflowLauncher\DirectWorkflowResumeDispatcher where suspended runs are approved or timed out. Create a WorkflowResumeRequestDto with decision($runId, $decision, $actor, $payload) or timeout($runId), then call dispatch(). A STARTED result means the resume envelope was stored and a detached child process was started; REJECTED includes a reason when the run is not eligible or its concurrency limit is reached.

Decision requests are checked against the suspension's allowed decisions. Timeout requests are accepted only when a deadline exists and has arrived. Resumes use the workflow's concurrency policy and continue execution in the detached process, so a long-running continuation does not block the calling request. A per-run lease lock rejects concurrent start or resume dispatches for the same run and is released by the child process after execution, including when the runner throws.