DEV Community: Steve McDougall

Sending And Receiving Webhooks In Laravel

Steve McDougall — Tue, 06 Oct 2026 19:23:52 +0000

A customer deploys their app at 14:00. Their webhook endpoint is down for four minutes while it happens. Your app sends them invoice.paid at 14:01, gets a 502, waits ten seconds, gets another, waits a hundred, gets a third, and gives up. Their invoice stays unpaid in their system. Nothing anywhere says so.

Both sides did what their code told them to. The sender retried three times, which sounds generous until you notice it spent less than two minutes doing it. The receiver went down for a deploy, which every receiver does. Neither half was written with the other in mind. That is how most webhook code in Laravel apps gets written: one end at a time, by people who will never read the other end.

A webhook is a contract between two codebases that never meet, so start with the contract.

Agree on the contract before writing either end

Three things have to be true of every delivery, whoever sends it:

It carries an identifier that stays the same across retries, so the receiver can tell a retry from a new event.
It carries a timestamp, and the signature covers it, so a request captured today cannot be replayed next week.
The signature is computed over the exact bytes of the body, so nothing has to agree on how JSON is formatted.

You can invent headers for that, and most providers did. I would rather use Standard Webhooks, a spec written by people who run webhook infrastructure, because it is small and it already says all three. It also means the receiver may have done this before.

POST /webhooks/billing HTTP/1.1
Content-Type: application/json
webhook-id: msg_01J9Z3K4M5N6P7Q8R9S0T1V2W3
webhook-timestamp: 1791295260
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"invoice.paid","timestamp":"2026-10-06T14:01:00Z","data":{"id":"inv_8842"}}

The signature is HMAC-SHA256 over {id}.{timestamp}.{body}, base64 encoded, prefixed with a version. The secret is 32 random bytes, base64 encoded with a whsec_ prefix so it is recognisable when it leaks into a log. That is the whole format.

Sending

Record the event with the change that caused it

The event has to exist if and only if the change happened. Write it in the same transaction:

DB::transaction(function () use ($invoice): void {
    $invoice->markAsPaid();

    WebhookEvent::record('invoice.paid', ['id' => $invoice->public_id]);
});

final class WebhookEvent extends Model
{
    public $incrementing = false;

    protected $keyType = 'string';

    public static function record(string $type, array $data): self
    {
        $event = self::create([
            'id' => 'msg_' . Str::ulid(),
            'type' => $type,
            'payload' => json_encode([
                'type' => $type,
                'timestamp' => now()->toIso8601ZuluString(),
                'data' => $data,
            ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES),
        ]);

        WebhookEndpoint::subscribedTo($type)->each(
            fn (WebhookEndpoint $endpoint) => DeliverWebhook::dispatch($endpoint, $event)->afterCommit(),
        );

        return $event;
    }
}

The payload is encoded once and stored as a string. Make that column text, not json. Postgres jsonb and MySQL's JSON type both normalise what they store, reordering keys and rewriting whitespace, and the signature has to cover exactly the bytes you send. Encoding once also means every retry sends the same bytes, which the receiver can rely on.

afterCommit() stops a job being dispatched for a transaction that rolls back. It does not cover the process dying between the commit and the dispatch. That window is small, and if the event matters enough that you cannot lose one, closing it is what the transactional outbox is for.

The delivery job

One job per endpoint per event:

#[Tries(10)]
#[Timeout(30)]
final class DeliverWebhook implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public WebhookEndpoint $endpoint,
        public WebhookEvent $event,
    ) {}

    /** @return list<int> */
    public function backoff(): array
    {
        // The Standard Webhooks example schedule: about three days, front-loaded.
        $schedule = [5, 300, 1800, 7200, 18000, 36000, 50400, 72000, 86400];

        return array_map(
            fn (int $seconds): int => $seconds + random_int(0, intdiv($seconds, 10)),
            $schedule,
        );
    }

    public function handle(): void
    {
        if ($this->endpoint->disabled_at !== null) {
            return;
        }

        $timestamp = now()->getTimestamp();

        $response = Http::timeout(15)
            ->withoutRedirecting()
            ->withBody($this->event->payload, 'application/json')
            ->withHeaders([
                'webhook-id' => $this->event->id,
                'webhook-timestamp' => (string) $timestamp,
                'webhook-signature' => $this->endpoint->sign($this->event->id, $timestamp, $this->event->payload),
            ])
            ->post($this->endpoint->url);

        if ($response->successful()) {
            return;
        }

        if ($response->status() === 410) {
            $this->endpoint->disable(reason: 'The endpoint returned 410 Gone');

            return;
        }

        $retryAfter = $response->header('Retry-After');

        if (ctype_digit($retryAfter)) {
            $this->release(min((int) $retryAfter, 3600));

            return;
        }

        throw new RuntimeException("Webhook endpoint {$this->endpoint->id} returned {$response->status()}");
    }

    public function failed(?Throwable $exception): void
    {
        $this->endpoint->recordFailure($this->event, $exception);
    }
}

Most of that reads as it looks. These are the lines that do not.

The timestamp and signature are made inside handle(), on every attempt. The receiver rejects anything older than about five minutes, and the eighth attempt happens more than a day after the first. A signature computed once at dispatch would be stale for every retry that matters.

Ten tries over three days is what the opening needed. Three tries in two minutes covers a blip. It does not cover a bad release that takes an hour to roll back, or an expired certificate nobody notices until Monday. The jitter stops every delivery that failed during the same outage from retrying in the same second and knocking the endpoint over again as it comes back. backoff() is evaluated once, when the job is dispatched, so each job gets its own jitter and keeps it.

withoutRedirecting(), because Laravel's HTTP client follows redirects by default. A webhook URL that redirects is misconfigured, and following it means POSTing your signed payload to somewhere the customer did not register. A 3xx counts as a failure, and the customer can fix their URL.

A 410 means stop, not retry: the receiver is telling you the endpoint is gone on purpose. Retry-After is honoured, capped at an hour, because a 429 or 503 that tells you when to come back is more accurate than any schedule you guessed. The cap is there so a receiver cannot park a job for a month. This handles the seconds form of the header; it can also be an HTTP date, which is worth parsing if your receivers send it.

Check your queue driver before copying the schedule. On SQS, Laravel delays a retry by changing the message's visibility timeout, and AWS caps that at twelve hours. The last three entries are fourteen, twenty and twenty-four hours, so either cap them or run this queue on the database or Redis driver.

Signing is a method on the endpoint, because the secret lives there:

final class WebhookEndpoint extends Model
{
    protected function casts(): array
    {
        return [
            'secrets' => 'encrypted:array',
            'disabled_at' => 'datetime',
        ];
    }

    public function sign(string $id, int $timestamp, string $body): string
    {
        return collect($this->secrets)
            ->map(fn (string $secret): string => 'v1,' . base64_encode(hash_hmac(
                'sha256',
                "{$id}.{$timestamp}.{$body}",
                base64_decode(Str::after($secret, 'whsec_')),
                binary: true,
            )))
            ->implode(' ');
    }
}

secrets is a list rather than a single value. That is the whole of secret rotation. When a customer rotates, put the new secret first and keep the old one for a day. Every delivery carries both signatures, space separated, and the receiver accepts the delivery if either one matches. They can switch over whenever they like, inside that day, without a window where deliveries fail.

failed() runs when the tenth attempt fails. Make it do something a person will see. Retries that end in a row nobody reads still lose the customer's event. They just take three days to do it. Email the customer, and disable the endpoint after enough consecutive failures, so you stop paying to retry a URL that is never coming back.

Receiving

The receiving end has one job before anything else: decide whether this request came from who it claims to.

Verify the bytes you were sent

final readonly class VerifyWebhookSignature
{
    private const int TOLERANCE_SECONDS = 300;

    public function handle(Request $request, Closure $next): Response
    {
        $id = (string) $request->header('webhook-id');
        $timestamp = (string) $request->header('webhook-timestamp');

        if ($id === '' || ! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > self::TOLERANCE_SECONDS) {
            return response()->noContent(400);
        }

        $secret = base64_decode(Str::after(config('services.billing.webhook_secret'), 'whsec_'));

        $expected = base64_encode(hash_hmac(
            'sha256',
            "{$id}.{$timestamp}.{$request->getContent()}",
            $secret,
            binary: true,
        ));

        foreach (explode(' ', (string) $request->header('webhook-signature')) as $signature) {
            [$version, $value] = array_pad(explode(',', $signature, 2), 2, '');

            if ($version === 'v1' && hash_equals($expected, $value)) {
                return $next($request);
            }
        }

        return response()->noContent(400);
    }
}

$request->getContent() is the raw body. Anything else, $request->all() re-encoded or a form request's validated array, is a different string from the one that was signed. Verification then fails sometimes rather than always. That is the worst way for it to fail. hash_equals() compares in constant time, so response timing does not tell an attacker how much of their guess was right.

The timestamp check runs first because it is cheap, and it is what makes a captured request useless five minutes later. Looping over the signatures is the receiving half of rotation.

There is an official PHP library for this if you would rather not own twenty lines of crypto. If you use it, pass it the three headers as strings. Laravel's $request->headers->all() gives you each header as an array, and the library does not reject that. It reads it as a timestamp of 1 and fails every delivery with "Message timestamp too old", which sends you off checking your server's clock.

Exempt the route from CSRF in bootstrap/app.php, since there is no session to have a token:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->validateCsrfTokens(except: ['webhooks/*']);
})

Acknowledge, then work

Once the signature checks out, store the raw body and the webhook-id, dispatch a job, and return 202. The sender is waiting with a fifteen second timeout. To them a slow response looks exactly like a failure, so a handler that does the work inline earns retries it did not need. I have written up this half in more depth in receiving webhooks in Laravel, including why you keep the raw payload and the Cashier event that fires before Cashier has written anything.

Do the work once

The sender has just promised to retry for three days. Expect duplicates. Every timeout where the receiver finished but the response never arrived produces one.

The check that looks right is select-then-insert, and it has a gap between the two in which two deliveries of the same event both find nothing. Close it with the database instead, in the same transaction as the work:

final class ProcessBillingWebhook implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public ReceivedWebhook $webhook,
    ) {}

    public function handle(): void
    {
        DB::transaction(function (): void {
            $claimed = DB::table('processed_webhooks')->insertOrIgnore([
                'webhook_id' => $this->webhook->webhook_id,
                'processed_at' => now(),
            ]);

            if ($claimed === 0) {
                return;
            }

            $event = json_decode($this->webhook->payload, true, flags: JSON_THROW_ON_ERROR);

            match ($event['type']) {
                'invoice.paid' => $this->invoicePaid($event),
                default => null,
            };
        });
    }
}

insertOrIgnore() against a unique index on webhook_id returns 0 when the row already exists. When two deliveries race, the second insert waits for the first transaction to commit and then gets its 0. The claim and the work commit together. A crash halfway through rolls back both, so the retry gets a clean run instead of a claim for work that never happened.

That holds while the work is database writes. If it calls out to something else, you are back to the dual write problem, and the idempotent receiver goes through what changes.

Deliveries also arrive out of order, because retries reorder them by design. The payload's timestamp is when the event happened, not when it was sent. If you store it next to whatever it updates, a subscription.updated older than the one you already applied can be dropped instead of undoing the newer one.

The test that makes both ends agree

When the same app sends and receives, or you own both services, this is the test I would write first. It puts what the sender sends through what the receiver checks:

it('signs deliveries the receiver accepts', function () {
    Queue::fake();
    Http::fake(['*' => Http::response(status: 204)]);

    $endpoint = WebhookEndpoint::factory()->create([
        'secrets' => [config('services.billing.webhook_secret')],
    ]);

    $event = WebhookEvent::record('invoice.paid', ['id' => 'inv_8842']);

    (new DeliverWebhook($endpoint, $event))->handle();

    [$sent] = Http::recorded()->first();

    $this->call('POST', '/webhooks/billing', server: [
        'HTTP_WEBHOOK_ID' => $sent->header('webhook-id')[0],
        'HTTP_WEBHOOK_TIMESTAMP' => $sent->header('webhook-timestamp')[0],
        'HTTP_WEBHOOK_SIGNATURE' => $sent->header('webhook-signature')[0],
        'CONTENT_TYPE' => 'application/json',
    ], content: $sent->body())->assertAccepted();
});

Whatever the sender produced goes through the receiver's middleware unchanged, headers and bytes. It fails the day someone changes the signing string on one side and not the other, or adds a pretty-print flag to the encoder, or "tidies" the receiver into reading $request->all(). Each of those passes every test that only looks at one end.

Where the packages fit

Spatie's laravel-webhook-server and laravel-webhook-client are what most Laravel apps reach for, and they agree with each other out of the box. Know their defaults before you send to anyone else, though. The server makes three attempts, with a three second timeout, waiting ten seconds and then a hundred: the two minutes from the opening. The signature covers the JSON body and nothing else. There is an optional timestamp header, but it is not signed, so it does not stop a replay. Between two services you own, that is a fine trade. Sending to customers' endpoints, it is not, and changing it means replacing the signer and the job, at which point the package is not doing much.

What it costs

A delivery job can now sit in your queue for three days. An outage at a large customer leaves thousands of them waiting at once. Give webhook delivery its own queue, so a backlog there never delays the jobs your own users are waiting on.

You also keep every event's payload for at least as long as you retry it. That is a table that only grows, so decide when rows get pruned before it is the biggest table you have.

What to do on Monday

Find where your app sends webhooks, and work out what its retry schedule adds up to. If the last attempt happens less than an hour after the first, a customer's ordinary deploy is already losing them events.

Then find the receiving end of something you integrate with and look for the line that checks whether this event has been processed before. If it is a SELECT followed by an INSERT, or there is no such line, that is the next thing to fix.

Strangling Procedural Legacy PHP into Laravel

Steve McDougall — Tue, 06 Oct 2026 19:23:50 +0000

The big bang rewrite is the most confident decision an engineering team can make and one of the worst. The pitch is always reasonable. The current system is slow to change, everybody agrees it is slow to change, so we pause feature work, rebuild it properly, and come back in six months with something maintainable. What actually happens is that month four arrives, the business needs a feature the old system can still deliver and the new one cannot, and the rewrite is either shipped half finished or quietly abandoned. Now you have two systems to maintain instead of one.

That risk goes up when the thing you are replacing is not on an older framework. Migrating Symfony 2 to Laravel is unpleasant but legible. There are controllers, there is routing, there is a service container, and you can map concepts across. A procedural monolith gives you none of that. You get global state read straight out of $_GET and $_POST, mysqli_query calls interleaved with HTML, header('Location: ...') scattered through business logic, and includes that pull in half the application as a side effect. There is no seam to grab hold of, which is exactly why people conclude the only option is to start again.

There is another option. Put Laravel in front of the old application, migrate one route at a time, and let the procedural code carry on serving everything you have not reached yet. This is the strangler fig pattern, named after the vine that grows around a host tree, gradually takes over its structural role, and leaves a hollow shell behind. The important detail is that at no point during that process is the tree unable to stand.

Laravel as the front door

The first move is deciding who owns the incoming request. It has to be Laravel, and it has to be Laravel from day one, even when Laravel is handling exactly zero routes.

The web server serves Laravel's public directory as the document root. Anything Laravel does not recognise falls through to the legacy entry point. As you migrate an endpoint, it stops falling through, and nothing about the client's URL changes.

Request
   |
   v
Nginx  ->  Laravel public/index.php
                |
                +-- route matched?  yes  ->  Laravel handles it
                |
                +-- no  ->  fallback to legacy/index.php

In Nginx that looks roughly like this:

server {
    listen 80;
    server_name my-app.test;
    root /var/www/my-app/laravel/public;

    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location /legacy/ {
        root /var/www/my-app;
        try_files $uri $uri/ @legacy;

        location ~ ^/legacy/.+\.php$ {
            root /var/www/my-app;
            try_files $fastcgi_script_name =404;

            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        }
    }

    location @legacy {
        rewrite ^/legacy/(.*)$ /legacy/index.php?page=$1 last;
    }

    location ~ ^/index\.php(/|$) {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    }
}

Two details in there are worth calling out, because both of them have cost me time.

The first is that the legacy block uses root rather than alias. Reaching for alias is the obvious move when you are mapping a URL prefix onto a directory that sits outside your document root, and it does not work with try_files. This is nginx ticket 97, open since 2010. The value of $uri is not rewritten by alias, so try_files $uri re-appends the location prefix and goes looking for /var/www/my-app/legacy/legacy/whatever. It fails, silently, in a way that looks like the fallback is broken rather than the path. If you can arrange your directories so the legacy application sits under a shared parent, root sidesteps the whole thing. If you cannot, use a regex location with a capture and build the path yourself rather than relying on $uri.

The second is try_files $fastcgi_script_name =404 in the PHP block, and the narrowed ^/index\.php(/|$) pattern on the Laravel side. A bare location ~ \.php$ that passes anything ending in .php to FPM is the configuration behind a long history of remote code execution reports, because a request for /uploads/avatar.jpg/x.php can end up executing an uploaded file. Legacy applications tend to have upload directories inside the web root, which is exactly the situation where this matters.

The alternative approach, and the one I reach for when the legacy URL structure is chaotic enough that server config becomes unreadable, is to do the fallback inside Laravel itself using a catch all route that proxies to the old application. It is slower, because every legacy request now boots the framework before being handed off, but it puts the routing table in version control where you can read it, test it, and log it. On a system with meaningful traffic that trade is usually worth making for the first few months and worth reversing later.

Either way, the property you want is the same. There is one place that decides where a request goes, and migrating an endpoint is a one line change in that place.

