adachsoft / scheduler-contracts
Interfaces and data transfer objects for periodic job scheduling.
Requires
- php: ^8.3
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
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
JobIdis a validated value object identifying a job.ScheduledJobInterfacedefines an application job that receives a run context and returns a result.JobResolverInterfaceresolves a job identifier to its application job.JobResultDtocarries a job's message, warnings, and scalar metadata.JobRunContextDtocarries the identity, trigger, timing, and attempt information for one run.
Schedules and definitions
ScheduleInterfacedescribes a schedule and returns the next run time after a given instant.JobPolicyDtodefines timeout, locking, retry, overdue, failure, and history-retention policy.JobDefinitionDtocombines a job identifier, schedule, policy, and description.JobDefinitionDtoCollectionprovides immutable access to job definitions while rejecting duplicate identifiers.JobDefinitionProviderInterfaceprovides the definitions registered with a scheduler.
Runs and execution
RunTriggerEnumidentifies whether a run was scheduled, retried, or started manually.JobRunOutcomeEnumidentifies a run's successful, failed, timed-out, or lock-skipped outcome.JobRunRecordDtorecords the timing, outcome, result, and errors for one run.JobRunRecordDtoCollectionis an immutable collection of run records.SchedulerInterfaceexposes scheduler operations for ticking due jobs, running one job, and finding the next due time.JobExecutionResultDtorepresents a successful, failed, or timed-out execution; job failures are values, not exceptions.JobExecutorInterfacedefines execution of a job from its definition and run context.
State and locking
CurrentRunDtodescribes an execution that is currently in progress.JobStateDtocarries the persisted scheduling and recent-run state for one job.JobStateRepositoryInterfacedefines loading and saving job state.JobLockInterfacedefines exclusive, time-limited locks that prevent overlapping runs.
Status and history
JobHealthEnumclassifies a job as healthy, pending, running, overdue, or failing.JobStatusDtocarries the health and scheduling status for one job.JobStatusDtoCollectionprovides immutable status iteration, health checks, and unhealthy-status filtering.JobStatusProviderInterfaceprovides status for all jobs or one job.JobRunHistoryQueryDtodefines optional run-history filters and bounded pagination.JobRunHistoryRepositoryInterfacedefines 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.