[Proposal] Scheduled Sequences — persistent irregular application schedules

[savgoran]

Summary

This proposal explores a first-class Laravel abstraction for persistent sequences of actions that occur at irregular times relative to an entity-specific start time.

A Scheduled Sequence persists its current scheduling state, evaluates application state immediately before each occurrence, and may complete, cancel, or continue recurring after its configured sequence.

It is intended to complement Laravel's existing Scheduler and queues rather than replace them.

Mechanism	Responsibility
Laravel Scheduler	Determines when the application checks for due work
Queue / delayed jobs	Executes or defers an individual unit of work
Scheduled Sequence	Owns persistent, entity-specific temporal state between occurrences

The important distinction is not simply how an action is executed later, but where the authoritative scheduling state lives.

A working package implements the core concept. Its design evolved from a predecessor used in production for two years.

---

Motivation

Some application schedules do not fit a recurring cron expression.

Consider an account that becomes unpaid. The business requirement may be:

immediately
+1 day at 10:00
+2 days at 10:00
+4 days at 10:00
+7 days at 10:00
+10 days at 10:00
+15 days at 10:00
+20 days at 10:00
then every 5 days

Every account starts this sequence independently.

Before each occurrence, the application must also check whether the account is still unpaid. If it has been paid, the remaining sequence should be cancelled.

The schedule maps naturally to a declaration such as:

protected array $offsets = [
    'now',
    '1 day 10am',
    '2 days 10am',
    '4 days 10am',
    '7 days 10am',
    '10 days 10am',
    '15 days 10am',
    '20 days 10am',
];

protected ?string $repeatEveryAfterwards = '5 days';

This is not naturally represented by a cron expression.

It can be implemented using delayed jobs, but the application must then manage additional concerns such as:

• which occurrence is currently active;
• cancellation when application state changes;
• irregular offsets;
• indefinite recurrence after a finite sequence;
• rescheduling;
• concurrency;
• failure behavior;
• inspecting the current state of the sequence.

The underlying abstraction is relatively small:

Application entity
        │
        ▼
     start_at
        │
        ▼
 irregular offsets
        │
        ▼
      next_at
        │
        ▼
 shouldContinue()
      /      \
    yes       no
     │         │
 handle()    cancel
     │
     ▼
 next occurrence

---

Proposed API

The following API is illustrative and based on the reference implementation.

It is included to make the proposed abstraction concrete, not as a proposed final framework API.

A sequence could be represented by a dedicated class:

use Illuminate\Scheduling\Occurrence;
use Illuminate\Scheduling\ScheduledSequence;

final class AccountLeftUnpaidSequence extends ScheduledSequence
{
    protected array $offsets = [
        'now',
        '1 day 10am',
        '2 days 10am',
        '4 days 10am',
        '7 days 10am',
        '10 days 10am',
        '15 days 10am',
        '20 days 10am',
    ];

    protected ?string $repeatEveryAfterwards = '5 days';

    protected function shouldContinue(): bool
    {
        return $this->model->isUnpaid();
    }

    protected function handle(Occurrence $occurrence): void
    {
        if ($occurrence->offset === 'now') {
            $this->sendInitialNotice();

            return;
        }

        $this->sendReminder();
    }
}

The sequence could then be started for an application entity:

AccountLeftUnpaidSequence::start($account);

An Occurrence object could expose contextual information such as:

$occurrence->offset;
$occurrence->scheduledAt;
$occurrence->sequence;

The exact namespace, inheritance model, offset representation, and method names are intentionally open for discussion.

---

This Is Not Notification-Specific

Notifications are an easy real-world example, but Scheduled Sequences describe temporal application behavior generally.

For example, a provisioning process might require:

today
tomorrow at 09:00
tomorrow at 17:00
5 days later
12 days later

It could be represented by:

final class ProvisioningSequence extends ScheduledSequence
{
    protected array $offsets = [
        'now',
        'tomorrow 9am',
        'tomorrow 5pm',
        '5 days',
        '12 days',
    ];

    protected function shouldContinue(): bool
    {
        return ! $this->model->provisioning_completed;
    }

    protected function handle(Occurrence $occurrence): void
    {
        // Perform the action associated with this occurrence.
    }
}

The abstraction is therefore about irregular temporal sequences, not notification delivery.

---