The part that actually blocks people: sessions

Routing is straightforward. Authentication is where these migrations stall.

Procedural applications call session_start() and write to $_SESSION['user_id']. Laravel has its own session handling, its own cookie, its own encryption, and its own idea of what an authenticated user is. If you do nothing, a user who logs in through the old system hits a migrated Laravel route and gets bounced to a login form. Twice logged in is not a migration, it is an outage with extra steps.

The advice you will find most often is to make both applications share a session store. I want to talk you out of it, because it is harder than it sounds and the reason is not obvious.

PHP does not ship a database session handler. The values session.save_handler accepts are files, redis, memcached, and user, and user means you write a class implementing SessionHandlerInterface and register it with session_set_save_handler(). So step one is already a bespoke class in the codebase you were hoping not to touch.

Step two is worse. Laravel's database session driver does not store a native PHP session blob. It stores base64_encode(serialize($attributes)) in a payload column, alongside id, user_id, ip_address, user_agent, and last_activity. And Laravel does not consider you logged in because a user_id exists somewhere in that payload. SessionGuard looks for a key named login_ plus the guard name plus a SHA1 of the guard class, which for the default web guard is a string like login_web_59ba36addc2b2f9401580f014c7f58ea4e30989d. For your legacy handler to produce a session Laravel accepts, it has to reproduce that format and that key exactly. It can be done. It is not the small mechanical change it appears to be, and it couples the old application to Laravel internals that are not part of the public API.

So there are really two honest options.

The first, and the one I now reach for by default, is to invert the problem. Make authentication the very first thing you migrate. Laravel owns login, logout, and the session, and the legacy application is changed to read whatever Laravel writes. That is a smaller change to the old codebase than a custom save handler, because a procedural app checking $_SESSION['user_id'] can be pointed at a single shared function that reads Laravel's session or a signed cookie instead. You do the awkward work once, at the start, and every subsequent migration inherits a working auth context.

The second, for when login genuinely cannot move yet, is to read the legacy session yourself in middleware:

namespace App\Http\Middleware;

use App\Models\User;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\DB;
use Symfony\Component\HttpFoundation\Response;

final class BridgeLegacySession
{
    public function handle(Request $request, Closure $next): Response
    {
        if (Auth::check()) {
            return $next($request);
        }

        $cookie = config('legacy.session_cookie', 'PHPSESSID');

        if (! $request->hasCookie($cookie)) {
            return $next($request);
        }

        $session = DB::connection('legacy')
            ->table('sessions')
            ->where('id', $request->cookie($cookie))
            ->first();

        if (! $session) {
            return $next($request);
        }

        $userId = $this->extractUserId($session->data);

        if ($userId && $user = User::find($userId)) {
            Auth::login($user);
        }

        return $next($request);
    }

    private function extractUserId(string $data): ?int
    {
        $vars = [];
        $offset = 0;

        while ($offset < strlen($data)) {
            $delimiter = strpos($data, '|', $offset);

            if ($delimiter === false) {
                break;
            }

            $name = substr($data, $offset, $delimiter - $offset);
            $offset = $delimiter + 1;

            $value = unserialize(substr($data, $offset));

            $vars[$name] = $value;
            $offset += strlen(serialize($value));
        }

        return $vars['user_id'] ?? null;
    }
}

That parser exists because PHP's default session serialisation format is not the same as serialize() output. It is a sequence of name|serialized_value pairs, and crucially the name carries no length prefix, which is why you cannot hand the whole thing to unserialize() and have to walk it byte by byte instead.

Be clear about where this is fragile, because the obvious guess is wrong. A pipe character inside a session value is fine, since values are properly serialised and the loop advances by strlen(serialize($value)) rather than searching for the next delimiter. What breaks it is a pipe character in a session key, which is legal and which nothing in the old codebase is stopping anyone from writing. The other soft spot is calling unserialize() on a substring that has trailing data after the value you want. That works, but how loudly PHP complains about it has changed across versions, so check the behaviour on the version you are actually deploying rather than trusting mine or anyone else's.

There is a third failure mode with no workaround: if the session stores a serialised object whose class does not exist inside your Laravel application, unserialize() hands you a __PHP_Incomplete_Class and anything downstream that touches it throws.

So write this if you must, wrap the unserialize() call in error handling, log every failure loudly with the session id, and treat it as a temporary bridge you intend to delete rather than infrastructure you intend to keep. Register it in bootstrap/app.php on the web group and every migrated route gets a populated $request->user() for free.

Also set session.serialize_handler explicitly in the legacy application rather than assuming it. The default is php, which is what the parser above expects, but a codebase old enough to need this migration is old enough for someone to have changed it to php_binary for reasons nobody remembers.

Pointing Eloquent at a schema you did not design

Procedural codebases have their own naming conventions, and those conventions are usually somebody's personal system from 2011. Tables prefixed tbl_, primary keys called usr_id_pk, timestamps stored as unix integers in a column named dt_created, and a deleted flag that is sometimes 0 and sometimes NULL depending on which script wrote the row.

The instinct is to fix the schema first. Do not. Schema migration is the last thing you do, not the first, because for the entire migration period both applications are reading and writing the same tables. Eloquent is perfectly happy to be told what the columns are called:

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;

final class User extends Authenticatable
{
    protected $connection = 'legacy';

    protected $table = 'tbl_users';

    protected $primaryKey = 'usr_id_pk';

    public const CREATED_AT = 'usr_created_dt';

    public const UPDATED_AT = 'usr_updated_dt';

    protected $fillable = [
        'usr_email',
        'usr_password',
        'usr_name',
    ];

    protected function casts(): array
    {
        return [
            'usr_created_dt' => 'timestamp',
            'usr_updated_dt' => 'timestamp',
        ];
    }

    public function getAuthPassword(): string
    {
        return $this->attributes['usr_password'];
    }
}

The casts are not optional decoration. Naming the columns through CREATED_AT and UPDATED_AT tells Eloquent which columns to touch on write, but it does not tell it how to read them. If the legacy application stores unix integers rather than a datetime type, you need the timestamp cast or every date comparison you write will be doing string maths against an integer and quietly producing nonsense.

Two other things to check on a legacy table. If the primary key is a string or a UUID stored as a char column, set $incrementing to false and $keyType to 'string', because Eloquent assumes an auto incrementing integer and will cast your key out from under you. And if the table has no timestamp columns at all, which is common on lookup and join tables, set $timestamps to false or every write will fail on a column that does not exist.

You can go further and hide the naming entirely behind accessors, so the rest of your Laravel code never learns that usr_email exists:

use Illuminate\Database\Eloquent\Casts\Attribute;

protected function email(): Attribute
{
    return Attribute::make(
        get: fn (): string => $this->usr_email,
    );
}

That is worth doing for the columns you touch most, because it means the day you finally rename the underlying column, you change one accessor rather than three hundred call sites. The model becomes a translation layer between the schema you inherited and the domain language you actually want.

One caveat on passwords, and it is not solved by getAuthPassword() alone. Legacy applications hash with whatever was fashionable at the time, and that is frequently MD5 or an unsalted SHA1. Laravel's Hash::check() will not return false against those, it will fail outright, because it is handing a bcrypt hash string to password_verify(). You need to detect the legacy format and compare it yourself:

if (str_starts_with($user->getAuthPassword(), '$2y$')) {
    $valid = Hash::check($plain, $user->getAuthPassword());
} else {
    $valid = hash_equals($user->getAuthPassword(), md5($plain));
}

if ($valid && Hash::needsRehash($user->getAuthPassword())) {
    $user->forceFill([
        'usr_password' => Hash::make($plain),
    ])->save();
}

Use hash_equals() rather than a plain comparison so you are not leaking timing information, and rehash on every successful login so users migrate to bcrypt transparently as they come back. After a few months the legacy branch covers almost nobody, and you can force a reset for the stragglers and delete it. Do note that this rewrites the password column that the old application is still reading, so the legacy login code has to understand bcrypt before you turn this on. That ordering is easy to get backwards and locks people out when you do.

Choosing what to migrate, in what order

With ingress, sessions, and models in place, the strangling can begin. The order matters more than the pace.

Start with things that have no user interface. Scheduled jobs, webhook receivers, report exports, anything that runs on a cron and writes to a table. These have clear inputs and outputs, no session state, and no visual regression risk. Rewriting one as an Artisan command is a contained afternoon's work, and it proves the plumbing works before anything user facing depends on it.

Then take read only pages. A listing screen or a detail view is low risk because getting it wrong shows up immediately and reverts cleanly. This is also where you establish the patterns the rest of the migration will follow, so spend the time getting the structure right rather than racing.

Write paths come next, and they come one at a time. A form that creates an order, a checkout flow, a settings update. These are where the business logic lives, which means they are also where the undocumented behaviour lives. Before you rewrite one, read the old code properly and write down every side effect you find, including the ones that look like bugs. Some of them are bugs. Some of them are load bearing, and the difference is a conversation with the business, not a judgement call you make alone.

Views come last, or rather views come alongside whatever you are already migrating. Replacing include 'header.php' with a Blade layout is not a project in itself, it is a thing that happens naturally as each page moves.

The step everybody skips is the final one. When a route is fully covered by Laravel, delete the legacy file and remove its fallback directive. If you do not delete it, it stays there, and eighteen months later nobody is sure whether it is still reachable. Deletion is the only proof that a migration finished.

Knowing whether it is working

A strangler migration that has no way of measuring progress will run forever, because there is always something more urgent than the next slice. Two numbers keep it honest.

The first is the count of requests still hitting the legacy fallback. Log it, graph it, and put the graph somewhere the team sees it. A line trending towards zero is the most persuasive migration status report you will ever write.

The second is the number of legacy files remaining. It is crude, and file size varies wildly, but it moves in one direction and it is impossible to argue with.

The reason this pattern works is not technical elegance. It works because it never asks the business to accept a period where nothing ships. Every week you deliver something, and every week a little more of the old system is gone. Nobody has to hold their nerve for six months, because nobody is ever more than a week from the next visible improvement.

That is the whole trick. Not a heroic rewrite, just a slow, boring, relentless narrowing of what the old code is still allowed to do.

Building Bulletproof Laravel APIs using Schema-First Contract Validation

Steve McDougall — Tue, 06 Oct 2026 19:23:18 +0000

Most Laravel APIs I review have the same shape. There is a controller, there is a FormRequest, and somewhere in a folder nobody has opened in four months there is an OpenAPI file that stopped being true around the third sprint. The validation rules and the documentation describe two different APIs, and the only way to find out which one is real is to send a request and see what comes back.

That gap is not a documentation problem. It is an architecture problem. We treat the contract as an output of the code, something we generate afterwards to keep consumers happy, when the contract is the one part of an API that consumers actually depend on. They do not depend on your Eloquent models. They do not depend on your Action classes. They depend on the shape of what they send you and the shape of what you send back.

Schema-first flips that relationship. You write the contract first, and everything else in the request response lifecycle is derived from it or checked against it. The schema validates the incoming payload, the schema shapes the response, and the schema is what your test suite asserts against. One source of truth, three consumers.

The problem with FormRequests as your only guard

I want to be clear that I like FormRequests. They are a good boundary. The issue is what they do not do.

Take a fairly ordinary request class:

final class StoreLeadRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'email', 'max:255'],
            'company' => ['required', 'string', 'max:255'],
            'source' => ['required', 'string', 'in:web,referral,event'],
        ];
    }
}

Now send this body:

{
    "email": "steve@example.com",
    "company": "Example Ltd",
    "source": "web",
    "is_admin": true,
    "score": 100,
    "internal_notes": "ignore this"
}

That request passes validation. Laravel does not care about the extra keys, because rules describe what must be present, not what is permitted. If a later refactor introduces a mass assignment path, or someone reaches for $request->all() instead of $request->validated(), those extra keys are suddenly live data in your database.

There is a subtler cost too. A consumer sending is_admin gets a 201 back and reasonably concludes the field is supported. They have no way to know it was silently discarded. You have created an undocumented, unsupported, entirely imaginary part of your API, and you did it by returning success.

A contract closes that door. In JSON Schema terms it is a single line:

{
    "additionalProperties": false
}

Anything the contract does not name is rejected. Not ignored, rejected, with a response that tells the client exactly which field was not understood.

Writing the contract first

I keep contracts as JSON Schema documents under contracts/, versioned alongside the routes they describe. If you are already publishing OpenAPI, the request and response schemas live inside your OpenAPI document and you extract them at build time. Either way the file is the artefact you edit by hand, and the PHP is what follows.

Here is the request contract for storing a lead:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://api.example.com/contracts/v1/leads/store-request.json",
    "type": "object",
    "additionalProperties": false,
    "required": ["email", "company", "source"],
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255
        },
        "company": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
        },
        "source": {
            "type": "string",
            "enum": ["web", "referral", "event"]
        },
        "notes": {
            "type": ["string", "null"],
            "maxLength": 2000
        }
    }
}

Writing this first changes the conversation you have before you write any code. You are forced to decide whether notes is nullable or absent, whether source is an open string or a closed set, and what happens when a client sends something you have not thought about. Those are design decisions. Making them in a schema file takes ten minutes. Making them in production takes a deprecation cycle.

Structuring the lifecycle around DTOs

The rule I hold to is that every side of the exchange gets its own object. Requests live in app/Http/Payloads, responses live in app/Http/Responses, and neither of them knows about Eloquent.

app/Http/
    Payloads/Leads/
        StoreLeadPayload.php
    Requests/Leads/V1/
        StoreLeadRequest.php
    Responses/Leads/
        LeadResponse.php
        LeadCollectionResponse.php
    Middleware/
        ValidatesContract.php

The payload is the typed representation of a validated request body. It carries no behaviour beyond construction and serialisation:

namespace App\Http\Payloads\Leads;

final readonly class StoreLeadPayload
{
    public function __construct(
        public string $email,
        public string $company,
        public string $source,
        public ?string $notes = null,
    ) {}

    public function toArray(): array
    {
        return [
            'email' => $this->email,
            'company' => $this->company,
            'source' => $this->source,
            'notes' => $this->notes,
        ];
    }
}

Past this point nothing in the application touches the request. The Action receives a payload, not an array, not a FormRequest, and certainly not the container resolved request singleton. That is the boundary doing its job.

Enforcing the contract at the edge

There are two ways to wire the schema in. You can validate inside the FormRequest, or you can validate before the FormRequest is ever resolved. I prefer the second, because a contract violation is not the same class of failure as a business rule violation, and I want to be able to tell them apart in logs.

Install a schema validator:

composer require opis/json-schema

Then a middleware that resolves the contract for the current route and checks the raw body against it:

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Opis\JsonSchema\Validator;
use Symfony\Component\HttpFoundation\Response;

final readonly class ValidatesContract
{
    public function __construct(
        private Validator $validator,
    ) {}

    public function handle(Request $request, Closure $next, string $contract): Response
    {
        $result = $this->validator->validate(
            data: json_decode($request->getContent() ?: '{}'),
            schema: "https://api.example.com/contracts/{$contract}.json",
        );

        if ($result->hasError()) {
            throw new ContractViolationException(
                error: $result->error(),
            );
        }

        return $next($request);
    }
}

The validator is registered once, with a resolver pointing at your contracts directory, so schemas are loaded and cached by $id rather than read from disk on every request:

public function register(): void
{
    $this->app->singleton(Validator::class, function (): Validator {
        $validator = new Validator();

        $validator->resolver()->registerPrefix(
            prefix: 'https://api.example.com/contracts/',
            path: base_path('contracts'),
        );

        return $validator;
    });
}

Applying it to a route is then a matter of naming the contract:

Route::post('/leads', V1\StoreController::class)
    ->middleware('contract:v1/leads/store-request');

The FormRequest still exists, and it still earns its place. It handles the things a schema genuinely cannot: uniqueness checks against the database, authorisation, rules that depend on the authenticated user. What it no longer does is describe the shape of the payload, because the schema already did that and did it in a format your consumers can read.

final class StoreLeadRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['unique:leads,email'],
        ];
    }

    public function payload(): StoreLeadPayload
    {
        return new StoreLeadPayload(
            email: $this->string('email')->toString(),
            company: $this->string('company')->toString(),
            source: $this->string('source')->toString(),
            notes: $this->input('notes'),
        );
    }
}

Notice what happened to the rules array. It got small, and everything left in it is something that requires knowledge the schema does not have. That is the split I want.

Failing in a way clients can act on

A contract violation deserves a better response than a generic 422 with a flat error bag. This is where Problem+JSON pays for itself:

final readonly class ContractViolationResponse implements Responsable
{
    public function __construct(
        private ValidationError $error,
        private string $contract,
    ) {}

    public function toResponse($request): JsonResponse
    {
        return new JsonResponse(
            data: [
                'type' => "https://api.example.com/errors/contract-violation",
                'title' => 'Request does not match the published contract',
                'status' => 422,
                'detail' => 'One or more fields were missing, malformed, or not recognised.',
                'contract' => $this->contract,
                'errors' => (new ErrorFormatter())->format($this->error),
            ],
            status: 422,
            headers: ['Content-Type' => 'application/problem+json'],
        );
    }
}

The client gets the schema identifier, the path to the offending field, and a link to documentation that describes the failure. A developer integrating with you can fix a broken payload without opening a support ticket, which is the whole point.

Responses get the same treatment

Requests are the half everyone remembers. Responses are the half that breaks people, because a response shape change ships silently and only surfaces when a mobile client three versions behind starts throwing null pointer exceptions.

Response DTOs live in app/Http/Responses and implement Responsable:

namespace App\Http\Responses\Leads;

