adachsoft / automation-contracts
Framework-independent contracts and value objects for user-defined automation schedules
Requires
- php: ^8.3
- adachsoft/action-contracts: ^0.1
- adachsoft/recurrence-contracts: ^0.1
- adachsoft/reference-contracts: ^0.1
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Framework-independent PHP 8.3+ contracts and immutable value objects for user-defined schedules that run ordered actions. The package defines schedule definitions, runtime state, repository contracts, execution-facing interfaces, stop-condition extension points, and in-memory repositories for tests and lightweight use. It does not provide a scheduler tick implementation or a framework integration.
Installation
Install the package with Composer:
composer require adachsoft/automation-contracts
Model
A schedule definition and its changing execution state are stored separately:
ScheduleDto (definition)
owner, recurrence rule, ordered actions, run policies, stop conditions
| |
v v
ScheduleRepositoryInterface ScheduleStateRepositoryInterface
ScheduleStateDto (runtime state)
evaluatedUntil, nextOccurrenceAt,
last-fired data, stop data, failures
FiredOccurrenceRepositoryInterface
(schedule id, UTC occurrence key) -> at-most-once marker
ScheduleDto is the user's configuration. ScheduleStateDto is the runner's cursor and runtime result; the state repository queries only this state and never reads a schedule definition. A persistent adapter and a runner can be supplied by an application.
Delivery semantics
A runner writes the fired-occurrence marker before invoking actions. This is at-most-once delivery, not exactly-once delivery: if a process crashes after markFired() but before action execution, the occurrence remains marked and its actions are not retried. Repositories used by concurrent workers must implement atomic insert-if-absent and coordinate schedule work with the lease lock automation.schedule.<schedule-id>.
The missed-run policy controls overdue occurrences:
SKIPskips occurrences older thannow - missedGraceSecondsand fires the remaining occurrences.RUN_LATESTfires only the latest due occurrence and skips earlier ones.RUN_ALLprocesses due occurrences in order up tomaxCatchUp; excess occurrences are skipped.
A stop condition is an application-defined StopConditionDto evaluated through StopConditionInterface. A non-null reason stops the schedule. Condition types are open identifiers such as reminder.acknowledged; the package does not implement domain-specific conditions.
Example: daily 19:00 light switch
The following definition repeats daily at 19:00 in the selected time zone and configures a homeiot.device.set action. The action parameter keys must match the schema registered by the application.
<?php
declare(strict_types=1);
use AdachSoft\ActionContracts\Definition\ActionDefinitionCollection;
use AdachSoft\ActionContracts\Definition\ActionDefinitionDto;
use AdachSoft\ActionContracts\Type\ActionTypeId;
use AdachSoft\AutomationContracts\Schedule\ScheduleDto;
use AdachSoft\AutomationContracts\Schedule\ScheduleId;
use AdachSoft\RecurrenceContracts\Rule\FrequencyEnum;
use AdachSoft\RecurrenceContracts\Rule\RepeatingRuleDto;
use AdachSoft\ReferenceContracts\PrincipalReference;
use DateTimeImmutable;
use DateTimeZone;
$timezone = new DateTimeZone('Europe/Warsaw');
$createdAt = new DateTimeImmutable('2025-01-01T18:00:00', $timezone);
$rule = new RepeatingRuleDto(
start: new DateTimeImmutable('2025-01-01T19:00:00', $timezone),
timezone: $timezone,
frequency: FrequencyEnum::DAILY,
);
$lightAction = new ActionDefinitionDto(
new ActionTypeId('homeiot.device.set'),
['device' => 'living-room-light', 'state' => 'on'],
label: 'Switch on the living-room light',
);
$schedule = new ScheduleDto(
id: new ScheduleId('daily-light'),
owner: new PrincipalReference('user', 'alice'),
name: 'Switch on the living-room light',
rule: $rule,
actions: new ActionDefinitionCollection([$lightAction]),
createdAt: $createdAt,
updatedAt: $createdAt,
);
The schedule definition can be persisted through ScheduleRepositoryInterface; runtime cursors and firing markers use their separate repository interfaces. The AutomationTickInterface describes the runner contract without coupling it to a framework or storage engine.
Requirements
The package requires PHP ^8.3 and uses the framework-free action-contracts, recurrence-contracts, and reference-contracts packages for shared action, recurrence, and identity types.