Persistent Scheduling State

The main difference from delayed jobs is where the authoritative future scheduling state is stored.

With multiple delayed jobs, future scheduling state effectively exists inside the queue:

Application
    │
    ├──────► delayed job: +1 day
    ├──────► delayed job: +3 days
    ├──────► delayed job: +7 days
    └──────► delayed job: +15 days

With a Scheduled Sequence:

Application entity
        │
        ▼
 Scheduled Sequence
   ├── start_at
   ├── next_at
   └── current state
        │
        ▼
      action
        │
        ▼
   optional queue

The queue may still execute the action, but it is not the canonical representation of the future schedule.

A Scheduled Sequence would persist only the state required to determine its next occurrence.

Conceptually:

id
handler
sequenceable_type
sequenceable_id
start_at
next_at
status

An Eloquent polymorphic relationship is one natural implementation, and is what the reference package currently uses.

However, the abstraction itself does not necessarily need to be restricted to Eloquent models.

The full set of future timestamps does not need to be stored. Future occurrences are derived from the sequence definition and its start_at.

---

Conditional Continuation

An important characteristic is that current application state is evaluated immediately before an occurrence executes.

For example:

protected function shouldContinue(): bool
{
    return $this->model->status === AccountStatus::Unpaid;
}

If the account becomes paid between the 7-day and 10-day occurrences, the next execution detects that state and cancels the remaining sequence.

This keeps the temporal definition and the business condition controlling its lifetime together.

---

Recurrence After an Irregular Prefix

A sequence may optionally transition from irregular offsets into regular recurrence.

For example:

protected array $offsets = [
    '1 day',
    '3 days',
    '7 days',
    '15 days',
    '20 days',
];

protected ?string $repeatEveryAfterwards = '5 days';

represents:

Day 1
Day 3
Day 7
Day 15
Day 20
Day 25
Day 30
Day 35
...

No unbounded collection of future jobs needs to be created.

The sequence only needs to know its current state and next occurrence.

---

Relationship to Laravel Scheduler

Scheduled Sequences would not replace Laravel's Scheduler.

An application could continue using a normal Laravel schedule:

Schedule::command('scheduled-sequence:run')
    ->everyMinute()
    ->withoutOverlapping();

The runner only needs to find active sequences where:

next_at <= now()

and process those occurrences.

The distinction is:

Laravel Scheduler: When should the application run this task?

versus:

Scheduled Sequence: When should this action next run for this particular application entity?

The current reference package registers the minute runner automatically, so applications do not need to add this command to their scheduler manually.

The framework-level responsibility remains the same: Laravel's Scheduler wakes the package runner.

---

Relationship to Queues

Scheduled Sequences would also not replace queues.

An occurrence may execute synchronously or dispatch normal queued work:

protected function handle(Occurrence $occurrence): void
{
    SendAccountReminder::dispatch($this->model);
}

Queues remain the execution mechanism.

The sequence owns the persistent scheduling state.

---

Why Not Use Delayed Jobs?

Laravel already supports delayed jobs:

SendReminder::dispatch($account)
    ->delay(now()->addDay());

For a single future action, this is usually exactly the right abstraction.

Even a finite sequence can be represented by dispatching several delayed jobs:

SendReminder::dispatch($account)->delay(now()->addDay());
SendReminder::dispatch($account)->delay(now()->addDays(3));
SendReminder::dispatch($account)->delay(now()->addDays(7));

Scheduled Sequences target a different case: long-lived scheduling state that belongs to an application entity.

When that state is represented entirely by delayed jobs, the application must decide how to:

• cancel already scheduled future work;
• change future execution times;
• inspect the current position;
• respond to changed application state;
• represent indefinite recurrence;
• avoid duplicating scheduling state between application data and queue data.

Another approach is for each job to schedule its successor.

That avoids creating all future jobs in advance, but the job chain then becomes the implicit representation of the schedule.

Scheduled Sequences make this state explicit, persistent, and queryable.

The distinction is therefore not:

“Can Laravel execute this action later?”

It clearly can.

The question is:

Should the queue also be the authoritative representation of a long-lived application schedule?

---

Related Laravel Discussions

I could not find an existing Laravel Framework discussion proposing the same combination of:

• persistent scheduling state;
• irregular relative offsets;
• entity-specific start times;
• conditional continuation;
• optional recurrence after a finite prefix.

