Search by

adachsoft / automation-contracts

Arkadiusz Adach

Framework-independent contracts and value objects for user-defined automation schedules

Package info

gitlab.com/a.adach/automation-contracts

Issues

pkg:composer/adachsoft/automation-contracts

Statistics

Installs: 16

Dependents: 1

Suggesters: 0

Stars: 0

v0.1.2 2026-11-22 18:50 UTC

This package is auto-updated.

Last update: 2026-11-22 17:50:40 UTC


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:

  • SKIP skips occurrences older than now - missedGraceSeconds and fires the remaining occurrences.
  • RUN_LATEST fires only the latest due occurrence and skips earlier ones.
  • RUN_ALL processes due occurrences in order up to maxCatchUp; 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.