final readonly class LeadResponse implements Responsable
{
    public function __construct(
        private Lead $lead,
        private int $status = 200,
    ) {}

    public function toResponse($request): JsonResponse
    {
        return new JsonResponse(
            data: [
                'data' => [
                    'type' => 'leads',
                    'id' => $this->lead->id,
                    'attributes' => [
                        'email' => $this->lead->email,
                        'company' => $this->lead->company,
                        'source' => $this->lead->source,
                        'score' => $this->lead->score,
                        'created_at' => $this->lead->created_at->toIso8601String(),
                    ],
                ],
            ],
            status: $this->status,
        );
    }
}

The controller reads exactly the way you would hope:

final readonly class StoreController
{
    public function __construct(
        private CreateLead $action,
    ) {}

    public function __invoke(StoreLeadRequest $request): Responsable
    {
        return new LeadResponse(
            lead: $this->action->handle(
                payload: $request->payload(),
            ),
            status: 201,
        );
    }
}

And the response contract sits next to the request contract, with additionalProperties set to false on every object in the tree. Leaking an internal field into a response is exactly as much of a breaking change as removing a documented one, and this is what stops it.

Testing against the contract

Here is where schema-first stops being tidy and starts being load bearing. Every feature test asserts against the published contract rather than against a hand written array:

it('returns a lead matching the published contract', function (): void {
    $response = $this->postJson('/api/v1/leads', [
        'email' => 'steve@example.com',
        'company' => 'Example Ltd',
        'source' => 'web',
    ]);

    $response->assertStatus(201);

    expect($response)->toMatchContract('v1/leads/store-response');
});

The custom expectation is a thin wrapper around the same validator the middleware uses:

expect()->extend('toMatchContract', function (string $contract): void {
    $result = app(Validator::class)->validate(
        data: json_decode($this->value->getContent()),
        schema: "https://api.example.com/contracts/{$contract}.json",
    );

    expect($result->isValid())->toBeTrue(
        (new ErrorFormatter())->formatFlat($result->error() ?? '')[0] ?? '',
    );
});

Now the contract cannot drift. If someone adds a field to a response DTO without adding it to the schema, the suite fails. If someone tightens the schema without updating the DTO, the suite fails. Documentation and implementation are held together by CI rather than by good intentions, and good intentions have a terrible track record.

I also run a paranoid test that sends deliberate rubbish at every write endpoint:

it('rejects fields outside the contract', function (): void {
    $this->postJson('/api/v1/leads', [
        'email' => 'steve@example.com',
        'company' => 'Example Ltd',
        'source' => 'web',
        'score' => 100,
    ])->assertStatus(422);
});

If that test ever goes green in the wrong direction, something has quietly opened the gate.

What this costs you

I am not going to pretend this is free. You are maintaining schema files as well as PHP classes, and there is a real temptation to generate one from the other to avoid the duplication. Resist it in the direction that matters. Generating PHP from the schema is fine. Generating the schema from PHP puts you back where you started, with a contract that describes whatever the code happens to do today.

There is also a performance consideration. Validating every request body against a schema is not free, though with a resolver caching compiled schemas in memory the cost sits well below the database work in a typical request. Measure it on your own workload before you take my word for it.

The payoff is that your API stops being a thing you discover through experimentation. Consumers read the contract and know what is accepted. Your test suite reads the contract and knows what is correct. Your middleware reads the contract and rejects what is not. Three parties, one file, no drift.

That is what bulletproof actually means here. Not that nothing ever goes wrong, but that when something does go wrong, it goes wrong loudly, in CI, before anybody outside your team notices.

Seven Days in Ten Milliseconds

Steve McDougall — Tue, 06 Oct 2026 19:23:16 +0000

Last month I walked through building an order fulfilment workflow with the workflow engine: signals arriving from webhooks, timeouts bounding the wait, retries with backoff, branching, and saga compensation when the whole thing falls over. It was a long article and it left one question completely unanswered.

How do you test the bit where it sleeps for three days?

That is not a rhetorical flourish. Take an abandoned cart reminder. Somebody adds a product to a basket and wanders off. You send a nudge, wait three days, send a final one, and give up. Most of that workflow is waiting. If your suite cannot cover the waiting, it is covering the boring quarter of the process and leaving the interesting three quarters to production.

The good news is that you never have to wait. Not once, not for a second. A sleeping instance is a database row with a wake time on it, and rows do not care what the clock says. Getting a seven day process to run in ten milliseconds is entirely a matter of who owns the clock, and it is not the workflow.

The test that lies to you

Here is the workflow. Two steps, one of which sleeps.

final class AbandonedCartReminder implements WorkflowDefinitionContract
{
    public static function name(): string
    {
        return 'abandoned_cart_reminder';
    }

    public function steps(): array
    {
        return [
            SendFirstReminder::class,
            SendFinalReminder::class,
        ];
    }
}

final class SendFirstReminder implements WorkflowStepContract
{
    public function __construct(
        private readonly CartRepository $carts,
    ) {}

    public function execute(WorkflowContext $context): StepResult
    {
        $cart = $this->carts->find($context->get('cart_id'));

        Mail::to($cart->email)->queue(new FirstReminder($cart));

        return StepResult::sleep(259_200, ['first_reminder_sent_at' => now()]);
    }

    public function timeoutSeconds(): ?int
    {
        return null;
    }

    public function maxAttempts(): int
    {
        return 3;
    }
}

And here is the test almost everybody writes first, because it is the one the tooling nudges you towards.

it('sleeps for three days', function (): void {
    $result = app(SendFirstReminder::class)->execute(
        context: WorkflowContext::make(
            workflowInstanceId: 'wf_1',
            aggregateId: (string) $this->cart->id,
            aggregateType: 'cart',
            initialData: ['cart_id' => $this->cart->id],
        ),
    );

    expect($result->sleepSeconds)->toBe(259_200);
});

That test passes. It will always pass. It is also worth nothing, and for exactly the reason I wrote about in Testing Actions, Not Mocks: it asserts on the shape of a return value rather than on what the system does with it.

Ask yourself what it would catch. Not a missing workflow:tick in the scheduler, which means the sleeper never wakes at all. Not a delayed advance job dropped by a queue restart. Not the second step reaching for first_reminder_sent_at and finding nothing because somebody moved the context update onto a different result. Not the customer who checks out on day two and gets the final reminder anyway, which is the bug your support inbox will actually receive.

Every one of those failures lives on the far side of the sleep. The unit test never goes there.

Own the clock, not the code

The shift that makes this tractable is small. Stop thinking of a sleeping workflow as blocked, and start thinking of it as parked. Nothing is held open. There is no worker sitting on it and no connection waiting. There is a row in workflow_instances with a status of sleeping and a wake_at in the future, and a delayed job that will knock on the door when the time comes.

So a test does not wait for anything. It moves the clock and knocks on the door itself.

use JustSteveKing\WorkflowEngine\Contracts\WorkflowRepositoryContract;
use JustSteveKing\WorkflowEngine\Domain\WorkflowEngine;
use JustSteveKing\WorkflowEngine\Domain\WorkflowStatus;

beforeEach(function (): void {
    $this->freezeTime();

    Queue::fake();
    Mail::fake();

    $this->engine = app(WorkflowEngine::class);
    $this->repository = app(WorkflowRepositoryContract::class);

    $this->cart = Cart::factory()->abandoned()->create();
});

it('parks on a wake time once the first reminder goes out', function (): void {
    $instance = $this->engine->start(
        workflowName: 'abandoned_cart_reminder',
        aggregateId: (string) $this->cart->id,
        aggregateType: 'cart',
        initialContext: ['cart_id' => $this->cart->id],
    );

    $this->engine->advance($instance->id);

    expect($this->repository->findById($instance->id))
        ->status->toBe(WorkflowStatus::Sleeping);

    Mail::assertQueued(FirstReminder::class);
});

Three things are doing the work. freezeTime() pins the clock so every calculation is relative to a known instant rather than to whenever CI happened to run. Queue::fake() stops the engine's own AdvanceWorkflow job from running the rest of the workflow out from under you, which is what makes the stepping deliberate. And calling advance() directly drives the state machine synchronously, which is exactly what the package's own feature suite does. In production the queued job calls the same method. In a test you are simply the queue.

One detail to internalise before you write anything else: advance() runs exactly one step. It executes the step at the cursor, persists the result, and queues a job for the next one. It does not loop. A test that drives the engine by hand needs one advance() per step, and one more at the end to move the cursor past the last step and mark the instance complete.

Asserting on absence

Here is where testing a sleeping workflow stops resembling normal testing.

Most of what we write asserts that something happened. A row exists, a mail went out, a response came back with the right status. With an instance parked on a wake time, the assertions that matter most are negative. The next step has not run. No mail is queued. The context has not gained the key that only the final step adds. The instance is still exactly where you left it.

Proving that a thing correctly has not happened yet is half the job, and almost nothing in the usual testing advice prepares you for it.

The sharpest version is the stray advance. Under an at-least-once queue you will get duplicate and early advance jobs, and the engine ignores one that arrives before the wake time. That guard is a real behaviour with a real failure mode, so it deserves a real test.

it('ignores an advance that lands before the wake time', function (): void {
    $instance = $this->engine->start(
        workflowName: 'abandoned_cart_reminder',
        aggregateId: (string) $this->cart->id,
        aggregateType: 'cart',
        initialContext: ['cart_id' => $this->cart->id],
    );

    $this->engine->advance($instance->id);

    $this->travel(2)->days();

    $this->engine->advance($instance->id);

    expect($this->repository->findById($instance->id))
        ->status->toBe(WorkflowStatus::Sleeping);

    Mail::assertNotQueued(FinalReminder::class);
});

Read that back as a sentence and it says something useful about the system: two days into a three day sleep, an extra advance changes nothing. Swap the repository for a custom one that quietly skips the wake time check and this test goes red. The unit test from earlier stays green.

Then, and only then, do you let time pass.

it('sends the final reminder once the sleep has elapsed', function (): void {
    $instance = $this->engine->start(
        workflowName: 'abandoned_cart_reminder',
        aggregateId: (string) $this->cart->id,
        aggregateType: 'cart',
        initialContext: ['cart_id' => $this->cart->id],
    );

    $this->engine->advance($instance->id); // SendFirstReminder, then sleeps

    $this->travel(3)->days()->addMinute();

    $this->engine->advance($instance->id); // wakes, runs SendFinalReminder
    $this->engine->advance($instance->id); // cursor past the end, instance completes

    expect($this->repository->findById($instance->id))
        ->status->toBe(WorkflowStatus::Completed);

    Mail::assertQueued(FinalReminder::class);
});

Three days and a minute, a few lines apart, no delay anywhere in the run. That is the ten milliseconds in the title.

A sleeping instance is not listening

There is a trap in that workflow, and writing the tests is how you find it.

A sleeping instance is in sleeping, not awaiting. It is not parked on a signal, so it is not listening for one. If the customer completes their checkout on day two, sending checkout_completed at the instance does not cancel anything. With early buffering on, which is the default, the signal is recorded and held for a step that never asks for it, and three days later the final reminder goes out to somebody who already bought the thing.

Sleep is a delay, not a subscription. If a drip campaign needs to be cancellable, the step that wakes up has to re-check the world before it acts.

public function execute(WorkflowContext $context): StepResult
{
    $cart = $this->carts->find($context->get('cart_id'));

    if ($cart->isCheckedOut()) {
        return StepResult::complete(['skipped_reason' => 'checked_out']);
    }

    Mail::to($cart->email)->queue(new FinalReminder($cart));

    return StepResult::complete();
}

Which gives you the absence test that actually protects the customer.

it('does not send the final reminder to a cart that has since checked out', function (): void {
    $instance = $this->engine->start(
        workflowName: 'abandoned_cart_reminder',
        aggregateId: (string) $this->cart->id,
        aggregateType: 'cart',
        initialContext: ['cart_id' => $this->cart->id],
    );

    $this->engine->advance($instance->id);

    $this->travel(2)->days();

    $this->cart->markCheckedOut();

    $this->travel(1)->day()->addMinute();

    $this->engine->advance($instance->id);
    $this->engine->advance($instance->id);

    expect($this->repository->findById($instance->id))
        ->status->toBe(WorkflowStatus::Completed)
        ->context->get('skipped_reason')->toBe('checked_out');

    Mail::assertNotQueued(FinalReminder::class);
});

The state changed while the workflow was asleep. That is the defining property of a long-running process, and it is invisible to any test that does not move the clock.

The races you only get one shot at

Sleeping is the easy half. The genuinely nasty paths appear when a signal and a timer are in flight at once, and those are the ones you will never reproduce by hand.

Take the member registration workflow from the package README. ChargeMemberStep sits at index 0, awaits payment_succeeded, and bounds its wait with an hour long timeout. The webhook lands at fifty nine minutes. The step advances. Somewhere out there, a delayed timeout job is still scheduled, and when it fires it must do nothing at all.

That is why the timeout carries the step index it was scheduled to guard. The engine ignores a timeout unless the instance is still awaiting at that exact cursor position. A guarantee you have not tested is a comment, so test it.

it('ignores a timeout scheduled for a step that has already advanced', function (): void {
    $instance = $this->engine->start(
        workflowName: 'member_registration',
        aggregateId: (string) $this->member->id,
        aggregateType: 'member',
        initialContext: ['member_id' => $this->member->id, 'plan' => 'annual'],
    );

    $this->engine->advance($instance->id); // ChargeMemberStep parks on the signal

    $this->engine->signal(
        instanceId: $instance->id,
        signal: 'payment_succeeded',
        signalData: ['payment_id' => 'pay_123'],
        deliveredBy: 'stripe_webhook',
    );

    $this->travel(1)->hour()->addMinute();

    $this->engine->timeout(
        instanceId: $instance->id,
        stepIndex: 0, // the step the timeout was guarding, now long gone
    );

    expect($this->repository->findById($instance->id))
        ->status->not->toBe(WorkflowStatus::Failed);
});

The other one worth writing is the early signal. A fast provider delivers payment_succeeded before the step has finished parking. With buffering on, the signal is held and consumed the moment the step asks for it, and the instance never parks at all. Fake the events, deliver the signal before the first advance, then advance, and assert that SignalReceived arrived with buffered set to true and that WorkflowAwaitingSignal was never dispatched.

Event::assertDispatched(
    SignalReceived::class,
    fn (SignalReceived $event): bool => $event->buffered,
);

Event::assertNotDispatched(WorkflowAwaitingSignal::class);

Absence again, and this time absence is the entire point of the feature.

I would write both of those before either of the happy paths. The happy path is what you check by hand in thirty seconds with workflow:advance and workflow:signal. The races are the ones you get exactly one shot at, at three in the morning, with a customer on the phone.

Time is an input, not an ambient fact

One last thing, and it quietly determines whether any of the above stays true.

Under an at-least-once queue a step can run more than once. If a step computes a deadline from whatever now() says at the instant it happens to execute, two runs produce two different deadlines, and the one that sticks is whichever run persisted last. Your test only agreed with production because you froze the clock. Production has no freezeTime().

Compute deadlines once, at start(), and thread them through the context as values.

$instance = $this->engine->start(
    workflowName: 'abandoned_cart_reminder',
    aggregateId: (string) $cart->id,
    aggregateType: 'cart',
    initialContext: [
        'cart_id' => $cart->id,
        'final_reminder_at' => now()->addDays(3)->toIso8601String(),
    ],
);

Now the step reads a value rather than asking the world what time it is, a re-run produces the same answer as the first run, and the test asserts on the same input production will see. Same reasoning as keeping models out of the context and storing identifiers instead. Anything a step derives from the outside world at execution time is something your test has to pin, and the pinning is where the lies creep in.

Get the clock under control and a three day drip campaign becomes an ordinary Pest test that runs in the same breath as everything else. Which leaves the harder question of what happens when a step fails halfway through and you have to unwind the ones that already succeeded.

Compensation is a saga running backwards, and testing a rollback is a different problem entirely. That one is next.

Give your Laravel AI agent real-time web knowledge

Steve McDougall — Thu, 16 Jul 2026 18:50:58 +0000

One of the best things about the Laravel AI SDK is that it doesn't lock you into a provider. Swap OpenAI for Anthropic, add Gemini as a failover, and your agent code barely changes. That's the entire pitch, and it mostly holds up.

Until your agent needs to browse the web.

The provider-agnostic promise has a hole in it

The SDK ships two provider tools for giving agents access to the web: WebSearch and WebFetch. They're convenient, a couple lines and your agent can search or fetch a page. But they're not really part of the SDK's unified layer, they're implemented natively by whichever AI provider you're using, which means their availability depends entirely on which model you picked.

WebSearch works on Anthropic, OpenAI, Gemini, and OpenRouter. WebFetch only works on Anthropic and Gemini. So if you configure a failover chain that includes Groq, DeepSeek, Mistral, or xAI, and one of those becomes the active provider, your agent quietly loses the ability to browse. Not an error, not a warning, just an agent that stops citing sources or stops noticing the page it was supposed to check even changed.

That's a rough thing to discover in production. You built a failover chain specifically so a rate limit or outage wouldn't take your feature down, and it turns out one of your fallback providers was silently missing a capability the whole time.

Even when it works, it's pretty shallow

Set the provider problem aside for a second. Even on a provider where WebSearch and WebFetch are both available, what you get back is raw: search results or fetched page content that the model has to reason over itself. There's no schema. There's no guaranteed citation tracking. If you want your agent to return a structured, sourced answer, that reasoning happens somewhere in the model's own inference, not in a layer you control or can test.

For a lot of use cases, that's fine. For anything where the answer needs to be defensible or reproducible, a research assistant, a competitive brief, anything a user might ask "where did this come from," it's not enough.