There are, however, discussions demonstrating parts of the problem.

In Laravel Framework discussion #44197, a developer wanted to schedule a one-time job for a future time derived from a database value and later change that execution time when the database value changed.

The suggested solution was a delayed job.

The developer's next problem was then how to update the delay of the already stored job when application state changed.

That is a simple example of future scheduling state that belongs to application data rather than a static application-level schedule.

Scheduled Sequences address a broader version of that problem by making the scheduling state explicit rather than treating queued jobs as its canonical representation.

Other approaches and packages solve related problems such as dynamically defining application-level schedules or delaying individual actions. Those remain useful, but operate at a different level from a persistent sequence belonging to one application entity.

---

Lifecycle

The lifecycle is intentionally small:

              ┌───────────────┐
              │    Active     │
              └───────┬───────┘
                      │
                occurrence due
                      │
               shouldContinue()
                  /        \
               true        false
                │            │
             handle()     Cancelled
                │
         calculate next_at
                │
        ┌───────┴───────┐
     more work        finished
        │                 │
      Active           Completed

A Scheduled Sequence therefore has only a few core concepts:

• start;
• current / next occurrence;
• conditional continuation;
• execution;
• completion or cancellation;
• optional recurrence.

---

This Is Not a Workflow Engine

Scheduled Sequences deliberately cover a much smaller problem than a general workflow engine.

A Scheduled Sequence has no:

• arbitrary branches;
• joins;
• dependency graphs;
• human approval steps;
• arbitrary state transitions;
• orchestration between multiple workflows.

Its topology is always linear:

A → B → C → D → D → D ...

The timing between those occurrences may be irregular, and execution may stop based on current application state, but there is always only one next occurrence.

A general workflow engine might instead model:

          ┌──→ B ──→ D
A → condition
          └──→ C ──→ E ──→ approval ──→ F

That is explicitly outside the scope of this proposal.

---

Failure Semantics

Failure behavior should be explicit rather than emerging accidentally from when next_at happens to be updated.

At minimum, a Scheduled Sequence should define whether a failed occurrence should:

• retry the same occurrence;
• advance to the next occurrence;
• cancel the sequence.

A reference implementation may provide attempts and backoff.

External side effects should still use appropriate idempotency mechanisms where available.

Exactly-once execution is not a goal of this proposal.

Detailed retry ledgers, execution history, retention policies, and other operational concerns can be explored by the reference implementation without requiring them to be part of the initial abstraction.

---

Non-Goals

Scheduled Sequences are not intended to:

• replace Laravel's Scheduler;
• replace queues, chains, or batches;
• become a general workflow or BPM engine;
• model arbitrary branching graphs;
• guarantee exactly-once external side effects;
• store every future occurrence in advance.

The proposed abstraction is intentionally narrow:

An ordered temporal sequence whose scheduling state belongs to an individual application entity.

---

Reference Implementation

A working package currently implements this concept with:

• class-based sequence definitions;
• relative offsets;
• Eloquent persistence;
• polymorphic model ownership;
• next_at-based execution;
• finite sequences;
• recurrence after the final offset;
• conditional cancellation;
• stable occurrence identity;
• recoverable queue publication through a durable occurrence ledger;
• stale queued-work protection;
• explicit catch-up policies;
• retained execution state;
• per-sequence concurrency protection;
• an Artisan runner with automatic minute registration.

The reference implementation currently supports Laravel 10–13 and PHP 8.1 or newer.

The package API is still being refined and is not intended to dictate the final Laravel API.

The original production implementation used notification-specific concepts such as:

checkBeforeSend()
onExpiredOffset()

The framework-facing abstraction proposed here instead uses domain-neutral concepts such as:

shouldContinue()
handle()
Occurrence

The reference package exists primarily to validate the abstraction against real-world application workloads.

Whether this ultimately belongs in Laravel itself or remains a community package is intentionally an open question.

The goal of this proposal is first to determine whether the abstraction itself is useful and sufficiently general, rather than to propose that the current package implementation should be merged into Laravel.

---

Open Questions

