adachsoft / workflow-launcher
Launches adachsoft/workflow runs in detached child processes with concurrency, budget, and idempotency guards.
Requires
- php: ^8.3
- adachsoft/command-executor-lib: ^2.4
- adachsoft/lease-lock-contracts: ^0.1.0
- adachsoft/workflow: ^7.1
- adachsoft/workflow-launcher-contracts: ^0.2.0
- psr/clock: ^1.0
- psr/log: ^3.0
Requires (Dev)
- adachsoft/lease-lock: ^0.1.0
- adachsoft/php-code-style: ^0.7.3
- adachsoft/workflow-launcher-contract-tests: ^0.1.1
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^12.5
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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/workflowwith 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.