Build the tool yourself, on infrastructure that doesn't care which provider is active

The fix is to stop relying on provider-native web tools and give your agent a custom tool instead, one backed by an API rather than whichever model happens to be answering the prompt. That's exactly what a Tool class in the Laravel AI SDK is for.

juststeveking/tabstack gives you the client to build it on. Its agent()->research() method takes a question, searches multiple sources, synthesizes an answer, and streams back a report with citations, all as one call.

Since the package doesn't ship Laravel integration out of the box, the first step is binding it in a service provider so it can be injected anywhere:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use JustSteveKing\Tabstack\Tabstack;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(Tabstack::class, fn () => Tabstack::make(
            apiKey: config('services.tabstack.key'),
        ));
    }
}

Add the key to config/services.php:

'tabstack' => [
    'key' => env('TABSTACK_API_KEY'),
],

Now the tool itself. This wraps agent()->research() and hands the agent back a report with its sources listed:

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use JustSteveKing\Tabstack\Requests\AgentResearch;
use JustSteveKing\Tabstack\Requests\ResearchMode;
use JustSteveKing\Tabstack\Tabstack;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class WebResearch implements Tool
{
    public function __construct(
        private readonly Tabstack $tabstack,
    ) {}

    public function description(): Stringable|string
    {
        return 'Answers a question by researching multiple sources on the web and returns a synthesized, cited report. Use this when you need current information not in your training data.';
    }

    public function handle(Request $request): Stringable|string
    {
        $result = $this->tabstack->agent()->research(
            params: new AgentResearch(
                query: $request['query'],
                mode: ResearchMode::Fast,
            ),
        )->result();

        $sources = collect($result->metadata->get('citedPages', []))
            ->map(fn ($page) => "- {$page['title']}: {$page['url']}")
            ->implode("\n");

        return "{$result->report}\n\nSources:\n{$sources}";
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'query' => $schema->string()
                ->required()
                ->description('The question to research'),
        ];
    }
}

The ->result() call blocks until the stream finishes and hands back a typed ResearchResult rather than making you consume events yourself, which keeps the tool's handle method simple. If you'd rather stream progress back to the agent as it happens, the client also gives you ->each() and raw iteration, but for a tool call the blocking result is usually what you want.

Wire it into any agent through the tools method, same as any other tool:

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\WebResearch;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class MarketAnalyst implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help analyze markets and competitors. Use the research tool whenever you need current information. Always mention your sources.';
    }

    public function tools(): iterable
    {
        return [
            app(WebResearch::class),
        ];
    }
}

Now switch providers all you want:

$response = (new MarketAnalyst)->prompt(
    'What are the current pricing trends for cloud browser automation APIs?',
    provider: [Lab::OpenAI, Lab::Anthropic, Lab::Groq],
);

The agent's ability to research the web doesn't depend on which of those three ends up answering the prompt. The tool is yours, it runs the same regardless of which model called it.

Why this beats a raw fetch too

You could build something similar with WebFetch on a supported provider, pointing it at a specific known URL. But that only works when you already know which page has the answer. /research is built for the opposite case, a question with no known source, where the value is in picking the right sources, reading them, and synthesizing a single answer with the receipts attached. That's a genuinely different job than fetching one page, and it's the piece the SDK's built-in tools don't attempt.

The takeaway

The Laravel AI SDK's provider independence is one of its best features, right up until you reach for a tool that isn't actually part of that independence. Web access shouldn't be something your agent loses depending on which model answered the prompt. Building it as a real Tool class backed by an API, rather than leaning on whatever the current provider happens to expose, keeps that promise intact.

If you're building agents with the Laravel AI SDK and want this kind of tool ready to go, juststeveking/tabstack on Packagist is where I'd start.

The Right Agent at the Right Time

Steve McDougall — Wed, 15 Jul 2026 18:25:09 +0000

There are two ways I keep watching teams get AI wrong, and they are mirror images of each other.

The first team fights it. Every line an assistant writes gets rewritten by hand, because trusting it feels reckless. Generation is treated as a threat to be contained rather than a capability to be aimed. These teams perform a lot of ceremony and capture almost none of the speed, and they tell themselves that is the price of quality.

The second team surrenders to it. Requirements live in a chat log, the assistant produces a pull request nobody can properly review because there is no written intent to review it against, and the definition of done is "it ran once on my machine". This is fast right up until the moment it is catastrophically slow, usually around the third feature, when the context window fills up and the model starts quietly contradicting decisions it made an hour earlier.

Both teams are asking the wrong question. They are asking how much AI to use, as if the answer sits on a dial between zero and one. The useful question is different. Which work belongs to a machine, at which moment in the life of a change, and who holds the gate between one moment and the next?

That question has a good answer, and once you have it you can build a way of working around it. I want to walk through a development lifecycle that puts the right agent at the right time, wire it to the standards that keep the architecture honest, and describe the thin runtime you would put underneath to hold the whole thing together.

The lifecycle we are aiming for

Two methods do the heavy lifting, and I am going to lean on the pieces rather than re-argue them.

Shape Up gives us the outer track. Work is shaped into a bounded pitch before anyone commits to it, then bet on at a betting table, then built by a team that owns the whole thing for a fixed appetite. The word appetite matters. We do not estimate how long a change will take and then miss the estimate. We decide how much the change is worth, fix that budget, and vary the scope to fit. When the work threatens to overrun, we cut scope, not corners, and we never quietly extend the clock.

OpenSpec gives us the engine inside that track. A shaped pitch is expanded, with a single command, into concrete artefacts: a proposal that says why and what, a set of specs whose acceptance scenarios define done, a design that records the approach, and a task list. The work is carried out against those specs, published, reviewed, and then folded back into a living source of truth. The specs sit in the repository next to the code, so the next change starts from an accurate picture instead of a fading memory.

There is a gap in that description, and it is the gap this piece is really about. The specs tell you what a change does. They say nothing about how your team has decided to build things. Left to itself, a model filling in a design reaches for whatever architecture is most common in its training data, which is almost never the architecture your team actually agreed on. You end up with a pattern you banned two years ago, or a queue where you standardised on handling things in the request, drizzled through the codebase one well-meaning pull request at a time.

Three sources of truth

The fix is to recognise that a healthy lifecycle has not two sources of truth but three, and to keep them apart.

The pitch owns why. It is transient, it belongs to one change, and it evaporates once the work is bet on or dropped.

The specs own what. They describe the behaviour of a specific change, and they get archived into a living description of what the system does.

Architectural Decision Records own how. They are durable, they cut across every change, and they record the standing decisions your team has made about the way you build. An ADR is a small, deliberately boring document: a status, the context that forced the decision, the decision itself, and the consequences you are signing up for. You do not edit an accepted one. You supersede it with a new one, so the trail of reasoning survives every change of mind.

Here is the move that makes ADRs earn their place in an AI-driven lifecycle. The accepted decisions become the constraints every agent works within, and a change that needs a new decision cannot proceed on an agent's say-so. Standards flow into the specs and the conversations, and new standards flow back out under human control. Consumed on the way in, produced on the way out, and a person in the middle of both.

It is a state machine with mixed owners

If you list the stages a change moves through, shaped, bet on, proposed, built, published, reviewed, archived, and then ask a simple question at each one, who actually does the work here, you get three answers, not one.

Some stages are pure human judgement, and an agent has no business touching them. Deciding the appetite is a judgement about worth. Placing the bet is a decision about what we are willing to not do. Accepting an architectural decision is a commitment the whole team lives with for years. No model gets a vote on any of them.

Some stages are the machine drafting and a human correcting. Expanding a rough pitch into a detailed spec is exactly the kind of structured, high-value work a reasoning model is good at, and exactly the kind of thing a human should read and correct rather than write from a blank page. Drafting a pull request description from a spec is the same shape of work.

And some stages are effectively automatic. Folding a merged change back into the source of truth is mechanical. It should simply happen.

That is the whole design, and most agent tooling I see misses it by assuming every stage wants the same treatment. The question is never how clever the model is. It is where the authority sits. Architecture is the sharpest case of human authority in the list. An agent may apply an accepted decision, or draft a proposed one, and that is the ceiling of what it is allowed to do.

The runtime is the thing that holds the gates

Once you see the lifecycle this way, what you build underneath is small. It is a workflow engine that knows the sequence of stages, knows which of them require a person, knows which agent belongs to each, and moves a change forward one step at a time. Nothing exotic. If you have ever built a workflow engine, you already know the shape.

What earns its keep is not the cleverness of the runtime but the rules it refuses to break. It will not skip a stage that needs a human. It will not run an agent at a stage where no agent belongs. It will not let a change outrun its appetite. And it will not advance a change on the back of an architectural decision no human has accepted. Four rules that teams normally rely on willpower to follow, moved into something that does not get tired and does not have a deadline.

That last point is worth saying plainly. A rule that lives only in a wiki page is a suggestion, and suggestions lose to deadlines every time. A rule the runtime enforces is one the team can actually rely on, because it holds at six in the evening when the person driving it would have waved anything through.

The right agent at the right stage

Walk the stages and the shape of "the right tool at the right time" stops being a slogan.

At shaping, a fast and cheap critic argues with the draft pitch. It is not there to shape the work, because shaping is human judgement. It pushes back: is this appetite honest, or is a big piece of work wearing a small one's clothes, where are the rabbit holes you have not patched, and, importantly, does this work imply an architectural decision we have not yet made. Surfacing that last one before the betting table means the bet is placed knowing a new decision is coming.

At betting, there is no agent at all, and that absence is the most important design choice in the whole system. Betting is a decision about what we are willing to sacrifice this cycle, and I do not want a model anywhere near it. Deliberately wiring in nothing, and making that nothing visible rather than accidental, is how you stop the automation creeping into a place it should never reach.

At proposing, a reasoning model expands the pitch into the full spec, and this is where the standards do their real work. The accepted decisions are handed to the model as constraints, so the design it produces conforms to what your team agreed rather than to what is statistically popular. When the design fits inside those decisions, it cites the ones it stands on, so a reviewer can trace the architecture back to the record that authorised it. When the design escapes them, the model does not improvise. It drafts a new decision record, writes up the context and the tradeoffs, and stops. A design that contradicts an existing decision is handled the same way, as a proposal to supersede that record, which is a heavier call again and just as firmly a human one.

At building, a coding agent drives the work against the task list and reports where it is on the hill, still figuring things out or executing what it already understands. The agent is fast and trustworthy on the downhill, on the known work. When it reports itself stuck on the uphill for too long, that is your earliest possible warning, long before a missed task count would tell you anything. The standards ride along here too, because they constrain the code as much as the design.

At publishing, the drafting is mechanical and the action is not. An agent writes the pull request description from the spec and the decisions it cited, and then it stops. A person opens it. Anything that changes the world outside the repository stays behind a human hand.

At reviewing, a first pass by a model saves the human reviewer from wasting their hour. It checks two mechanical questions before a person looks: does the implementation satisfy every scenario in the specs, and does it conform to the decisions the design cited. A change that quietly wandered off its stated architecture gets caught cheaply, which leaves the human free to judge the only thing a human can, whether this is genuinely the right solution.

The gates are the point

The temptation is always to remove gates for speed, so let me defend them.

Three kinds matter. The judgement gate, on shaping, betting, and review, where the work waits until a person approves. The architecture gate, where a proposed or superseding decision holds the change until a human rules on it. And the side-effect gate, on publishing, merging, and deleting, actions that reach outside the repository and must never fire on a model's confidence alone.

The failure mode of agent tooling is rarely a bad line of code. Review catches that. It is an irreversible action, or an unexamined architectural choice, taken confidently at the wrong moment. You put those behind gates precisely so the gate holds when the person driving it is tired and behind and would have clicked yes to anything.

The circuit breaker, and standards that feed both ways

The appetite is not advisory. When a change blows its budget, the work does not roll forward and nobody negotiates an extension. It goes back to shaping, to be re-shaped with what was learned and bet on again from scratch. The default is that unfinished work stops, not that it drags, and that default is the single healthiest habit Shape Up gives you.

The standards behave the same way, enforced rather than hoped for. Every spec and every agent conversation is bounded by decisions a human accepted, so the architecture cannot drift one convenient pull request at a time. And every new decision surfaces as its own gate rather than hiding inside a diff, so the team decides architecture on purpose, with the reasoning written down, at the moment the choice is actually made.

It is worth being clear about how these records relate to a plain conventions file, because most teams already keep one of those. A conventions file is the distilled current rule an agent follows day to day. It tells the model what to do. A decision record is the reasoning behind a rule, captured at the moment it was made, so that when someone later proposes to overturn it they are arguing with the original context rather than guessing at it. Keep both, and generate the conventions from the accepted decisions if you can, so the two never drift apart.

Why any of this, and not just a set of commands

You might reasonably ask why a lifecycle needs a runtime at all, when the tools already give you the commands and the decision records are just files in a folder.

Because the process is exactly the thing that gets skipped under pressure, and the person under pressure is the worst possible guardian of it. The value of the runtime is that it holds the gate the human would not. It refuses to advance past review late in the day. It trips the breaker on the change everyone is emotionally committed to finishing. It leaves betting to people by having nothing to delegate it to. And it will not let a design invent architecture, because a proposed decision parks the change until a person signs the record. The discipline stops depending on everyone remembering to be disciplined and becomes a property of the system.

The heart of all this, the sequence of stages, the gates, the appetite, the decision log, has nothing to do with any particular framework or even any particular language. It is a workflow engine with mixed authority and a standards layer, and I would build it to stay independent of any framework and let the AI tooling plug in at the edges. Which, you will notice, is itself an architectural decision, the kind of thing that belongs in a record with its context and its consequences written down. The runtime ends up built the way its own decision log says to build things, and that is the whole idea quietly working on itself.

Next time I want to open up the two agents I skated past here, the critic that argues with your pitch and the reviewer that reads AI-generated work for both correctness and conformance, because those are the two places where getting the model's role slightly wrong quietly poisons everything downstream.

Fibers Plus the Polling API: What Async PHP Actually Looks Like Now

Steve McDougall — Wed, 15 Jul 2026 18:25:05 +0000

I wrote about the Polling API RFC a few weeks back and framed it as underrated, mostly because the coverage kept missing that the real motivation was the internal php_poll.h API rather than the userspace Io\Poll classes. I stand by that. But I got a fair bit of feedback along the lines of "fine, but what do I actually build with it?" That is a reasonable question, and it is the one I want to answer here.

The timing is good for it too. The RFC passed 33 to 1 with four abstentions and closed on 3 June, and the implementation is already merged to master. Alpha 1 is scheduled for 2 July, feature freeze and Beta 1 land in mid-August, and GA is pencilled in for 19 November. Which means the Polling API has gone from RFC text to something you can compile off master and poke at right now, ahead of the formal alpha tag. So that is what I did.

At the same time, there is a genuinely live argument running through the PHP community right now about which async approach to actually use in production: Fibers with a userland event loop, ReactPHP, Swoole, or Amp v3 on Revolt. Nobody has tied that debate cleanly to what the Polling API changes. I want to do that properly, with real code, not just vibes.

Fibers are the concurrency model, the Polling API is the missing primitive

These two things get conflated constantly, so let me separate them cleanly before we build anything.

A Fiber is PHP's cooperative concurrency primitive, in core since 8.1. It gives you a function that can pause itself with Fiber::suspend() and be resumed later with $fiber->resume(), keeping its own stack and local state intact across the pause. That is the entire feature. It does not know anything about sockets, timers, or I/O. It is a control-flow primitive, nothing more.

An event loop is the thing that decides when to resume a suspended fiber. Historically in PHP, that meant stream_select() under the hood, or reaching for a PECL extension like ext-uv or ext-event to get native epoll or kqueue. ReactPHP ships four separate loop implementations, StreamSelectLoop, ExtUvLoop, ExtEventLoop, ExtEvLoop, precisely because there was no single reliable native primitive to build on. AMPHP built its own equivalent story through Revolt.

The Polling API is that missing primitive. It does not replace Fibers, and it is not an event loop itself. It is the one thing underneath an event loop that PHP never had natively: a fast way to ask the operating system "which of these file descriptors are ready" without maintaining four separate backend implementations to get there.

Put together, Fibers give you pausable functions and the Polling API gives you an efficient way to know when to resume them. That is the whole story. Everything else, timers, cancellation, backpressure, is stuff you or a library builds on top.

Building the smallest possible scheduler

The best way to understand what Amp v3 and ReactPHP are actually doing internally is to build a toy version yourself. So let us do that: a scheduler that runs several fibers concurrently, each one fetching a URL over a raw non-blocking socket, resumed by a single Io\Poll\Context.

<?php

declare(strict_types=1);

use Io\Poll\{Context, Event};

final class MiniScheduler
{
    private Context $poll;

    /** @var array<int, Fiber> */
    private array $fibers = [];

    public function __construct()
    {
        $this->poll = new Context();
    }

    public function spawn(callable $task): void
    {
        $fiber = new Fiber($task);
        $fiber->start();

        if ($fiber->isTerminated()) {
            return;
        }

        $this->fibers[spl_object_id($fiber)] = $fiber;
    }

    public function run(): void
    {
        while ($this->fibers !== []) {
            foreach ($this->poll->wait(timeoutSeconds: 1) as $watcher) {
                $fiber = $watcher->getData()['fiber'];

                $fiber->resume($watcher);

                if ($fiber->isTerminated()) {
                    unset($this->fibers[spl_object_id($fiber)]);
                }
            }
        }
    }

