Search by

adachsoft / scheduler-contracts

Arkadiusz Adach

Interfaces and data transfer objects for periodic job scheduling.

Package info

gitlab.com/a.adach/scheduler-contracts

Issues

pkg:composer/adachsoft/scheduler-contracts

Statistics

Installs: 11

Dependents: 1

Suggesters: 0

Stars: 0

v0.1.0 2026-11-19 15:01 UTC

This package is auto-updated.

Last update: 2026-11-19 14:02:00 UTC


README

adachsoft/scheduler-contracts defines the PHP 8.3 contracts and immutable data transfer objects for scheduled job execution. It allows applications to define jobs and adapters to provide scheduling, execution, state storage, locking, health reporting, and run history without coupling those contracts to a specific implementation.

Installation

Install the package with Composer:

composer require adachsoft/scheduler-contracts

Composer's PSR-4 autoloader exposes classes under the AdachSoft\\SchedulerContracts namespace. Use the contracts to connect your scheduler implementation to application jobs, scheduling rules, and storage or execution adapters.

Requirements

  • PHP 8.3 or later.

Contracts and data types

Jobs

  • JobId is a validated value object identifying a job.
  • ScheduledJobInterface defines an application job that receives a run context and returns a result.
  • JobResolverInterface resolves a job identifier to its application job.
  • JobResultDto carries a job's message, warnings, and scalar metadata.
  • JobRunContextDto carries the identity, trigger, timing, and attempt information for one run.

Schedules and definitions

  • ScheduleInterface describes a schedule and returns the next run time after a given instant.
  • JobPolicyDto defines timeout, locking, retry, overdue, failure, and history-retention policy.
  • JobDefinitionDto combines a job identifier, schedule, policy, and description.
  • JobDefinitionDtoCollection provides immutable access to job definitions while rejecting duplicate identifiers.
  • JobDefinitionProviderInterface provides the definitions registered with a scheduler.

Runs and execution

  • RunTriggerEnum identifies whether a run was scheduled, retried, or started manually.
  • JobRunOutcomeEnum identifies a run's successful, failed, timed-out, or lock-skipped outcome.
  • JobRunRecordDto records the timing, outcome, result, and errors for one run.
  • JobRunRecordDtoCollection is an immutable collection of run records.
  • SchedulerInterface exposes scheduler operations for ticking due jobs, running one job, and finding the next due time.
  • JobExecutionResultDto represents a successful, failed, or timed-out execution; job failures are values, not exceptions.
  • JobExecutorInterface defines execution of a job from its definition and run context.

State and locking

  • CurrentRunDto describes an execution that is currently in progress.
  • JobStateDto carries the persisted scheduling and recent-run state for one job.
  • JobStateRepositoryInterface defines loading and saving job state.
  • JobLockInterface defines exclusive, time-limited locks that prevent overlapping runs.

Status and history

  • JobHealthEnum classifies a job as healthy, pending, running, overdue, or failing.
  • JobStatusDto carries the health and scheduling status for one job.
  • JobStatusDtoCollection provides immutable status iteration, health checks, and unhealthy-status filtering.
  • JobStatusProviderInterface provides status for all jobs or one job.
  • JobRunHistoryQueryDto defines optional run-history filters and bounded pagination.
  • JobRunHistoryRepositoryInterface defines appending, querying, and pruning run history.

The package also defines SchedulerException and its specialized exceptions for missing jobs, storage failures, and invalid job policies.

Example

<?php

declare(strict_types=1);

use AdachSoft\SchedulerContracts\Definition\JobPolicyDto;
use AdachSoft\SchedulerContracts\Job\JobResultDto;
use AdachSoft\SchedulerContracts\Job\JobRunContextDto;
use AdachSoft\SchedulerContracts\Job\ScheduledJobInterface;

final class PricingSyncJob implements ScheduledJobInterface
{
    public function run(JobRunContextDto $context): JobResultDto
    {
        // Perform application-specific pricing synchronization.
        return new JobResultDto('Pricing synchronized.');
    }
}

$policy = new JobPolicyDto(timeoutSeconds: 300, retryDelaySeconds: 3600);

The scheduler implementation and storage adapters are provided by adachsoft/scheduler; this package contains contracts and data types only.