Download the PHP package nixphp/schedule without Composer

[!IMPORTANT] NixPHP is now NAF — "Not Another Framework".

This package continues as naf/schedule: github.com/nafphp/schedule · documentation · what changed and how to move

The old name collided with NixOS down to the shell, where the CLI binary was literally nix. This repository is archived and receives no further releases; nixphp/schedule stays on Packagist so existing installations keep working.

Note the plugin type. NAF discovers plugins by the Composer type naf-plugin. A package still declaring nixphp-plugin is not loaded — silently, with no error.

← Back to NixPHP

nixphp/schedule

Minimalistic scheduling for NixPHP – cron-based, predictable, and queue-aware.

This plugin provides a lightweight scheduler for recurring tasks using cron expressions. It is designed to work seamlessly with the NixPHP Queue plugin, without introducing hidden magic or unnecessary complexity.

🧩 Part of the official NixPHP plugin collection.
Use it when you want to run recurring jobs reliably – without relying on system cron files or external schedulers.

Features

• Cron-based scheduling (* * * * * syntax)
• Central scheduler loop (schedule:ticker)
• Queue-backed execution (no direct execution in the ticker)
• Automatic backlog prevention (latest run wins)
• Persistent scheduler state (prevents duplicate runs)
• No marker interfaces, no job annotations
• Fully deterministic and testable

📥 Installation

`

The plugin will be autoloaded automatically.

Basic idea

The scheduler does not execute jobs directly.

Instead:

1. The scheduler decides which jobs are due
2. Due jobs are queued
3. Queue workers execute them asynchronously

This keeps scheduling and execution cleanly separated.

Defining scheduled jobs

A scheduled job is a normal queue job that additionally implements ScheduledJobInterface:

Registering scheduled jobs

Register scheduled jobs via the Scheduler:

Payloads can be passed as well:

Running the scheduler

Start the scheduler ticker via CLI:

The ticker:

• checks all registered jobs
• evaluates cron expressions
• queues jobs that are due

It runs continuously and is usually managed by Supervisor or systemd.

Backlog handling (important)

The problem

If the scheduler runs but queue workers are down, scheduled jobs can pile up. In most cases this is not desired: polling, syncing, rebuilding, or checking tasks usually only need to run once with the latest state.

The solution: automatic coalescing

By default, the scheduler coalesces scheduled jobs:

If a job was scheduled multiple times while workers were unavailable, only the latest execution is kept in the queue.

This prevents useless backlogs and keeps execution predictable.

How it works (internally)

The scheduler assigns a deterministic job ID based on:

• job class
• cron expression

This causes older queued runs to be replaced automatically.

No special configuration is required. Queue drivers remain fully generic.

Configuration

You can control this behavior via configuration:

When to disable coalescing

Set coalesce to false if:

• every scheduled run must be processed (e.g. audits, snapshots)
• time-based effects must not be skipped
• backlog processing is intentional

Duplicate execution prevention

The scheduler also tracks its own state internally to ensure that:

• a job is only queued once per cron minute
• restarts do not cause duplicate enqueues

State is stored in a small JSON file (configurable).

Worker interaction

The scheduler does not spawn queue workers by default.

You are expected to run queue workers independently, e.g. via Supervisor:

This keeps the system flexible and avoids hidden background processes.

Supervisor example (optional)

Requirements

• nixphp/framework ^0.1.0
• nixphp/queue ^0.1.0
• nixphp/cli ^0.1.0

📄 License

MIT License.