    public function awaitReadable($stream): void
    {
        $fiber = Fiber::getCurrent();
        $handle = new StreamPollHandle($stream);
        $watcher = $this->poll->add($handle, [Event::Read], ['fiber' => $fiber]);

        Fiber::suspend();

        $watcher->remove();
    }

    public function awaitWritable($stream): void
    {
        $fiber = Fiber::getCurrent();
        $handle = new StreamPollHandle($stream);
        $watcher = $this->poll->add($handle, [Event::Write], ['fiber' => $fiber]);

        Fiber::suspend();

        $watcher->remove();
    }
}

That is genuinely most of it. spawn() starts a fiber, which runs until it hits Fiber::suspend(). run() calls wait() on the poll context, which blocks until a watched stream is actually readable, then resumes exactly the fiber waiting on it. No polling in a tight loop, no scanning every stream on every tick. The operating system tells us the moment something is ready, and we hand control straight back to the fiber that cares.

Now the actual task, a non-blocking fetch over a raw socket. This needed one correction from my first draft of this: writing to a non-blocking stream can short-write, so the request has to be written in a loop that awaits writability whenever the kernel send buffer pushes back, rather than trusting a single fwrite() call to send the whole thing:

<?php

declare(strict_types=1);

function writeAll(MiniScheduler $scheduler, $stream, string $data): void
{
    while ($data !== '') {
        $written = fwrite($stream, $data);

        if ($written === false) {
            throw new RuntimeException('Write failed');
        }

        if ($written === 0) {
            $scheduler->awaitWritable($stream);
            continue;
        }

        $data = substr($data, $written);
    }
}

function fetch(MiniScheduler $scheduler, string $host, string $path): string
{
    $stream = stream_socket_client("tcp://{$host}:80", $errno, $errstr, 30);

    if ($stream === false) {
        throw new RuntimeException("Connect to {$host} failed: {$errstr}");
    }

    stream_set_blocking($stream, false);

    writeAll($scheduler, $stream, "GET {$path} HTTP/1.1\r\nHost: {$host}\r\nConnection: close\r\n\r\n");

    $response = '';

    while (!feof($stream)) {
        $scheduler->awaitReadable($stream);
        $response .= fread($stream, 8192);
    }

    fclose($stream);

    return $response;
}

On termination: the loop relies on feof() flipping true after a read that hits end of stream, which is the same pattern the RFC's own TCP client example uses. It holds here for a reason worth being explicit about: awaitReadable() only requests Event::Read, but Event::Error and Event::HangUp are automatically monitored by every backend regardless of what you asked for, so wait() still returns the watcher when the server closes the connection. The code does not branch on hasTriggered() before calling fread(), it just calls it unconditionally once woken, and fread() on a closed non-blocking stream returns an empty string and sets the EOF flag rather than blocking or erroring. That is what makes the final iteration exit cleanly instead of hanging on the last descriptor. If you want to be stricter about it, checking hasTriggered(Event::Read) before reading and handling Event::HangUp separately is the more defensive version, I just did not want to bury the core loop under branches that do not change the outcome for a plain HTTP GET.

Wire five of these into a scheduler and run them concurrently:

<?php

declare(strict_types=1);

$scheduler = new MiniScheduler();

$hosts = [
    'example.com',
    'httpbin.org',
    'jsonplaceholder.typicode.com',
];

foreach ($hosts as $host) {
    $scheduler->spawn(function () use ($scheduler, $host) {
        $body = fetch($scheduler, $host, '/');
        echo "{$host}: " . strlen($body) . " bytes\n";
    });
}

$scheduler->run();

Three fibers, each blocked on its own socket, all resumed independently by one Io\Poll\Context. This is, structurally, what Revolt's driver does and what ReactPHP's loop does. We just wrote the smallest version that still works.

What I am not showing you, on purpose

This scheduler has no timers, no cancellation tokens, no error propagation from a fiber back to the caller, no protection against a fiber that never suspends and blocks everyone else, and no DNS handling beyond whatever stream_socket_client() gives you for free. That is not an oversight. It is the point.

Amp v3 and ReactPHP exist because building a correct, safe version of this is genuinely hard, and getting cancellation and backpressure right across hundreds of concurrent fibers is not a weekend project. Do not take this scheduler anywhere near production. Take the understanding it gives you into whichever library you actually reach for.

Benchmarking it, honestly

I want to be upfront about the limits here before I give you numbers. PHP 8.6 is still pre-alpha as I write this, self-compiled off master, not a packaged build you can apt install. There is no stable release, no distro packages, and the Io\Poll implementation can still change before GA. Treat what follows as directional, not a production SLA.

I ran the three-host fetch above four ways: sequential blocking file_get_contents() calls, the mini scheduler above on the 8.6 alpha build, ReactPHP's StreamSelectLoop on 8.4, and Amp v3 on Revolt on 8.4. Same three hosts, same simple GET request, ten runs each, median taken.

Sequential blocking came in around the sum of all three round trips, no surprise there, since each request waits for the last to finish before starting. The mini scheduler and ReactPHP's StreamSelectLoop landed close to each other, both roughly bounded by the slowest single request rather than the sum, which is exactly what you want from concurrent I/O. Amp v3 on Revolt was marginally ahead of both, which tracks, since Revolt has years of tuning behind it that my forty-line scheduler does not.

The interesting result was not the timing, it was the CPU behaviour. stream_select() based loops do measurably more userspace work rescanning descriptor sets as the number of watched streams grows. The Io\Poll\Context version stayed flat. Three streams versus thirty streams cost roughly the same per wait() call, because epoll does not rescan the whole set, it just tells you what is ready. That is the actual payoff, and it will not show up clearly until someone benchmarks this at real concurrency, hundreds or thousands of streams, not three.

One honest gap in this comparison: ReactPHP and Amp v3 ran on 8.4, the mini scheduler ran on 8.6 pre-alpha, so what I measured is loop implementation and PHP version changing together, not the loop in isolation. A same-version comparison, ReactPHP and Amp v3 both running against a Polling API backend on the same 8.6 build, would isolate the loop's contribution properly. That is not possible yet because neither project has shipped an Io\Poll driver, which is rather the point of this whole piece. Take the CPU behaviour as the more reliable signal here, since that is architectural and does not depend on which PHP build ran it, and take the wall-clock numbers as a rough sanity check rather than a verdict.

Where this leaves Fibers versus ReactPHP versus Swoole versus Amp v3

This is the argument I said I would tie together, so here is where I land on it.

Swoole is not really part of this comparison, and treating it as one option among four is where a lot of the online debate goes wrong. Swoole is a different PHP runtime. It replaces how your application boots, patches core functions to be non-blocking transparently, and gives you a production HTTP server with worker processes built in. You do not add Swoole to an app, you build the app for Swoole from the start. It is genuinely excellent for the right workload, and the C-level coroutine switching gives it a real edge over userland Fibers when you need every millisecond and have the ops discipline to manage a compiled extension in your Docker images. The Polling API changes nothing about that trade-off, since Swoole was never limited by the thing the Polling API fixes.

ReactPHP and Amp v3 are the ones actually affected here, and in the same direction. Both exist to give you an event loop on top of Fibers without asking you to rewrite your application around a different runtime. Both have spent years maintaining multiple backend implementations, StreamSelectLoop, ExtUvLoop, ExtEventLoop, ExtEvLoop for ReactPHP, an equivalent spread for Amp, purely to paper over the fact that PHP core never gave them a single reliable native polling primitive. The Polling API is that primitive, finally, and it collapses the reason those parallel implementations exist. I would expect Revolt in particular to pick this up quickly as a native backend, since Revolt already sits underneath Amp v3 as the shared low-level driver, and this is exactly the kind of internal plumbing it was built to abstract over.

None of this makes the choice between ReactPHP and Amp v3 disappear. That is still mostly a style question. Amp v3's fiber-first API reads closer to synchronous code, ReactPHP's promise-chaining style gives you more explicit control over the loop if you want it, and they are interoperable through revolt/event-loop-adapter-react if you genuinely need both in one process. What the Polling API does is remove the excuse for either of them to keep maintaining bespoke native backends, and it means a five dollar droplet running vanilla PHP 8.6 gets the same epoll performance that used to require a compiled PECL extension most shared hosts never had.

A quick PestPHP check on the scheduler

If you want to verify the concurrency claim rather than take my word for the timings, this is roughly how I tested it, using two servers that each sleep for a fixed period before responding, to confirm the total time tracks the slowest request rather than the sum:

<?php

declare(strict_types=1);

it('resumes concurrent fibers without serialising the wait time', function () {
    $scheduler = new MiniScheduler();
    $started = microtime(true);

    foreach (['sleepy-one.test', 'sleepy-two.test'] as $host) {
        $scheduler->spawn(function () use ($scheduler, $host) {
            fetch($scheduler, $host, '/sleep?ms=200');
        });
    }

    $scheduler->run();

    $elapsed = microtime(true) - $started;

    expect($elapsed)->toBeLessThan(0.35);
});

Two requests that each take roughly two hundred milliseconds finishing in well under the combined four hundred is the whole test. It is not a sophisticated assertion, but it is the one that actually matters here, and it is the one that fails immediately if you accidentally write blocking code inside a fiber and forget it.

The practical takeaway

If you are building application code today, reach for Amp v3 or ReactPHP, not a hand-rolled scheduler, and pick based on whether you want fiber-native ergonomics or explicit promise control. If you are running a workload where every millisecond and every byte of memory per connection matters and you have the operational maturity for a compiled extension, Swoole earns its complexity. If you maintain one of those libraries yourself, the Polling API is the thing to go build against right now, while it is still ahead of alpha and your feedback can actually shape what ships in November.

PHP spent a decade being told it could not do this properly. Turns out it just needed the operating system to stop being a stranger.

The Polling API Is the Most Underrated RFC PHP Has Shipped in Years

Steve McDougall — Tue, 23 Jun 2026 21:09:47 +0000

While most of the community spent the spring arguing about generics, a different RFC slipped into PHP 8.6 with almost none of the attention it deserved. No long Twitter threads. No blog posts dissecting the implications. Just a quiet vote that closed on the third of June with 33 in favour, one against, and four abstaining, from a list of names that includes the Composer author, the FrankenPHP creator, and a healthy chunk of the people who actually maintain the async libraries you depend on.

That RFC is the Polling API, authored by Jakub Zelenka as part of his ongoing stream evolution work. I want to make the case that it is the most consequential thing to land in PHP in years, and that the reason nobody is talking about it is exactly the reason it matters.

The problem you have been quietly working around

If you have ever written anything that needs to watch more than one socket at a time, you have met stream_select(). It is the only I/O multiplexing primitive PHP has shipped for most of its life, and it is built on the select() system call from 1983. It works. It also carries a set of limitations that every async library author has had to engineer around.

The first is the file descriptor ceiling. The current implementation caps out at around 1024 descriptors on most systems, which is fine until the moment it very much is not. The second is the complexity. select() is O(n): it scans every descriptor you hand it on every single call, so performance degrades as you add connections. The third is that it gives you no access to the mechanisms the rest of the world has been using for two decades. There is no epoll on Linux, no kqueue on BSD or macOS, no event ports on Solaris. There is no edge-triggered mode and no one-shot mode.

This is why every serious async runtime reaches past select(). Node, Nginx, Go's net package, Rust's Tokio: they all sit on epoll or kqueue, because that is the foundation high-concurrency networking is built on. PHP was the last major runtime without native access to it, which is why libraries like AMPHP and ReactPHP have shipped multiple driver backends for years. You write your StreamSelect driver for the common case, then a separate libuv driver for the people who installed ext-uv, because a single native high-performance option simply did not exist. That "install ext-uv for performance" line in the README is a workaround for a hole in the language itself.

The Polling API fills the hole.

What it actually is, and what it is not

The proposal adds a small set of classes under a new Io\Poll namespace. It automatically selects the best polling backend for the platform you are running on, and exposes a consistent interface on top of it. On Linux you get epoll, on macOS and BSD you get kqueue, on Solaris and illumos you get event ports, on Windows you get WSAPoll, and everything else falls back to poll(). You do not have to think about any of that. You create a context and it picks the right backend.

Here is the whole thing in one breath. You create a Context, you wrap a stream in a StreamPollHandle, you add it to the context with the events you care about, and you call wait():

<?php

declare(strict_types=1);

use Io\Poll\{Context, Event};

$poll = new Context();

$server = stream_socket_server('tcp://0.0.0.0:8080', $errno, $errstr);
stream_set_blocking($server, false);

$poll->add(new StreamPollHandle($server), [Event::Read], ['type' => 'server']);

while (true) {
    foreach ($poll->wait(timeoutSeconds: 1) as $watcher) {
        // a watcher only comes back if it has events ready
        $handle = $watcher->getHandle();

        if ($watcher->hasTriggered(Event::Read)) {
            // accept, read, write, whatever this descriptor needs
        }
    }
}

That is the shape of it. wait() blocks until something is ready or the timeout expires, then hands you back only the watchers that actually triggered. No scanning the full set yourself, no guessing which descriptor woke you up.

The important thing to understand is what the RFC deliberately leaves out. This is not an event loop. There are no timers in the first cut, no signal handling, no child process management. It is one primitive: a way to watch file descriptors efficiently using whatever the operating system does best. If you want a full event loop with all the trimmings, you still reach for AMPHP or ReactPHP. The difference is that those libraries can now sit on a single native backend instead of maintaining their own.

The part nobody is talking about

Here is where I think the coverage has missed the real story. Every article I have seen frames this as a userspace feature, a faster stream_select() for people building WebSocket servers. That is a genuine benefit, and it is also explicitly the secondary one.

Read the RFC carefully and the primary motivation is the internal API. Jakub is building a unified polling interface that PHP core and extensions can share, and the userspace classes are a gift that falls out of having done that work properly. The internal php_poll.h header is the actual point.

Why does that matter to you, someone writing application code who will probably never type new Context()? Because of what it unlocks underneath. Safe, efficient signal handling in ZTS, which is exactly what FrankenPHP needs for its goroutine-based threading mode. More flexible event handling in PHP-FPM workers, replacing the ad-hoc implementations that exist today. A cross-platform timer foundation, which has been a genuine pain on macOS. A standard interface that the sockets and curl extensions can build on rather than each rolling their own.

The future scope section reads like a roadmap for the next few years of PHP's networking internals: SocketPollHandle, CurlPollHandle, TimerHandle, SignalHandle, FPM migrating onto the internal loop, and the consolidation of all the scattered polling code across the codebase into one place. None of that is glamorous. All of it is the kind of foundational plumbing that quietly raises the ceiling for everything built on top.

The best infrastructure changes are invisible. You do not notice epoll. You notice that Nginx handles ten thousand connections without sweating, and you never think about why.

The design choices worth admiring

A couple of decisions in the API are worth slowing down on, because they tell you something about how carefully this was put together.

The first is the Handle interface. It is a marker interface with no methods, and you cannot implement it from userland. Try, and you get a fatal error at class declaration time:

Fatal error: Io\Poll\Handle cannot be implemented by user classes

That looks restrictive until you understand why. Every concrete handle type has to register a C-level operations table (php_poll_handle_ops) that tells the backend how to extract the underlying file descriptor and check whether the handle is still valid. A userland class cannot provide that, so allowing it to implement the interface would only produce handles that do not work. By locking the interface to internal classes, the contract stays enforceable: any Handle that reaches the polling backend is guaranteed to have a working ops table. If you need to poll a custom resource, you wrap a stream in StreamPollHandle and let the existing machinery do its job. Clean userspace surface, all the messy file descriptor logic kept on the C side where it belongs.

The second is the Watcher. You never construct one directly; Context::add() returns it to you, and it carries everything about that registration. You can ask it which events it is watching, which ones just triggered, and the arbitrary user data you attached. You can modify it in place or remove it:

<?php

declare(strict_types=1);

use Io\Poll\{Context, Event};

$poll = new Context();
$stream = fopen('php://temp', 'r+');

$watcher = $poll->add(new StreamPollHandle($stream), [Event::Read], 'some data');

// switch what you are watching for without rebuilding the registration
$watcher->modifyEvents([Event::Write]);

// or change both events and the attached data at once
$watcher->modify([Event::Read, Event::Write], 'updated data');

if ($watcher->isActive()) {
    $watcher->remove();
}

The Event enum is where the modern mechanisms surface. Alongside the obvious Read and Write, you get Event::OneShot to have a watcher remove itself automatically after it fires once, and Event::EdgeTriggered for the high-performance mode that only reports state changes rather than state. Edge triggering is the technique that lets epoll and kqueue scale to tens of thousands of connections, and it is available here through a single enum case. You can even ask the backend whether it supports it before you rely on it, via $poll->getBackend()->supportsEdgeTriggering().

The narrative this quietly kills

There is a line you have heard a thousand times, usually from someone who last touched PHP in 2014. "PHP can't scale." For a long time there was a kernel of technical truth buried under the reputation, because the language genuinely did not give you native access to the polling primitives that high-concurrency servers are built on. You could get there with userland libraries and an optional extension, but the foundation was not in the language.

With 8.6 it is. AMPHP, ReactPHP, and Revolt can move their event loop backends onto it. The ext-uv footnote can start disappearing from async READMEs. Benchmarks handling the C10K problem on a stock PHP build will follow, because epoll and kqueue hold steady at ten thousand connections and beyond where select() falls apart after a few hundred. The last technical leg under "PHP can't scale" gets kicked away, and what remains is a perception problem rather than a language one.

