Download the PHP package padosoft/laravel-routines without Composer

The 3am problem

A routine is an automation that runs when the user is not there. That is its entire value, and its entire problem.

The rest of the Padosoft ecosystem rests on one invariant: an agent proposes, the user confirms on screen, per action. It is the rule that makes delegation safe (MOBILE-SEC-LLM-001 §6, laravel-iam-agents). But a routine scheduled for 3am has nobody to ask. Existing automation resolves the contradiction in one of the two worst ways:

Neither is an answer. This package gives a third one.

The standing mandate, and the pause

A routine carries a mandate: a consent that is standing but narrower than the interactive one, bound to (target, action classes, spend ceiling, time window) and tied cryptographically to the canonical digest of the approved payload.

While the routine stays inside its mandate, it runs alone. When it exceeds it — a €1,200 order when the mandate covers 500 — it neither fails nor proceeds: it goes paused, and the approval request goes out to a human on a real channel (laravel-rebel-channels: Telegram, WhatsApp, SMS, voice). The person answers, and the fire resumes where it stopped, not from the beginning.

That the last line is the default behaviour is the whole point: the safe failure is stopping, not "going ahead because it was almost within the limits anyway".

What it does, briefly

• Triggers: cron (in the owner's timezone), one-shot, manual, application event, signed webhook.
• Extensible targets: the core does not know what it launches. A job, a flow, an agent, a query — whoever owns the domain registers a RoutineTarget from their own provider, and the core does not change by a line.
• Execution guarantees: locks with a TTL, idempotency enforced by the database, capped catch-up of missed occurrences, exponential backoff, overlap policies.
• Daylight saving handled for real — in both directions, and pinned by tests (see below).
• Fire ledger: every execution is an immutable fact with outcome, cost, duration, reason and idempotency key. It is evidence, not a log.
• Delegated identity (phase 2): the routine runs as the user, through the agent — sub + act — with authority that is the strict intersection of the two, re-evaluated on every fire.

Installation

The tick registers itself with Laravel's scheduler (routines.tick.schedule). All you need is the scheduler running:

Five minutes

1. Write a target

Register it from your service provider:

2. Create the routine

The payload is validated now, while there is a human in front of the form. A broken payload discovered on the first 3am fire is a silent failure inside a log nobody reads.

The other ways to fire a routine

Cron is the most common one, not the only one. Each of the others carries a question that has to be decided once, and well: when are two arrivals the same fact, and when are they two facts.

On an application event

Every emission gets a fresh key by default. Deduplicating two OrderPlaced would be worse than running them twice: it would mean not shipping an order. If your event can arrive twice for the same fact — an at-least-once delivery from a queue — expose idempotencyKey(): string on the event and deduplication happens. The sender is the one who knows: there is no way to guess it here.

From the event object, only scalars are passed through. The input goes into the ledger, and a whole model would drag relations along with it, and sometimes data that must not leave. Need more? Expose toRoutineInput(): array and decide yourself what goes out.

From a signed webhook

The sender signs with HMAC-SHA256 and calls POST /hooks/routines/{id}:

The route sits outside the session guard: a machine calls it, and a machine has no cookie and no CSRF token, and must not need one. The signature is the only authentication, so every detail of the verification is a defence whose failure would be silent:

A paused routine answers 409 instead, not 403: the signature was right, and the caller must be able to tell "you are not authorized" from "it is stopped".

The secret is encrypted at rest, not hashed — verifying an HMAC needs the real secret at comparison time, so the most that can be achieved is that a database dump does not hand it over.

Spend ceilings

Scopes limit what a routine may do; the ceiling limits how much. It is the second defence, and it is the one missing everywhere: a routine perfectly authorized to "send email", called a thousand times by a runaway loop, has violated no permission — it has just sent a thousand emails.

The ceiling is checked before and after every fire: before alone is not enough (the first overrun comes from a fire that was still inside beforehand), after alone discovers the overrun once the money is already spent. On an exhausted ceiling the routine suspends rather than skipping: skipping would mean meeting the same exceeded ceiling every hour for the rest of the month.

The period is computed in the owner's timezone — "this month" for someone living in Rome starts two hours before it does in Greenwich — and the message says when it resumes, because without that the only action left to the reader is to raise the ceiling, which is often not the right thing to do.

The decisions that matter

A scheduling package is judged on five edge cases. All five are pinned by tests.

A missed tick does not lose an execution

The dispatcher asks "what is due" (next_run_at <= now), never "which cron matches this minute". A six-minute deploy does not make the 6:03 occurrence disappear: it is found on the next tick. Anything that computes from the tick loses executions silently — the worst way to lose them.

Two workers produce one fire, not two

The lock is a conditional UPDATE — the arbiter is the database, not an if. And the unique on (routine_id, idempotency_key, attempt) also closes the race the lock did not see: the second insert fails and that tick withdraws quietly. It is a schema guarantee, not a code one.

The lock has a TTL, and it exists for the case nobody considers: the worker that dies holding the lock. Without a TTL that routine stays stopped forever, and there is no error anywhere.

Daylight saving has two traps, and they are different from each other

Almost every scheduler handles one and ignores the other.

It happens twice a year and nobody remembers it: which is why both cases are pinned by tests that fail if the guard is removed.

A downtime does not become a swarm

A routine running every 5 minutes, stopped for a day, has 288 occurrences behind it, and catching up on all of them means sending 288 emails in thirty seconds. Catch-up has a cap (catch_up_cap), and the policy is an explicit field because it is a domain decision: a daily report is worth catching up on, a 9am reminder delivered at 2pm is just noise (skip_to_next).

Paused is neither success nor failure

TargetOutcome has four cases and not three. Without the fourth, whoever implements a target is forced to choose between proceeding without permission and failing silently. Neither is what should happen when an automation meets something its mandate does not cover.

Comparison

The first five rows are scheduling hygiene: get them wrong and you lose or duplicate executions. The middle rows nobody else has, and not by oversight: they require an IAM with delegation (laravel-iam-agents), a step-up with dynamic linking (laravel-rebel-step-up), a channel layer (laravel-rebel-channels) and a FinOps ledger (laravel-ai-finops) — an ecosystem, that is, not a feature.

Two deserve a line of their own, because they describe failures the other systems cannot even see:

• Unanswered questions. A routine that paused to ask and that nobody answered is the worst failure in the system, and it is invisible by construction: the routine is doing exactly what it should — it does not act without permission — so it produces no error, in no log, for no monitor. laravel-rebel-ai-guard detects it as routine_approval_starvation, carrying the oldest question verbatim in the case, and can suspend the routine so it stops accumulating more.
• The target contract shipped as tests. The target is written by whoever installs the package, and no engine guarantee covers it. Testing\TargetContract makes the four rules that keep it safe executable (see Tests).

Honesty about status. Everything above is implemented and covered by tests, with one clarification: delegated identity and multi-channel escalation are seams — the package defines the contracts (RoutineDelegationBroker, RoutineEscalator), calls them at the right points and ships defaults that fail safe; the concrete implementations come from laravel-iam-agents and laravel-rebel-channels. Without those packages the routine runs as the application, and the question lands in the log at warning level instead of on Telegram.

Architecture

Three packages, one clean boundary:

The panel

padosoft/laravel-routines-admin is the reference consumer of the Admin API, but not a privileged one: everything it does goes through the same HTTP endpoints available to anything else. If the panel is replaced tomorrow the API stays, and with it every integration built on top. It is the same separation laravel-iam-console has from laravel-iam-server.

The screen the product is named for is this one: the routines that stopped because they met something their mandate does not cover. They are not failures — they are doing exactly what they were written to do — and that is precisely why they appear in no error log and trip no monitor. The only place they show up is a queue somebody looks at.

The panel also adapts to a phone, which is where "a routine is waiting for you" tends to be read — away from a desk.

Configuration

Why the job allow-list is not a precaution

A routine's payload is data: it comes from a form, it can come from an import, and in phase 3 it can come from an assistant that proposed it. Instantiating whatever class is found inside would give that data the right to execute anything that exists in the application. That is why schedulable jobs are declared, and why the allow-list is re-checked at fire time too: a routine created when a job was permitted must not keep running after it has been removed.

Commands

Events

Ecosystem integration

None of them is required: with nothing installed, the package is a scheduler that neither loses nor duplicates executions.

Tests

The tests do not cover the happy path — they cover the cases that break real schedulers: two concurrent workers, a dead worker's lock, both directions of daylight saving, a six-hour downtime, an uninstalled target, an unexpected exception, a webhook delivered twice.

Your target's contract, in executable form

The tests above prove the engine keeps its guarantees. The target is yours to write, and the rules that keep it safe would otherwise live only in this README's prose. The package ships the executable version of them:

Four assertions, and each one matches a way of failing silently:

Every assertion in the kit has, in this package's own suite, a test that watches it fail against a target that violates it: a kit that passes on anything proves nothing.

License

MIT © Padosoft