1. Is ScheduledSequence an appropriate name for this concept?
2. Is persistent, entity-specific scheduling useful enough to warrant a Laravel abstraction, or is it better left to community packages?
3. Should sequence definitions remain class-based, or would a fluent API also be useful?
4. Should Eloquent ownership be part of the core abstraction or only one implementation?
5. Should offsets accept relative date strings, dedicated value objects, or both?
6. What should the default failure behavior be?
7. Should Laravel automatically register a sequence runner with the Scheduler?
8. How should timezone and daylight-saving transitions be represented for offsets containing local clock times?

The main question is:

Would Laravel benefit from a first-class abstraction for persistent irregular schedules whose timing belongs to individual application entities rather than to the application's global schedule?

The reference package is intended to help answer that question with real-world usage before any framework integration is considered.

Reference implementation

Version v0.1.0 is available on Packagist:

composer require ai-soft/laravel-scheduled-sequence

• Package: https://packagist.org/packages/ai-soft/laravel-scheduled-sequence
• Source: https://github.com/savgoran/laravel-scheduled-sequence

The package supports Laravel 10–13 and PHP 8.1 or newer. It includes durable occurrence identity, recoverable queue publication, stale-work protection, concurrency controls, explicit catch-up policies, retained execution state, and automatic minute-runner registration.

The design evolved from a predecessor used in production for two years. The implementation is an early 0.x release, and its public API may evolve before 1.0 while the abstraction continues to be validated against real application workloads.

[vynazevedo]

The most useful part of this proposal to me is having queryable scheduling state outside the queue. Before choosing between inheritance and a fluent API, I'd make the identity and completion point of an occurrence explicit.

In your queued example, handle() returns after dispatching SendAccountReminder, not after the reminder has completed. That leaves two valid but different contracts:

• The sequence owns dispatch timing: advancing means the occurrence has been durably handed off; execution retries belong to the job.
• The sequence owns action completion: the job must report completion before the sequence advances, and job failure must feed back into the sequence's retry/cancel policy.

Either can stay linear. Leaving the distinction implicit makes “retry the same occurrence” ambiguous when handle() successfully dispatched a job that later failed.

A stable occurrence identity would help both designs: for example (sequence_id, definition_version, occurrence_number), carried into the job and reused across retries. Then consider this concrete test: dispatch an occurrence, reschedule or cancel the sequence while the queue is delayed, and only then let the worker run. Checking shouldContinue() in the scheduler cannot protect that later execution by itself. The worker needs a defined stale-job policy, such as reloading the sequence and comparing the expected version/status before performing the action. External side effects still need their own idempotency handling, as you already note.

For a database-backed sequence handing work to an external queue, afterCommit() prevents a worker seeing uncommitted state, but it doesn't by itself provide a durable handoff across a process crash after commit and before publication. A transactional outbox or an equivalent recoverable dispatch record is one way to make that boundary explicit; it need not store every future occurrence.

I'd validate the reference package with three fault-injection cases: two runners claiming the same occurrence, a crash between durable state change and queue publication, and a stale queued occurrence after cancellation/rescheduling. For time semantics, specify whether downtime causes catch-up, skipping, or coalescing, and whether recurring dates are anchored to scheduled time or actual completion time.

Those contracts would give the package a concrete basis for deciding what belongs in the framework. This is design feedback on the proposal, not a claim that the reference implementation currently fails those cases.

[savgoran]

Thanks — this is exactly the kind of boundary I wanted the discussion to expose.

I agree that occurrence identity and completion semantics should be defined before settling on the public API.

My current inclination is that a Scheduled Sequence should own dispatch timing, not completion of asynchronously executed work. In other words, once an occurrence has been durably handed off, the sequence may advance; execution failures and retries remain the responsibility of the queued job. Making the sequence wait for arbitrary queued work to complete would move the abstraction much closer to a workflow/orchestration engine, which I would like to avoid.

Your stale-job example shows that shouldContinue() at scheduling time is not sufficient, though. I like the idea of giving every occurrence a stable identity such as (sequence_id, definition_version, occurrence_number) and propagating that identity into dispatched work. A queued handler could then reload the sequence before performing the side effect and reject work belonging to a cancelled or superseded sequence version. The same identity could also provide a natural idempotency key where the external integration supports one.

The crash between committing sequence state and publishing the queued job is another important boundary. afterCommit() does not close that gap. I don't think a transactional outbox necessarily has to be part of the minimal Scheduled Sequence abstraction, but the contract should acknowledge the handoff problem, and the reference implementation should have a recoverable strategy if it claims durable dispatch.