I want to be honest about the limits of the excitement, because the accurate version is more persuasive than the hype. This passed with one dissenting vote and four abstentions, not the unanimous landslide some of the early write-ups claimed. Most application developers will genuinely never write new Io\Poll\Context() in anger. You will feel this through your framework, through a faster FPM, through an async library that finally ships one backend instead of three, through FrankenPHP handling signals correctly under threads. The value is real and it is almost entirely indirect.

That is precisely why it is underrated. A loud feature you use every day gets attention by default. A quiet foundation that raises the floor for the entire ecosystem has to be pointed at, because the people it helps most are the ones who will never see it directly. Jakub did the unglamorous work of building the primitive that was missing for twenty years, and the people who understood what it does voted it through without much noise.

Sometimes the most important thing in a release is the line nobody is arguing about.

Next time you read a README that tells you to install ext-uv for performance, remember that the footnote has an expiry date now, and go and read what Io\Poll is doing underneath.

A Proper Look at Tabstack

Steve McDougall — Tue, 23 Jun 2026 20:07:27 +0000

I have spent a fair bit of time recently with Tabstack, including building a CLI around its API, and I think it is worth writing down what it actually is, what you would reach for it to do, and whether it earns its place in your stack. There is a lot of noise around anything with "AI" in the description at the moment, so I want to cut through that and talk about the thing on its own terms.

Let me start with the problem it exists to solve, because the product makes far more sense once you have felt the pain it removes.

The problem nobody wants to own

If you have ever tried to give a program reliable access to the web, you know how quickly it turns into a swamp. You begin with a simple fetch. Then a site renders its content client-side, so a raw fetch returns an empty shell and you reach for a headless browser. Then you are managing proxies because you keep getting rate limited. Then the markup changes and your carefully written selectors snap. Then you are writing bespoke parsing logic for every single site you touch, and every one of those is a small liability waiting to break at three in the morning.

None of that is the interesting part of your product. It is plumbing. You are maintaining a rendering engine, a proxy layer, and a pile of brittle extraction code purely so your actual application can read a page. That is the work Tabstack is offering to take off your hands.

What Tabstack actually is

Tabstack is a web execution and data transformation API built at Mozilla. The pitch is straightforward: you hand it a URL, a schema, a question, or a task, and the browser, the model, and the orchestration all run on their side. You get back clean data, cited answers, or completed browser tasks. There is no headless Chrome for you to provision, no LLM for you to wire in, and no parsing layer for you to babysit.

It is a developer product, not a consumer one. There is no dashboard where you sit and browse the web by hand. It is a REST API with TypeScript and Python SDKs, an MCP server, and a CLI, and it is aimed squarely at people building agents, research tools, data pipelines, and automated workflows.

At the time of writing it is in public early access, and every account starts with ten thousand free credits and no card required, which is generous enough to actually evaluate it properly rather than just kicking the tyres.

The four things it does

The whole surface comes down to four capabilities, and once you see them laid out, the mental model clicks into place.

Extract turns a page into something a model can actually use. The cheapest form is markdown. You give it a URL and you get clean markdown back, frontmatter and all, which is exactly what you want when you are feeding a context window and do not want to burn tokens on rendered HTML noise.

curl -X POST "https://api.tabstack.ai/v1/extract/markdown" \
  -H "Authorization: Bearer $TABSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

The more interesting form of extract is JSON. You describe the shape you want with a schema, you pass a URL, and you get back data that matches that schema. No selectors, no parsing, no handling of unexpected shapes downstream.

import Tabstack from '@tabstack/sdk';

const client = new Tabstack();

const { jobs } = await client.extract.json({
 url: 'https://www.google.com/about/careers/applications/jobs/results',
 json_schema: {
  jobs: [{ title: 'string', location: 'string' }],
 },
});

That schema enforcement is the bit that matters. The contract is yours, not the website's. When the site reshuffles its layout next week, your pipeline does not care, because you are asking for a shape rather than scraping a structure.

Generate is the sibling to extract, and the distinction is worth getting right. Extract pulls data that already exists on the page. Generate uses a model to create something new from that content: a summary, a categorisation, a rewritten output, a tailored message. If you want the price that is printed on a product page, that is extract. If you want a one-line sentiment-tagged summary of a review, that is generate.

Automate is the ambitious one. You give it a task in plain language and it drives a real browser to completion: clicking, scrolling, filling forms, submitting, working through multi-step flows on sites you do not control.

import os
from tabstack import Tabstack

tabs = Tabstack(api_key=os.getenv('TABSTACK_API_KEY'))

result = await tabs.agent.automate(
    url="https://news.ycombinator.com",
    task="Go through 5 pages of the top posts. For each post, determine the "
         "website it is from and group all posts by website. Return the 10 "
         "websites with the most posts.",
)

This is the capability that replaces the headless-browser-and-glue-code stack entirely. It also has guardrails you can set, a max-iterations cap, and an interactive mode where your own orchestrator can stay in the loop, which I will come back to.

Research runs an autonomous multi-source pass and hands you back a synthesised answer with every claim cited to its source. The selection of sources, the reading, the synthesis, and the citation all happen inside one call.

const stream = await client.agent.research({
 query: 'Key risks in CRE lending right now?',
 mode: 'fast',
});

for await (const event of stream) {
 if (event.event === 'complete') {
  console.log(event.data.report);
  console.log(event.data.metadata.citedPages);
 }
}

The citations are the selling point here. If you are shipping a research feature to real users, an answer they can trust because every claim points at a source is worth a great deal more than a confident paragraph with no provenance.

What you would actually build with it

The four capabilities are abstract until you map them onto real work, so here is where they land.

Price and competitor monitoring is the obvious one. A scheduled extract call against a set of product pages, returning schema-matched JSON, keeps a dashboard current without anyone copy-pasting from a browser. Lead enrichment is another clean fit: take a raw domain, extract headcount, tech stack, and funding signals, and push it into your pipeline instead of stitching together a row of data vendors. Job aggregation, market research, and competitive intelligence all sit in the same bucket, where the win is structured output from messy pages.

Research mode opens up in-product features: a research assistant inside your application that answers from the live web with citations, rather than from a stale index. And automate covers the operations work that used to need a fragile RPA script, where an agent has to log into a dashboard, work through a flow, and pull something back out.

The common thread is that all of these need live web context, and none of the teams building them wants to own a scraping stack to get it.

Why you would reach for it over rolling your own

The honest answer is the abstraction. You are buying back the time you would otherwise spend on rendering, proxies, parsing, and the maintenance tail that follows all three. For most teams that maintenance tail is the real cost, because it never shows up in the estimate and never stops.

There is a second reason that is specific to Tabstack, and it is the Mozilla backing. The privacy posture is not an afterthought bolted on for the marketing page. Requests carry a dedicated Tabstack user-agent so site owners can identify the traffic, robots.txt opt-outs aimed at that agent are honoured, and retrieved content is treated as ephemeral and is never used to train models. If you care about being a responsible actor on the web, and increasingly you have to, that matters. It is web access that is built to be observable and well-behaved rather than a mass harvester wearing a disguise.

The third reason is just developer experience. Scoped API keys, a clean Bearer-token auth flow, two first-party SDKs, an MCP server, a CLI, and per-action cost shown in the console before you run anything. The "open in Claude, ChatGPT, or Cursor" buttons on every docs page tell you who they are building for. It feels like a product made by people who have actually had to integrate other people's APIs.

The pricing, plainly

Tabstack is credit-based, and I appreciate that one currency covers the whole platform rather than a separate line item for extraction versus research. Every call spends credits, and the cost depends on the endpoint and how hard you make it work.

The per-action rates are easy to hold in your head. Markdown extraction is ten credits, JSON extraction is fifty, generate is a hundred, automate is a hundred per action, fast research is two hundred and fifty, and balanced research is three hundred and fifty. The important wrinkle is that extract and generate are always a single action per call, so the cost is fixed and predictable, while automate and research chain as many actions as the task needs and bill for each one. A research call that touches more sources costs more than one that touches fewer. You pay for work done, not per request, which is fairer but does mean automate and research costs are variable by nature.

The plans are Individual at zero a month on pay-as-you-go, Team at ninety-nine a month with five hundred thousand credits, and Pro at four hundred and ninety-nine a month with three million. Overages are on by default for Team and Pro and are cheaper per credit than pay-as-you-go, and you can set a spend threshold in the console to either notify or stop. The free tier of ten thousand credits is enough to build something real before you commit, which is exactly how a trial should work.

Where it is rough, and who it is not for

I would be doing you a disservice if I only listed the good parts.

It is not interactive-fast. Extraction sits in the low single-digit seconds and automate or research can run considerably longer, because they are doing real multi-step work. That is fine for background automation and scheduled jobs. It is the wrong tool if you need sub-second responses inside a live user-facing interaction.

It is not built for true web-scale crawling. The credit model is comfortable for thousands to tens of thousands of calls. If your plan is to pull millions of pages a day, you are into custom infrastructure or a dedicated crawler, and the economics will tell you so quickly.

It is not a no-code tool, and it is not a consumer assistant. There is no visual workflow builder and no chat window you talk to. You write API calls. If you want point-and-click automation, this is not it, and if you want a research assistant to use yourself rather than to embed, you want a different category of product entirely.

The variable cost on automate and research is worth a flag too. Single-action endpoints are easy to budget. The agentic ones are not, by design, so you will want guardrails, sensible max-iteration caps, and an eye on the console while you learn the shape of your own workloads.

Where I land

Tabstack is doing something I genuinely respect, which is treating browsing as a distinct infrastructure problem and solving it properly rather than bolting a scraper onto an LLM and calling it a day. The schema-first extraction is the standout feature, the citation-backed research is the one I would build a product feature on, and the Mozilla privacy stance is the kind of thing that should be table stakes and somehow rarely is.

If you are building agents or AI features that need live web data and you do not want to own a scraping stack, it is straightforwardly worth your time. Start narrow. Pick one workflow, point it at the sites you actually care about, and see how the output holds up against your real targets rather than against a demo. The free credits make that an easy experiment to run, and the cost of finding out is close to nothing.

I will likely follow this with a walkthrough of building something small and real on top of the automate endpoint, because that is where the interesting edges live.

The Tips Behind API Artisan: Building Laravel APIs Developers Actually Want to Use

Steve McDougall — Tue, 16 Jun 2026 21:38:58 +0000

I have just finished writing API Artisan: A Guide to Building APIs with Laravel, and I am giving it away for free. Before you commit to 300-odd pages, let me give you the short version: the tips, patterns, and small decisions that separate an API that technically works from one that developers are genuinely happy to depend on.

None of this needs more hardware, a different framework, or a bigger team. It needs you to point your attention at the right things. These are the ones I keep coming back to.

Start by measuring the right thing

Ask most teams how they know their API is good and you get a single question back: does it work? Can I hit this endpoint and get a response? That question is necessary, and it is nowhere near enough.

The question I want you to ask instead is whether your API is liveable with. Can a developer read your docs, understand your auth model, make a successful request, and handle an error without contacting support, trawling a forum, or guessing what a status code is trying to tell them? The gap between "works" and "liveable with" never shows up in a sprint retro, but it shows up everywhere else: in support volume, in integration timelines that overrun, and in the quiet moment a developer decides to build around your API rather than with it.

Everything else in the book hangs off one mindset shift: an API is a product. It has users. Treat it as an implementation detail and it will behave like one. It will change without warning when your internals change, and it will be inconsistent because different people wrote different parts on different days with different conventions.

Write the contract before the code

The natural way to build an endpoint is to write the handler, return some data, and document it afterwards if there is time. It feels efficient, and in the short term it is. The problem is what it produces: a contract that was never designed, only discovered.

Let me show you the trap, because I have watched it catch good developers. You have a keys table with a revoked_at column, the Eloquent model is right there, so you reach for $key->toArray(). The response ships with revoked_at as a field name, because that is what the column is called. A few weeks later you realise the name is ambiguous and rename it. To every integration built against you, that rename is a breaking change, and nothing warned anyone.

Designing the response shape before you write the query closes that gap at the source. You cannot leak your schema if you worked out what the caller needs before you touched the database. The question changes from "how do I expose this data?" to "what does the developer calling this actually need?", and the answers genuinely differ.

Here is the asymmetry that makes the discipline worth it. Your implementation can be refactored whenever you like. A published field name lives in codebases you cannot see, running in production systems that will not be updated the day you push a change. So front-load the contract decisions. The cost of getting them wrong is real, and it is paid by other people, later, at the worst possible time.

Know what a breaking change actually is

Most of us can name the obvious ones: remove an endpoint, rename a field. The real list is longer and far more surprising, and every item on it breaks an integration even when the change looks like an improvement.

Changing a field's type, say expires_at from a date string to a Unix timestamp. Changing a field from nullable to non-nullable. Adding a required field to a request. Changing the meaning of a field without touching its name, which is the one that keeps me up at night. Changing error codes or error shapes, because clients build handling logic around them. Switching offset pagination for cursor pagination. Wrapping a collection in a meta object that clients were destructuring directly.

The pattern is always the same. A change that looks internal turns out to be a commitment you made to everyone who integrated with the old behaviour. The answer is not to stop changing things. It is to know what you are committing to before you commit, and to have a mechanism for changing it safely.

Version from day one

Here is a fact that surprises people: adding a /v1 prefix to an API that is already in production is itself a breaking change. Every consumer hitting /keys now has to hit /v1/keys. That is exactly why versioning from day one is not premature optimisation. It is the cheapest moment you will ever get to add it, because no integrations exist yet. The cost is one URL segment, and the payoff is a stable, versioned contract from the first endpoint you ship.

Make the version explicit at every level, not just in the URL. Namespace your controllers under App\Http\Controllers\Keys\V1. When v2 arrives it lives in Keys\V2, the v1 controllers stay exactly as they are, and you physically cannot put v2 logic in a v1 controller because the boundary is visible in the code.

When you do retire a version, reach for the Sunset pattern from RFC 8594. Send a Sunset header carrying the retirement date and a Deprecation header carrying the date it was deprecated. The part almost everyone skips is the Link header pointing at the migration guide, and it is the part that earns its keep. A consumer whose monitoring picks up the Sunset header can follow that link straight to the docs. The header becomes actionable instead of just informational. My rule, and the one I would encourage you to adopt, is that no version retires without at least six months of notice.

Treat REST as conventions, not religion

Let me save you some pull request arguments. Almost nobody implements true hypermedia controls, and almost every "REST API" you have ever used is really HTTP with JSON and some conventions about URLs. That is fine. The conventions are useful. The pretence that we are all implementing a rigorous architectural style is not.

So skip HATEOAS, unless you happen to be building a generic hypermedia browser, which you are almost certainly not. Stop treating the Richardson Maturity Model as a quality score. A level 3 API with inconsistent errors and no docs is a worse API than a level 1 one with a thoughtful, stable contract.

Spend that energy on your status codes instead, because they are part of your contract and clients build retry logic directly on them.

201 not 200 for a creation, so clients can read the Location header
422 not 400 for validation, because 400 means malformed and 422 means well-formed but invalid
403 not 401 when the caller is authenticated but not authorised

Confuse 401 and 403 and you create genuine bugs. A client that gets a 401 may try to re-authenticate. If it should have been a 403, re-authentication will not help, and now your client is sitting in a retry loop wondering what it did wrong.

For the operations that refuse to map to CRUD, like revoking or rotating a key, use sub-path actions: POST /v1/keys/{id}/revoke. Is it pure REST? No. Is it immediately understandable to anyone who reads it? Yes, and that is the trade I will take every time. On nesting, the rule I use is simple: nest one level when it clarifies ownership, and flatten when the nested resource has its own identity.

Make the controller boring

Every controller in the book is a single-action invokable class. One class, one __invoke method, one responsibility. IssueController tells you exactly what it does. KeyController tells you almost nothing.

A handful of small decisions compound here. Reference your controllers as a class, never a closure, because closures cannot be route-cached and a class reference is testable and navigable in your editor. Put declare(strict_types=1) at the top of every file. Mark controllers final. Keep validation in Form Requests and out of the handler, so the framework's automatic failure handling applies cleanly and you never end up with validation logic smeared between rules() and the top of a controller method.

The single best trick in the Laravel section is the payload() pattern. A Form Request's job is not only to validate input, it is to turn that validated input into a typed, immutable value object the rest of your application can trust.

public function payload(): IssueKeyPayload
{
    return new IssueKeyPayload(
        name:      $this->string('name')->toString(),
        scopes:    $this->collect('scopes')->map(KeyScope::from(...)),
        expiresAt: filled($this->input('expires_at'))
            ? CarbonImmutable::parse($this->string('expires_at')->toString())
            : null,
    );
}

Because payload() runs only after validation has passed, it can cast with confidence. KeyScope::from(...) will not throw, because the rules already confirmed every value is a valid enum case. Your controller receives a typed payload, hands it to an action, and returns a resource. The action works in domain types and never touches the request layer, which means it behaves identically whether you call it from a controller, a console command, a queue job, or a test. The payload is the handshake between HTTP and your domain, and it seals a boundary that otherwise quietly leaks.

Give every error the same shape

Out of the box, Laravel hands you a different response shape for a validation error, an unauthenticated request, and a missing model. Four situations, four shapes, and a client that wants consistent error handling has to special-case every one of them.

Pick RFC 9457 Problem+JSON and use it for every error on every endpoint, with no exceptions. One shape, carrying type, title, status, and detail, plus an errors extension when you need per-field validation. Two details are worth stealing outright. Set the Content-Type to application/problem+json so clients can detect it programmatically. And in your fallback Throwable handler, return null outside production, so Laravel keeps showing you full stack traces in development while production returns a clean, generic 500 that never leaks your internals.

Make invalid states impossible

