adachsoft / workflow-launcher-contracts
Contracts and in-memory concurrency support for launching workflows.
Package info
gitlab.com/a.adach/workflow-launcher-contracts
pkg:composer/adachsoft/workflow-launcher-contracts
Requires
- php: ^8.3
- psr/clock: ^1.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- 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 that defines the contracts and value objects needed to launch workflows consistently. It also provides an in-memory concurrency-slot implementation for lightweight, single-process use.
Features
- Workflow launch and launch-budget guard interfaces.
- Typed request, result, concurrency policy, and reservation DTOs.
- Enums for launch triggers, outcomes, and concurrency conflict actions.
- In-memory concurrency reservations with configurable expiration, using a PSR-20 clock.
Requirements
- PHP 8.3 or later.
- Composer.
The in-memory concurrency implementation also requires a PSR-20 clock implementation, which must be provided by your application.
Installation
Install the library with Composer:
composer require adachsoft/workflow-launcher-contracts
The in-memory concurrency implementation requires a PSR-20 clock implementation. Add a clock provider to your application if you use that feature.
Basic usage
Create a launch request and implement the launcher contract in your application:
use AdachSoft\WorkflowLauncherContracts\Dto\WorkflowLaunchRequestDto;
use AdachSoft\WorkflowLauncherContracts\Dto\WorkflowLaunchResultDto;
use AdachSoft\WorkflowLauncherContracts\Enum\LaunchTriggerEnum;
use AdachSoft\WorkflowLauncherContracts\WorkflowLauncherInterface;
final class WorkflowLauncher implements WorkflowLauncherInterface
{
public function launch(WorkflowLaunchRequestDto $request): WorkflowLaunchResultDto
{
// Resolve and start the workflow in your application.
return WorkflowLaunchResultDto::started('run-123');
}
}
$request = new WorkflowLaunchRequestDto(
workflowId: 'daily-report',
input: ['date' => '2025-01-01'],
trigger: LaunchTriggerEnum::MANUAL,
);
$result = (new WorkflowLauncher())->launch($request);
Resuming runs in the background
Applications can dispatch decision-based and timeout-based resumptions through WorkflowResumeDispatcherInterface, so the remaining workflow steps can run outside an HTTP request or scheduler process while following the launcher's concurrency rules. Accepted requests return a STARTED result with the same run ID; requests that cannot proceed now return REJECTED with a reason, while unknown run IDs raise WorkflowRunNotFoundException.
See the usage examples for launch handling and concurrency reservations.