I also agree with making downtime behavior explicit. The current reference implementation already skips missed recurring intervals and calculates the first future recurrence rather than replaying every missed interval, but that is currently an implementation detail. It should become a documented policy, along with whether recurrence is anchored to the scheduled occurrence or actual completion time.

The three fault-injection cases you suggested are excellent acceptance tests:

1. two runners claiming the same occurrence;
2. a crash between durable state change and queue publication;
3. a queued occurrence executing after the sequence has been cancelled or rescheduled.

I'll incorporate these contracts into the full RFC/reference implementation. This also reinforces for me that occurrence identity should probably be designed before choosing between inheritance and a fluent API.

Thanks for the detailed feedback.

[savgoran]

I've also published the reference implementation and turned the reliability scenarios you raised into concrete design issues. Further feedback and PRs are very welcome.

[vynazevedo]

@savgoran Thanks for publishing it. I checked the design issues, including #7, which now separates the contracts you report as covered from the remaining process/database tests. That makes the next validation step much clearer.

For the real-process crash test, I'd distinguish two cut points:

1. The occurrence is committed, but publication has not happened. Recovery should eventually publish that same occurrence identity.
2. The queue has accepted the message, but the publisher dies before recording that success. Recovery may publish it again, so the consumer must handle duplicate delivery for the same identity.

The second case is easy to miss if the test only crashes before publication. For both, assert eventual progress as well as the absence of unintended duplicate effects: “executed at most once” alone also passes when nothing executes.

I'd also scope that assertion to the boundary the package controls. A database execution ledger cannot by itself make an external effect exactly-once if the worker dies after the remote system accepts it but before local completion is recorded. An idempotent downstream test double, receiving the occurrence key on every retry, can verify the propagation guarantee without claiming atomicity across the database and an external service.

For the two-runner test, a barrier before claiming the same due occurrence would make the race reproducible, rather than depending on two processes starting at roughly the same time. This is feedback on the issue's acceptance criteria; I haven't run the package's new implementation or its database tests.

[savgoran]

Thanks — agreed on both crash cut points.

The current #7 wording only covers the first boundary: committed occurrence state with publication still pending. You're right that the opposite side is equally important: the queue may already have accepted the message while the publisher dies before recording that fact, so recovery must be allowed to publish the same occurrence identity again.

I'll split that test into those two explicit fault-injection cases and assert eventual progress in both, not only “at most once”. As you point out, zero executions would otherwise satisfy the latter assertion.

I also agree that the guarantee needs to stop at the boundary the package controls. The package can provide a stable occurrence identity, deduplicate/guard its own execution state, and propagate that identity downstream. It cannot claim exactly-once atomicity with an external system if the worker can fail after the external side effect succeeds but before local completion is recorded.

Using an idempotent downstream test double keyed by the occurrence identity sounds like the right way to test that contract without overstating the guarantee.

And yes, I'll make the competing-runner test deterministic with a barrier immediately before the claim so both processes race on the same due occurrence rather than relying on process startup timing.

Thanks again — these are good acceptance-criteria improvements, and I'll reflect them in #7 and the reliability section of the RFC.

[shaedrich]

The naming could be confusing. I would probably rename $repeatEvery to $repeatEveryAfterwards or $repeatAfterwardsEvery or $afterwardsRepeatEvery

[savgoran]

Good point. $repeatEvery doesn't make it clear that the recurrence only starts after the configured offsets have been exhausted.
I've renamed it to $repeatEveryAfterwards to make that distinction explicit. Thanks!

[savgoran]

Update — v0.1.0 released

The reference implementation is now available on Packagist:

composer require ai-soft/laravel-scheduled-sequence

Version v0.1.0 supports Laravel 10–13 and PHP 8.1+. It includes stable occurrence identity, recoverable queue publication through a durable occurrence ledger, stale-work protection, per-sequence concurrency controls, explicit catch-up policies, retained execution state, and automatic minute-runner registration.

The reliability test task discussed above is now closed after the GitHub Actions matrix passed. The package remains an early 0.x release, so its public API may evolve before 1.0.

Package: https://packagist.org/packages/ai-soft/laravel-scheduled-sequence
Source: https://github.com/savgoran/laravel-scheduled-sequence