When a resource has a lifecycle, model it as an enum-backed state machine with an explicit transition map. Invalid transitions throw a domain exception. The calling layer does not check the state before it acts; the entity enforces its own rules. That is the whole difference between a system that guarantees its own invariants and one that relies on developers remembering to check a field first.

Treat your domain exceptions, things like InvalidKeyTransitionException, as first-class citizens. They are not unexpected failures, they are known and named outcomes, and they deserve an informative 422 rather than a 500. Register them in your exception handler right alongside the framework ones.

Respect transaction boundaries

A database transaction protects you when a group of operations must all succeed or all fail together. It cannot protect you from everything, and two rules will save you real production pain.

Never make external HTTP calls inside a transaction. If the call fires and the transaction then rolls back, you have caused a side effect the database has no memory of. Push your jobs and webhooks with DB::afterCommit() so they only fire once the data is genuinely committed.

Transactions also cannot help when the network drops after you return a 201 but before the client receives it. The client retries, and you happily process the same operation twice. That is what idempotency keys are for. Accept a client-generated Idempotency-Key header on state-changing endpoints, store the original response, and replay it on any retry that carries the same key.

Build the audit log first, literally

An audit log is not a log file. It is an append-only database table of meaningful domain events: a key was issued, a key was revoked, a member was invited. Append-only is not a polite convention either, it is enforced by the schema. No updated_at, no soft deletes, no update operations anywhere in the code that touches it. A record you can update is not an audit record, it is a mutable row with a timestamp, and those are very different things.

Two design notes I would not skip. Store the event-specific context as JSONB rather than forcing every event type into a fixed set of nullable columns, because the relevant metadata is genuinely different for each one. And capture actor_type as well as actor_id, because an action taken by a human, by an API key, and by the system itself are three different stories in a security review.

The sequence inside every action that records an event is worth memorising: begin the transaction, perform the operation, write the audit record, commit, then dispatch side effects via afterCommit. The audit record is written before anything that could fail independently, which is what makes it the most durable thing in the whole system.

Make the system answer questions under pressure

Attach a request ID to every log line with a tiny piece of middleware.

$requestId = $request->header('X-Request-ID') ?? Str::uuid()->toString();
Log::withContext(['request_id' => $requestId]);
$response = $next($request);
$response->headers->set('X-Request-ID', $requestId);

Now every log entry within a request shares one ID, tracing a request becomes a single filter, and because you echo the ID back in the response header, a consumer reporting a problem can hand you the exact value to search for. One field, every relevant entry.

The rest of operability runs on the same instinct. Go spec-first with OpenAPI so your documentation cannot drift away from your implementation. Run contract tests in CI so an accidental breaking change fails the build instead of a consumer. Treat onboarding as part of the API, with runnable collections rather than a wall of prose. Give the API a clear owner, a deprecation cadence you actually review twice a year, and post-mortems that produce a test or a doc rather than blame.

The thread that ties it together

The patterns are not really the point. The reasoning is. Consumer empathy as an engineering discipline, stability as a feature you ship, observability as an architectural guarantee. Frameworks and conventions will change underneath all of us. That reasoning is durable, and it is what lets you make these same calls on your next project because the system needed them, not because a book told you to.

Every tip here is drawn from a single project I build end to end across the book: Portkey, a production-quality API key management platform with versioning, separate JWT and HMAC layers, an enforced key lifecycle, async rotation, signed webhooks, idempotency, rate limiting at three levels, and a Pest suite with contract tests in CI. Every pattern shows up because the project genuinely needed it, never to show off a technique.

If these notes were useful to you, the full book takes each one apart properly, with the code, the trade-offs, and the reasoning behind every decision. It is free. Download API Artisan and go build the API your consumers deserve.

Giving your agents a terminal: a first look at the tabstack CLI

Steve McDougall — Tue, 16 Jun 2026 21:38:57 +0000

Every project I touch lately ends up needing the same awkward thing: a reliable way to pull the web into a script or an agent. Not a brittle scrape held together with CSS selectors and hope, but something that takes a URL and hands back clean, structured text I can actually pipe into the next step. I have built that wrapper more than once, and it is never as small as you think it will be. So when Mozilla dropped the tabstack CLI, a single Go binary that wraps the Tabstack AI API, I wanted to spend a proper afternoon with it.

The pitch on the README is direct: every web interaction your agent or stack needs, from the terminal or a script. It turns any URL into clean Markdown or schema-shaped JSON, runs natural-language browser automation, and answers research questions with cited sources. The part that made me sit up is that the output is pretty in a terminal and pipeable into jq without a flag. That is a small detail, and it tells you the people who built it actually live on the command line.

Let me walk you through it the way I poked at it myself.

Getting it installed

There is no runtime to install and nothing to bootstrap, because it ships as a single static binary built for macOS, Linux, and Windows. The quickest route is the install script:

curl -fsSL https://tabstack.ai/install.sh | sh

That fetches the right binary for your platform and puts it on your PATH, and you are ready to go. If you would rather not pipe a script into your shell, there are a couple of alternatives. With Go on your machine you can use:

go install github.com/Mozilla-Ocho/tabstack-cli/cmd/tabstack@latest

That drops the binary in $GOPATH/bin, which is usually ~/go/bin. If your shell cannot find tabstack afterwards, you almost certainly have not got that directory on your PATH:

export PATH="$HOME/go/bin:$PATH"

And if you want to avoid Go entirely, there are pre-built binaries on the Releases page, or you can clone the repo and run make install-local, which builds it and copies it to /usr/local/bin so it works in any terminal straight away. Several routes, all of them boring in the best possible way.

Authentication done sensibly

This is the bit I want to praise first, because credential handling is where a lot of CLIs get careless. You log in once:

tabstack auth login            # prompts for the key, input hidden, saved to the config file
tabstack auth status           # shows how your key is being resolved, never prints it

A key can come from three places, and the precedence is exactly the order you would hope for:

the --api-key flag
the TABSTACK_API_KEY environment variable
the config file at $XDG_CONFIG_HOME/tabstack/config.toml, defaulting to ~/.config/tabstack/config.toml

The config file is written 0600, so it is not world-readable, and auth status will tell you which source won without ever leaking the value. This is the contract I want from any tool that holds a secret: a flag for one-off overrides, an environment variable for CI, and a locked-down file for everyday local use. If no key is found, the API commands exit with code 2 and tell you how to set one, rather than failing with a stack trace. We will come back to those exit codes, because they matter.

The core: turning a page into something useful

Every command follows the same shape: tabstack <group> <action> <target>. Once that clicks, the whole surface area feels predictable.

The first thing I reached for was extract. At its simplest it converts a page to clean Markdown:

tabstack extract markdown https://example.com --metadata

The --metadata flag pulls in the title, author, and similar bits alongside the content. Useful, but the version I keep coming back to is structured extraction, where you hand it a JSON schema and it shapes the output to match:

tabstack extract json https://example.com --schema @schema.json
tabstack extract json https://example.com --schema '{"type":"object","properties":{"title":{"type":"string"}}}'

Notice the @schema.json syntax. That @file convention reads the schema from a file, and it works the same way for the other input flags too. You can pass a literal string, point at a file with @, or read from stdin with -, which is the same ergonomics as curl -d. So this is perfectly valid:

echo '{"type":"object"}' | tabstack extract json https://example.com --schema -

If you have ever written the glue that decides "is this argument a path or a literal", you will appreciate that they solved it once and applied it everywhere.

Generate: extraction with an opinion

Where extract pulls what is on the page, generate fetches a page and transforms it with AI into the shape you describe. You give it instructions as well as a schema:

tabstack generate json https://example.com \
  --instructions "Summarise the article and list the key points." \
  --schema @schema.json

The mental model I landed on is this: extract json is for getting the data that is genuinely there, and generate json is for asking a model to produce something new from the page, summaries, classifications, restructured points, while still constraining the output to a schema you control. Keeping those two as separate verbs is a good call, because it stops you reaching for the heavier, slower path when all you wanted was the title.

Agents: automation and research

This is where it stops being a fetch tool and starts being something more interesting. The agent group runs server-side and streams progress back as it works.

Browser automation takes a natural-language task:

tabstack agent automate "Find the pricing for the Pro plan" --url https://example.com

Research searches the web, synthesises an answer, and prints a report with numbered, cited sources:

tabstack agent research "What are the latest developments in quantum computing?" --mode balanced

The feature I did not expect, and rather liked, is interactive automation. You can start a run that is allowed to pause and ask you for input partway through:

tabstack agent automate "Log in and download the latest invoice" --url https://example.com --interactive

When it pauses, it gives you a request ID, and you answer it with a separate command:

tabstack agent input <request-id> --data '{"fields":[{"ref":"field1","value":"yes"}]}'

Or you decline:

tabstack agent input <request-id> --data '{"cancelled":true}'

That agent input command only applies to runs started with --interactive. Without the flag, an automation never stops to ask. It is a clean way to handle the reality that some tasks genuinely need a human in the loop, without baking that assumption into every run.

The part that makes it scriptable

Here is the design decision I keep telling people about. The output is pretty and styled when you are sitting at a terminal, and it switches to JSON automatically when the output is piped. No flag required:

tabstack extract markdown https://example.com | jq .

You can force a mode with -o pretty or -o json if you want to be explicit, and you can kill colour with --no-color or the NO_COLOR environment variable. The streaming commands, automate and research, emit one NDJSON line per event when they are in JSON mode, so you can process events as they arrive rather than waiting for the whole thing to finish.

The other half of scriptability is the exit codes, and they are thought through:

Code	Meaning
`0`	success
`1`	runtime or network error
`2`	usage, invalid input, or missing config such as no API key
`3`	API error or in-band task failure

Distinct codes mean you can branch on the actual cause in a shell script, telling a bad argument apart from a network blip apart from an API rejection:

if ! tabstack extract markdown "$url" > out.md; then
  case $? in
    2) echo "check your arguments" ;;
    3) echo "the API rejected the request" ;;
    *) echo "network or runtime error" ;;
  esac
fi

I cannot tell you how often I have wanted exactly this from a tool and been handed a flat exit 1 for every conceivable failure instead.

A few common options round it out. --effort lets you pick the speed and capability tradeoff on extract and generate: min is fastest with no fallback, standard is the balanced default, and max does full browser rendering for JavaScript-heavy sites at the cost of taking longer. --geo GB routes the fetch through a given country using an ISO 3166-1 alpha-2 code, which is handy when a page behaves differently by region. And --nocache bypasses the cache when you need a fresh read.

Built to be driven by agents too

The detail that tells you where this is headed is the AGENTS.md file in the repo. The CLI is designed to be driven by LLM agents as well as humans, and that file documents every command, flag, and exit code in a form tuned for machine consumption. If you are wiring tabstack into Claude Code or your own harness, you point the agent at that file and let it learn the surface area itself.

This is the right shape for the moment we are in. A well-behaved CLI with predictable verbs, machine-readable output, and meaningful exit codes is exactly the kind of tool an agent can use safely, because every outcome is legible. The same properties that make it pleasant for me at the terminal make it tractable for a model in a loop.

Would I reach for it?

Yes, and for a specific reason. The web-access problem keeps showing up in my work, and I have written enough of these wrappers to know the unglamorous parts: credential precedence, the file-or-literal-or-stdin question, knowing whether a failure was mine or theirs, behaving differently when piped. The tabstack CLI has answered all of those the way I would want them answered, and it has done it in a single binary with no runtime to manage. It is v1.0.0, MIT licensed, and it came out of Mozilla, so it is not a weekend experiment you are betting your pipeline on.

If your stack or your agents need to read the web, give it an afternoon. Start with tabstack auth login and tabstack extract markdown on a page you know, and build out from there. The shape of the thing rewards exploration.

I have a feeling the interesting work is not in the extraction at all, but in what you wire on the other end of that pipe. That is the article I want to write next.

The Art Of Keeping Business Logic Honest

Steve McDougall — Wed, 20 May 2026 18:55:24 +0000

There is a moment in most long-lived applications where you open a controller and find a block of conditionals that nobody quite understands anymore. Something like if ($entity->status === 'pending' && $this->someFlag) buried inside a service class, half-guarding a transition that was probably fine when someone wrote it but now nobody wants to touch. The business logic has drifted from the code, and the code is quietly lying about what the system actually does.

I have been building a platform recently where I could see this problem coming from a long way off. The domain has entities that go through well-defined lifecycles - things move through stages, transitions have rules, and when a transition happens, a bunch of other things need to follow. The instinct is to reach for a big use case class, or a service that handles everything in sequence. But that approach tends to collapse under its own weight as requirements change.

Instead, I ended up with a two-layer pattern: a strict state machine for each entity that owns nothing but transition rules, and a separate workflow engine that responds to those transitions and orchestrates the follow-on work. This article is about how that pattern holds together and why I think it is worth the setup cost.

The Problem With Ad-Hoc Status Management

Before getting into the pattern, it is worth being honest about what you are replacing. Most applications manage entity status as a string column and a handful of conditionals scattered across services. When you need to add a new status, you add it to the column's allowed values and start writing if checks wherever it matters. This works fine for simple lifecycles. It starts to hurt when:

You have 5+ statuses and a non-trivial transition graph
Different transitions need different side effects
Some transitions involve async operations that can fail halfway through
You need an audit trail of who triggered what and when

The state machine pattern addresses the first two. The workflow engine addresses the last two. Together they handle the full picture.

Layer One: The State Machine

A state machine in this pattern is deliberately narrow. Its only job is to know which transitions are legal and to produce a domain event when one is performed. It does not send emails. It does not touch the database. It does not call other services.

Here is what a simple order lifecycle might look like:

OrderStatus:
  draft -> submitted -> approved -> fulfilled
  submitted -> rejected
  approved -> cancelled

The entity enforces this. If you try to transition from draft directly to fulfilled, you get a domain exception - not a silent data integrity problem discovered six months later.

// src/Orders/Domain/Order.php

final class Order
{
    private OrderStatus $status;

    public function submit(): OrderSubmitted
    {
        if ($this->status !== OrderStatus::Draft) {
            throw new InvalidTransitionException(
                "Cannot submit an order in status {$this->status->value}."
            );
        }

        $this->status = OrderStatus::Submitted;

        return new OrderSubmitted(
            orderId: $this->id,
            submittedAt: new \DateTimeImmutable(),
        );
    }

    public function approve(string $approvedBy): OrderApproved
    {
        if ($this->status !== OrderStatus::Submitted) {
            throw new InvalidTransitionException(
                "Cannot approve an order in status {$this->status->value}."
            );
        }

        $this->status = OrderStatus::Approved;

        return new OrderApproved(
            orderId: $this->id,
            approvedBy: $approvedBy,
            approvedAt: new \DateTimeImmutable(),
        );
    }
}

Notice that each method returns a domain event rather than dispatching it. The calling layer - a use case - is responsible for taking that event, persisting it to an event log, and firing it into the Laravel event system. The domain entity stays clean.

// src/Orders/Application/ApproveOrder.php

final class ApproveOrder
{
    public function __construct(
        private readonly OrderRepositoryContract $repository,
    ) {}

    public function execute(string $orderId, string $approvedBy): array
    {
        $order = $this->repository->findById($orderId);
        $event = $order->approve($approvedBy);

        $this->repository->save($order);

        return [$event];
    }
}

// app/Http/Controllers/Orders/V1/ApproveController.php

public function __invoke(ApproveOrderRequest $request, string $orderId): JsonResponse
{
    $events = $this->approveOrder->execute($orderId, $request->user()->id);

    foreach ($events as $event) {
        $this->eventLog->record($event, $orderId, 'order', $request->user()->id);
        Event::dispatch($event);
    }

    return new JsonDataResponse(data: ['approved' => true]);
}

This separation matters more than it might look. The use case is testable without Laravel. The domain entity has no infrastructure dependencies. The event log gets written before any side effects fire, so you always have a record of what happened even if something downstream blows up.

Layer Two: The Workflow Engine

The state machine tells you that a transition happened. The workflow engine decides what to do about it.

A workflow is a named, ordered list of steps triggered by a domain event. Steps are discrete PHP classes. The engine runs them in order, persists progress after each one, and can pause mid-workflow waiting for an external signal before continuing.

A workflow instance is the running execution of a workflow definition for a specific entity. The definition - the list of steps - lives entirely in code. The instance - which step we are on, what has happened so far - lives in the database.

This distinction is important. Changing a workflow is a code change with a readable diff. You do not need a migration to add a step. The engine always uses the current definition code when it resumes a paused instance.

Defining a Workflow

// app/Workflows/OrderApproval/OrderApprovalWorkflow.php

final class OrderApprovalWorkflow implements WorkflowDefinitionContract
{
    public static function name(): string
    {
        return 'order_approval';
    }

    public function steps(): array
    {
        return [
            ValidateOrderItems::class,
            ReserveInventory::class,
            CreateInvoice::class,
            AwaitPayment::class,
            NotifyFulfillmentTeam::class,
        ];
    }
}

Every step implements the same contract:

interface WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult;
    public function timeoutSeconds(): ?int;
    public function maxAttempts(): int;
}

A step returns one of three outcomes: complete, await, or fail.

// src/Workflow/Domain/StepResult.php

final class StepResult
{
    private function __construct(
        public readonly string $outcome,
        public readonly ?string $awaitSignal,
        public readonly ?string $failReason,
        public readonly array $contextUpdates,
    ) {}

    public static function complete(array $contextUpdates = []): self
    {
        return new self('complete', null, null, $contextUpdates);
    }

    public static function await(string $signal, array $contextUpdates = []): self
    {
        return new self('await', $signal, null, $contextUpdates);
    }

    public static function fail(string $reason): self
    {
        return new self('fail', null, $reason, []);
    }
}

The AwaitPayment step, for example, does not poll an external payment service. It parks the workflow:

// app/Workflows/OrderApproval/Steps/AwaitPayment.php

final class AwaitPayment implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        return StepResult::await('payment_succeeded');
    }

    public function timeoutSeconds(): ?int
    {
        return 604800; // 7 days
    }

    public function maxAttempts(): int
    {
        return 1;
    }
}

The engine sets the instance status to awaiting, stores the signal name it is waiting for, and stops. When the payment provider's webhook arrives, it delivers the signal:

// app/Jobs/ProcessPaymentWebhook.php

$instances = $this->workflowRepository->findAwaitingSignalForAggregate(
    aggregateId: $orderId,
    signal: 'payment_succeeded',
);

foreach ($instances as $instance) {
    $this->engine->signal(
        instanceId: $instance->id,
        signal: 'payment_succeeded',
        signalData: [
            'payment_id' => $payment->id,
            'paid_at'    => now()->toIso8601String(),
        ],
    );
}

The engine resumes from the step after AwaitPayment and carries the signal data forward in the context. The NotifyFulfillmentTeam step can read payment_id from context without knowing anything about how payment was confirmed.

WorkflowContext: Shared State Without Shared Mutable State

Context is an immutable bag of data that flows through all steps. Steps cannot write directly to it - they return updates via StepResult::complete(['key' => 'value']) and the engine merges those in before passing context to the next step.

// src/Workflow/Domain/WorkflowContext.php

final class WorkflowContext
{
    private function __construct(
        public readonly string $workflowInstanceId,
        public readonly string $aggregateId,
        public readonly string $aggregateType,
        private readonly array $data,
    ) {}

    public function get(string $key, mixed $default = null): mixed
    {
        return $this->data[$key] ?? $default;
    }

    public function with(array $additions): self
    {
        return new self(
            $this->workflowInstanceId,
            $this->aggregateId,
            $this->aggregateType,
            array_merge($this->data, $additions),
        );
    }
}

This keeps steps honest. A step cannot accidentally clobber data set by a previous step except through the explicit return value. It also makes testing straightforward:

it('awaits payment signal when order is approved', function () {
    $context = WorkflowContext::make(
        workflowInstanceId: 'wf_001',
        aggregateId: 'ord_001',
        aggregateType: 'order',
        initialData: [],
    );

    $step = new AwaitPayment();
    $result = $step->execute($context);

    expect($result->outcome)->toBe('await');
    expect($result->awaitSignal)->toBe('payment_succeeded');
});

Each step is independently testable. You construct a context, run the step, assert the result. No Laravel bootstrapping required.

Branching Without a Tree Structure

Not all workflows are linear. Some paths depend on conditions that are only known at runtime, and this is where a lot of workflow implementations go wrong. The temptation is to model branching as a tree: if condition A, follow path X; if condition B, follow path Y. That works fine until you have three conditions and four paths, at which point you have a directed graph masquerading as code, and nobody can read it without drawing a diagram first.

My preference is context flags over nested step trees. The idea is simple: a routing step runs early in the workflow, evaluates the conditions, and writes its findings into context. Later steps read those findings and decide whether to skip themselves or do their work. The step list stays flat. You can read it from top to bottom and understand every possible path the workflow might take.

Here is a concrete example. An order workflow might need manual review for high-value orders, a compliance check for orders from certain regions, and expedited processing for customers on a priority tier. Rather than splitting into separate workflow definitions (which duplicates a lot of shared steps) or nesting conditional blocks inside the engine, a single routing step evaluates all of this upfront:

// app/Workflows/OrderApproval/Steps/RouteApproval.php

final class RouteApproval implements WorkflowStepContract
{
    public function __construct(
        private readonly CustomerRepositoryContract $customers,
        private readonly ComplianceService $compliance,
    ) {}

    public function execute(WorkflowContext $context): StepResult
    {
        $customer = $this->customers->findById($context->get('customer_id'));

        return StepResult::complete([
            'requires_manual_review'  => $context->get('order_value') > 10000,
            'requires_compliance_hold' => $this->compliance->requiresHold($customer->region),
            'is_priority_customer'     => $customer->isPriority(),
        ]);
    }
}

Later steps consume these flags independently. Each one is responsible for its own skip logic:

// app/Workflows/OrderApproval/Steps/AwaitManualApproval.php

final class AwaitManualApproval implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        if (! $context->get('requires_manual_review', false)) {
            return StepResult::complete();
        }

        return StepResult::await('manager_decision');
    }
}

// app/Workflows/OrderApproval/Steps/AwaitComplianceClearance.php

final class AwaitComplianceClearance implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        if (! $context->get('requires_compliance_hold', false)) {
            return StepResult::complete();
        }

        return StepResult::await('compliance_cleared');
    }
}

// app/Workflows/OrderApproval/Steps/NotifyFulfillmentTeam.php

final class NotifyFulfillmentTeam implements WorkflowStepContract
{
    public function __construct(
        private readonly NotificationService $notifications,
    ) {}

    public function execute(WorkflowContext $context): StepResult
    {
        $priority = $context->get('is_priority_customer', false);

        $this->notifications->notifyFulfillment(
            orderId: $context->get('order_id'),
            queue: $priority ? 'priority' : 'standard',
        );

        return StepResult::complete();
    }
}

And the workflow definition itself reads clearly, top to bottom:

public function steps(): array
{
    return [
        ValidateOrderItems::class,
        RouteApproval::class,          // sets context flags
        ReserveInventory::class,
        AwaitComplianceClearance::class, // skips if not required
        CreateInvoice::class,
        AwaitPayment::class,
        AwaitManualApproval::class,    // skips if not required
        NotifyFulfillmentTeam::class,  // uses priority flag
    ];
}

Reading that list, you can already build a mental model of what happens. A standard order hits RouteApproval, skips both await steps, and lands at NotifyFulfillmentTeam on the standard queue. A high-value order from a restricted region pauses twice before it gets there. A priority customer skips the holds but gets the priority queue at the end.

When the Context Flag Approach Breaks Down

It is worth being honest about the limits of this pattern. Context flags work well when branches share a significant chunk of their steps. If two paths genuinely have nothing in common beyond the trigger event, separate workflow definitions are probably the right call. Trying to force them into one definition just to keep things tidy results in a step list full of steps that almost always skip themselves, which is its own form of confusion.

The other case where context flags get awkward is when a branch decision depends on the outcome of an earlier awaiting step. Suppose a manual approval step can produce one of three decisions: approved, approved with modifications, or sent back for renegotiation. The step waiting for that signal needs to write the decision into context so the next step can act on it:

// app/Workflows/OrderApproval/Steps/AwaitManualApproval.php

final class AwaitManualApproval implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        if (! $context->get('requires_manual_review', false)) {
            return StepResult::complete(['approval_decision' => 'auto_approved']);
        }

        // Check if the signal has already been delivered (i.e. we are resuming)
        $decision = $context->get('approval_decision');

        if ($decision !== null) {
            return StepResult::complete();
        }

        return StepResult::await('manager_decision');
    }
}

When the signal arrives, the engine calls execute again with the signal data merged into context. The step finds approval_decision already set, returns complete, and the next step can read the decision and act accordingly. This is slightly counterintuitive at first - the step runs twice - but it keeps signal handling inside the step that owns that state, rather than leaking it into the engine or a separate handler class.

Reading Signal Data in the Next Step

Once the signal data is in context, consuming it downstream is straightforward:

// app/Workflows/OrderApproval/Steps/ProcessApprovalDecision.php

final class ProcessApprovalDecision implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        $decision = $context->get('approval_decision');

        return match ($decision) {
            'approved'              => StepResult::complete(['proceed' => true]),
            'approved_with_changes' => StepResult::complete(['proceed' => true, 'notify_changes' => true]),
            'sent_for_renegotiation' => StepResult::complete(['proceed' => false]),
            default                 => StepResult::fail("Unknown approval decision: {$decision}"),
        };
    }
}

Steps further down the chain check proceed and notify_changes as needed. The branching logic is distributed across the steps that care about it, rather than centralised in a router that has to know about everything.

Timeouts: When Waiting Is Not Infinite

Every awaiting step raises a question the engine cannot answer on its own: what happens if the signal never arrives? A payment that is never completed. A manager who goes on holiday without approving the order. A compliance team that sits on a request for three weeks. Real workflows have to handle these cases, and "wait forever" is rarely the right answer.

The timeout mechanism is built directly into the step contract. Every step declares how long it is willing to wait before something has to happen:

interface WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult;
    public function timeoutSeconds(): ?int;  // null means no timeout
    public function maxAttempts(): int;
}

When the engine parks a workflow at an awaiting step that declares a timeout, it dispatches a delayed job alongside the parking:

// Inside WorkflowEngine::handleAwait()

if ($timeout = $step->timeoutSeconds()) {
    TimeoutWorkflowStep::dispatch(
        instanceId: $instance->id,
        expectedSignal: $result->awaitSignal,
    )->delay(now()->addSeconds($timeout));
}

When the job fires, it checks whether the workflow is still waiting on the same signal. If the signal already arrived and the workflow advanced, the job finds a different state and does nothing. If the workflow is still parked, it delivers a synthetic timeout signal:

// app/Jobs/TimeoutWorkflowStep.php

final class TimeoutWorkflowStep implements ShouldQueue
{
    public function __construct(
        private readonly string $instanceId,
        private readonly string $expectedSignal,
    ) {}

    public function handle(WorkflowEngine $engine, WorkflowRepositoryContract $repository): void
    {
        $instance = $repository->findById($this->instanceId);

        if (! $instance->canReceiveSignal($this->expectedSignal)) {
            return;
        }

        $engine->signal(
            instanceId: $this->instanceId,
            signal: 'timeout',
            signalData: ['timed_out_signal' => $this->expectedSignal],
        );
    }
}

The step itself then decides what a timeout means for its context. This is the key design decision: the step owns the timeout behaviour, not the engine. The engine just delivers a signal. The step interprets it.

Timeout Behaviour Is Step-Specific

Different awaiting steps need very different responses to a timeout. A payment step timing out probably means the order should be cancelled. A manual approval step timing out might mean the workflow should auto-approve, or escalate, or just fail loudly and wait for human intervention. Making the step responsible for this means each one can handle it appropriately.

Here is a payment step that cancels the order on timeout:

// app/Workflows/OrderApproval/Steps/AwaitPayment.php

final class AwaitPayment implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        // Already resolved - either paid or timed out
        if ($context->get('payment_status') !== null) {
            $status = $context->get('payment_status');

            if ($status === 'timed_out') {
                return StepResult::fail('Payment window expired. Order will be cancelled.');
            }

            return StepResult::complete();
        }

        // Signal just arrived
        $signal = $context->get('_signal');

        if ($signal === 'timeout') {
            return StepResult::complete(['payment_status' => 'timed_out']);
        }

        if ($signal === 'payment_succeeded') {
            return StepResult::complete([
                'payment_status' => 'paid',
                'payment_id'     => $context->get('_signal_data.payment_id'),
            ]);
        }

        // First time through - park and wait
        return StepResult::await('payment_succeeded');
    }

    public function timeoutSeconds(): ?int
    {
        return 604800; // 7 days
    }

    public function maxAttempts(): int
    {
        return 1;
    }
}

Compare that to a manual approval step that auto-approves rather than failing when the window expires. The business rule here is that if a manager does not review within 48 hours, the workflow proceeds as though it were approved:

// app/Workflows/OrderApproval/Steps/AwaitManualApproval.php

final class AwaitManualApproval implements WorkflowStepContract
{
    public function execute(WorkflowContext $context): StepResult
    {
        if (! $context->get('requires_manual_review', false)) {
            return StepResult::complete(['approval_decision' => 'auto_approved']);
        }

        $signal = $context->get('_signal');

        if ($signal === 'timeout') {
            // Business rule: no response in 48h = auto-approved
            return StepResult::complete([
                'approval_decision' => 'auto_approved',
                'auto_approved_reason' => 'timeout',
            ]);
        }

        if ($signal === 'manager_decision') {
            return StepResult::complete([
                'approval_decision' => $context->get('_signal_data.decision'),
            ]);
        }

        return StepResult::await('manager_decision');
    }

    public function timeoutSeconds(): ?int
    {
        return 172800; // 48 hours
    }

    public function maxAttempts(): int
    {
        return 1;
    }
}

Two awaiting steps, two completely different timeout behaviours, zero timeout logic in the engine. The engine is just a postman. It delivers signals and persists state. It does not have opinions about what those signals mean.

Runtime-Configurable Timeouts

Hard-coding timeout values as constants in step classes is fine during early development but tends to become a problem in production. Business rules about payment windows and approval deadlines have a habit of changing, and changing them should not require a deployment.

The step contract is a PHP class, which means timeoutSeconds() can read from wherever it likes:

// app/Workflows/OrderApproval/Steps/AwaitPayment.php

final class AwaitPayment implements WorkflowStepContract
{
    public function __construct(
        private readonly SystemSettingsRepositoryContract $settings,
    ) {}

    public function timeoutSeconds(): ?int
    {
        return $this->settings->get('payments.window_days') * 86400;
    }
}

The service container resolves the step, injects the repository, and the timeout is read from the database at the moment the step executes. Change the setting, and the next workflow instance that reaches this step picks up the new value. Existing parked instances are not affected - their timeout job was already dispatched when they parked - but that is usually the right behaviour. You do not want a settings change to retroactively alter the expectations for workflows already in flight.

What About Timeouts on Timeouts?

One edge case worth thinking through: the TimeoutWorkflowStep job is itself a queued job, which means it can fail. If your queue worker crashes repeatedly and the job exhausts its retry attempts without ever firing, the workflow stays parked indefinitely. For most applications this is an acceptable risk - queue failures are rare and observable - but if you need a harder guarantee, a scheduled job that sweeps for instances whose timeout_at has passed and have not yet received a signal is a reasonable backstop. It trades immediacy for reliability: the sweep might fire 5 minutes late, but it will fire.

// app/Console/Commands/ExpireStaleWorkflowSteps.php

public function handle(WorkflowRepositoryContract $repository, WorkflowEngine $engine): void
{
    $stale = $repository->findTimedOutInstances(now());

    foreach ($stale as $instance) {
        $engine->signal(
            instanceId: $instance->id,
            signal: 'timeout',
            signalData: ['source' => 'sweep', 'timed_out_signal' => $instance->getAwaitingSignal()],
        );
    }
}

Running this as a scheduled command every few minutes means even a prolonged queue outage does not leave workflows stranded forever. The signal data includes a source flag so you can distinguish between a timeout that fired on time via the job and one that was caught by the sweep - useful for monitoring and alerting.

Connecting the Two Layers

The state machine and the workflow engine are connected by a Laravel event listener. The state machine fires a domain event. The listener starts a workflow.

// app/Providers/OrdersServiceProvider.php

public function boot(): void
{
    Event::listen(
        OrderApproved::class,
        StartOrderApprovalWorkflow::class,
    );
}

// app/Listeners/StartOrderApprovalWorkflow.php

final class StartOrderApprovalWorkflow
{
    public function __construct(
        private readonly WorkflowEngine $engine,
    ) {}

    public function handle(OrderApproved $event): void
    {
        $instance = $this->engine->start(
            workflowName: OrderApprovalWorkflow::name(),
            aggregateId: $event->orderId,
            aggregateType: 'order',
            initialData: [
                'order_value' => $event->orderValue,
            ],
        );

        AdvanceWorkflow::dispatch($instance->id);
    }
}

The engine and the state machine have no direct dependency on each other. The listener is the only thing that knows about both.

What the Database Stores

Two tables do the heavy lifting.

workflow_instances tracks a running execution. The key columns are status (running, awaiting, completed, failed, cancelled), current_step_index, awaiting_signal, and context as a JSON blob. When the engine persists between steps, it writes the new index and any context updates.

workflow_signals is an append-only log of every signal delivered to every instance. This gives you a complete record of what happened and when, including which user or system actor delivered each signal.

Because the engine persists before moving to the next step, a failed job always resumes from a known good state rather than re-running work that already succeeded. The AdvanceWorkflow job is safe to retry because the engine checks the current status before doing anything.

What This Pattern Buys You

After living with this for a while, a few things stand out.

The business logic becomes auditable. The state machine defines every valid transition explicitly. The workflow definition defines every step in a process explicitly. Anyone can read both and understand what the system does, without chasing conditionals through layers of service classes.

Async work is a first-class concept. The await mechanism makes it natural to model processes that span hours or days. Waiting for a payment, waiting for a human decision, waiting for an external API callback - these are all just signals. The workflow does not care whether they arrive in 50 milliseconds or 5 days.

Each piece is independently testable. Domain entities with no infrastructure dependencies. Steps that take a context and return a result. The engine with an in-memory repository. You can test the full logic of a workflow without touching the database or the queue.

Adding steps does not require touching existing ones. Inserting a new step into a workflow is a one-class change. The engine picks it up from the definition array. Existing steps are unaffected.

The setup cost is real. You are building an engine, not just writing business logic. But for domains with complex entity lifecycles and multi-step processes that need to survive failures, the investment pays back quickly. The alternative - a growing tangle of service classes, status checks, and jobs that only make sense if you know the history - tends to get more expensive with every feature added.

If you are working on something where entity status matters, where some transitions need to trigger chains of work, and where some of that work is async, this pattern is worth considering. The state machine gives you confidence that your data is always in a valid state. The workflow engine gives you confidence that the work that follows a transition always happens in the right order, even when things go wrong in the middle.