DEV Community: kevariable

Your Laravel queue worker count is a guess. Here is the math that replaces it.

kevariable — Fri, 21 Aug 2026 07:29:39 +0000

Every Laravel deployment I have seen has a line like this somewhere:

[program:queue-worker]
numprocs=10

Why 10? Nobody knows. Someone picked it years ago and it stayed. Too low and
jobs wait minutes during a campaign blast. Too high and you burn RAM all night
for workers doing nothing. The number is wrong in both directions because load
changes and the config does not.

I spent this week testing an alternative on a demo app:
cboxdk/laravel-queue-autoscale
with cboxdk/laravel-queue-metrics,
built by Sylvester Damgaard, who worked on the queue manager at Laravel. Instead
of a worker count, you declare a promise, and the count is derived. These are my
measured results.

The formula

You declare one thing, an SLA: "a job on this queue must be picked up within
10 seconds." Then every 5 seconds a manager process solves:

workers = (pending jobs / SLA seconds) / jobs per second per worker

Read it in two steps. pending / SLA seconds is the throughput you need: 3,000
pending jobs with a 10s promise means you must process 300 jobs per second.
Divide by what one worker can do (my demo job takes ~100ms, so ~10 jobs/s) and
you get 30 workers. Same reasoning as "I need to move 300 boxes per hour, one
person moves 10, so I need 30 people."

This is Little's Law from queueing theory, the same 1961 theorem behind checkout
lines and CPU schedulers. The insight is that the only input a human provides
is a business question (how long may a job wait?) instead of a technical guess
(how many processes?).

If you have ever sized a PHP-FPM pool with
max_children = RAM / avg process size, this is the identical idea. Measure
one unit, derive the count. Web requests spend memory, queue jobs spend time.

Setup

composer require cboxdk/laravel-queue-autoscale cboxdk/laravel-queue-metrics
php artisan vendor:publish --tag=queue-autoscale-config

// config/queue-autoscale.php
'queues' => [
    'orders' => [
        'connection' => 'redis',
        'sla' => ['target_seconds' => 10],
        'workers' => ['min' => 1, 'max' => 16],
    ],
],

Then run php artisan queue:autoscale. It spawns and kills plain
php artisan queue:work processes, the same command you would run by hand. The
workers do not know the autoscaler exists.

Two gotchas that cost me time: the manager needs ext-pcntl (and v4 also
ext-posix), and each queue entry needs an explicit 'connection', otherwise
it silently looks for a queue connection literally named default and every
evaluation fails into the log.

Measured: 3,000 jobs hit the queue

I dispatched 3,000 jobs of ~100ms at once against the 10s SLA and sampled every
5 seconds:

t	workers	pending
0s	1	3,000
5s	6	2,910
10s	10	2,619
15s	14	2,209
25s	16 (cap)	956
35s	16	0

The formula asked for 30 workers; my configured cap of 16 won (the package also
caps by measured host CPU and RAM, so it will not scale past what the machine
carries). All 3,000 jobs completed, none lost, and on SIGTERM every worker
finished its in-flight job before dying. Scale-down afterwards is deliberately
slow, one worker per cycle with an anti-flapping cooldown, so a bursty queue
does not yo-yo.

The part that impressed me: an outage is not load

Here is the trap with any naive autoscaler. Your payment provider dies. Every
job fails and retries. The backlog grows. The math screams "add workers!" and
now 16 workers are hammering a dead API, which helps nobody.

I simulated it: 2,000 jobs that all throw. The manager logged this:

fuse OPEN: 100.0% failure rate over 28 jobs, holding at workers.min instead
of scaling into the failure; backlog=1999 requires 999.5 workers to prevent
SLA breach

The backlog math demanded 999.5 workers. The failure fuse allowed 1. It
detects that the failure rate (not the backlog) is the real signal, pins the
queue at minimum, and uses that one worker as a probe. When my jobs stopped
failing, the failure window aged out, the fuse closed itself (0% over 387
jobs) and normal scaling resumed. No restart, no human.

That single log line, "999.5 demanded, 1 allowed", is the difference between
an autoscaler and a bash script.

Do 16 workers on one queue conflict?

No, and it is worth understanding why. When a worker claims a job, Laravel runs
a Lua script in redis that pops the job from the pending list AND writes it to
a reserved set as one atomic operation. Redis runs Lua single-threaded, so two
workers can never claim the same job.

But the guarantee is at-least-once, not exactly-once. Reservations have a
timeout (retry_after, default 90s): if a worker dies mid-job, the job returns
to pending and runs again. So the rules stay the same as always: make jobs
idempotent, keep retry_after longer than your slowest job, and reach for
ShouldBeUnique / WithoutOverlapping when the business logic needs it.

What about Horizon?

Different question. Horizon balances workers ACROSS queues, but the pool size
is still maxProcesses, a number you pick. The autoscaler derives the number
itself. They are not competitors; the gap in both worlds was never balancing,
it was that someone still picks the number.

Honest tradeoffs

It scales processes on one host, not machines. Multi-host needs its cluster mode; on Kubernetes you might prefer scaling pods.
Young project, one maintainer. I found a real bug during testing (the metrics package's Prometheus endpoint reads keys its own DTO does not write).
The manager itself needs supervising (systemd or a container restart policy), and it should run continuously: a freshly restarted manager has no measurements and ramps lazily for a minute while it re-learns.
v4 needs PHP 8.4+, ext-pcntl and ext-posix. No Windows dev machines.

The takeaway

Worker counts, like FPM pool sizes, are derivable numbers that we have been
configuring by folklore. Declare the promise, measure the unit, let the math
run every 5 seconds. My queue now answers a question my config never could:
"how many workers do I need right now?"

Exactly as many as the backlog says. And when everything is on fire, exactly
one.

igbinary: half the Redis memory for one line of config

kevariable — Thu, 20 Aug 2026 10:13:08 +0000

Everything PHP stores in Redis gets serialized first: sessions, cache entries, queued jobs. PHP's native serialize() produces a verbose text format, and most of us never think about it. igbinary is a PHP extension that swaps in a compact binary format instead, and you enable it with one config line, your code does not change.

I benchmarked it properly on a Laravel app (PHP 8.4, phpredis 6.3, Redis 7), and one of the results confused me enough that figuring it out taught me more than the benchmark itself.

Where it plugs in

phpredis:

$redis->setOption(Redis::OPT_SERIALIZER, Redis::SERIALIZER_IGBINARY);

Laravel, one line in config/database.php:

'redis' => [
    'options' => [
        'serializer' => Redis::SERIALIZER_IGBINARY,
    ],
],

Native PHP sessions and APCu, in php.ini:

session.serialize_handler = igbinary
apc.serializer = igbinary

The benchmark

Four payloads: a realistic session array (~2.7KB: user profile, cart, tokens, flash), a single product row, a 100-product list (~35KB), and a 1000-element nested array (~125KB). Each serialized with native serialize(), igbinary_serialize(), and json_encode() for reference, then the session payload pushed through a real Redis round-trip both ways.

Size first:

payload	serialize	igbinary	json
session ~2.7KB	2,774 B	1,462 B (-47%)	1,901 B
100 products ~35KB	35,508 B	16,112 B (-55%)	27,971 B
nested ~125KB	125,184 B	39,557 B (-68%)	83,176 B

Unserialize throughput (ops/sec):

payload	serialize	igbinary
session ~2.7KB	287k	257k (slightly slower!)
100 products	33.3k	43.0k (+29%)
nested	3.2k	6.2k (+94%)

And the part that actually matters, the same session payload through Redis via phpredis:

	PHP serializer	igbinary
Redis MEMORY USAGE per session	3,128 B	1,592 B (-49%)
1,000 sessions	3,047 KiB	1,547 KiB
SET ops/s	15,145	15,864 (+5%)
GET ops/s	15,895	16,771 (+6%)

JSON, for the record, was bigger than igbinary and slower to decode in every single test.

The puzzle: why is the small payload slower but the big ones faster?

This is the result that confused me. igbinary unserialize was 10% slower on the session but 29% faster on the product list and 94% faster on the nested array. Same extension, opposite outcomes. Why?

Two forces are competing:

igbinary pays a fixed cost per call. It sets up a string table (for its deduplication) on every serialize and unserialize. On a tiny 2.7KB payload, that fixed cost is a meaningful share of the total time, and PHP's native format, a dumb linear text scan, is genuinely fast at small sizes.

igbinary wins on repetition. The 100-product list repeats the same eight keys (id, name, sku, price...) a hundred times. igbinary interns each string once and back-references it, so decoding allocates those keys once. Native unserialize re-parses and re-allocates every repeated key, all 800 of them. Plus igbinary walks half the bytes and reads binary type tags instead of parsing ASCII numbers. The nested array amplifies the same effect.

The session payload has almost no repetition relative to its size (tokens, emails, random strings are unique), so it gets the fixed cost without the dedup payoff.

Rule of thumb that falls out: CPU cost is a wash on small unique data, and wins big on anything with repeated structure, which is most real application data.

The microbench is not the pipeline

Here is the thing though: even for the "slower" session payload, the end-to-end Redis round-trip was FASTER with igbinary. +5% on SET, +6% on GET.

Because the microbench measures CPU only. The pipeline pays for bytes: bytes serialized, bytes on the wire, bytes Redis parses and stores, bytes coming back. Halving the payload beats a ~100 nanosecond CPU difference every time. And per real request you unserialize a session once, 0.004ms, invisible next to a multi-millisecond request, while the 49% Redis memory saving is permanent.

The usage pattern that matters is "serialize rarely, unserialize often", and reads are where igbinary is strongest.

Tradeoffs

Binary and PHP-only: not readable in redis-cli, and nothing except PHP with the extension can decode it. Use JSON where other languages consume the data
Every reader needs ext-igbinary: all app servers, workers, cron boxes
Switching serializers makes existing entries unreadable: flush the cache or session store when migrating
Object semantics are preserved (__sleep, __wakeup, references), so behaviour is drop-in
Pairs well with phpredis compression (Redis::OPT_COMPRESSION, LZ4/ZSTD) for large values

Takeaway

One line of config. Sessions take half the Redis memory, payloads shrink 47-68%, reads get faster on real data shapes, and the round-trip gains a few percent on top. The only real costs are operational: the extension everywhere, and a flush when you switch.

Size is what scales. CPU differences at these speeds are noise; half the RAM and half the bytes on the wire are not.

Other people's benchmarks

igbinary's own suite: https://github.com/igbinary/igbinary/blob/master/benchmark/comparisons.php
native vs json vs igbinary vs msgpack on session-like arrays: https://gist.github.com/spajak/d07a999deb0430e2b6b7e58fc44213d1
Drupal field reports (10-30% faster pages, ~50% less unserialize time): https://www.drupal.org/project/redis/issues/2143149
Ilia Alshanetsky, "Igbinary, the great serializer": https://ilia.ws/blog/igbinary-the-great-serializer

PHP-FPM vs FrankenPHP classic vs Octane worker

kevariable — Thu, 20 Aug 2026 10:12:17 +0000

The same Laravel app, served three ways. Same code, same database, same box.
The only difference is what happens between "request arrives" and "your
controller runs", and that difference is worth 3.5x.

What each one actually does per request

PHP-FPM (processes)

request -> nginx -> FastCGI -> a worker PROCESS picks it up
        -> execute index.php from opcache
        -> boot Laravel (container, providers, config, routes)
        -> your controller
        -> throw the app state away, worker waits for next request

One process = one request at a time. The pool grows and shrinks
(pm=dynamic: fork when idle < min_spare, kill when idle > max_spare).
Every request pays the full framework boot.

FrankenPHP classic (threads)

request -> Caddy (same binary) -> a THREAD picks it up
        -> execute index.php from opcache
        -> boot Laravel        <- still pays this
        -> your controller
        -> throw the app state away

Threads instead of processes: no fork cost, shared opcache, one binary with
the web server built in. But the app still boots per request, so per-request
work is nearly the same as FPM. Thread count defaults to 2x CPU cores.

Octane worker (kept-warm)

boot ONCE: Laravel container, providers, config, routes -> keep in memory

request -> Caddy -> a warm worker
        -> your controller     <- straight to it
        -> reset request state, keep the app

The framework boot happens once per worker lifetime, not once per request.
Requests only pay for their own work.

The numbers (same endpoint, 50 VUs, 30s, zero failures)

runtime	throughput	avg latency
PHP-FPM	723 rps	69 ms
FrankenPHP classic	618 rps	81 ms
Octane worker	2,516 rps	20 ms

The gap between FPM and classic is small: opcache already removed the
compile cost, so both are dominated by the same framework boot. The gap to
the worker is the boot itself: that is what "keep the app in memory" buys.

How to prove which mode you are in

A static counter survives requests only if the app survives requests:

Route::get('/runtime', function () {
    static $served = 0;
    $served++;
    return ['requests_served_by_this_worker' => $served];
});

FPM: always 1
classic: always 1
worker: 1, 2, 3, 4... across calls

If the counter climbs, the app never died between requests. Simplest worker
mode debug tool there is.

Sizing: the two formulas

FPM scales by memory: max_children = (RAM for PHP x 0.9) / avg process size (each worker is a full process, ~37 MB for a Laravel API, 250+ MB for a heavy CMS)
Workers scale by cores: workers = 2 x CPU cores as the starting point (io-heavy apps 2-4x, pure cpu 1x). Threads = workers + a few spare for statics.

Different resource, different formula. Mixing them up is a common mistake.

What it costs you: state persists

In worker mode the app never dies, so anything static or global carries over
between requests: memoized singletons, static caches, leaking event
listeners. Laravel and Octane reset the framework side, but your own statics
are your problem. This is THE tradeoff for the 3.5x.

Both runtimes also recycle workers on purpose (FPM pm.max_requests, Octane
--max-requests): a leak cannot grow forever if the worker does not live
forever.

When to use which

FPM: the default, battle-tested, per-request isolation means no state bugs, fine for most apps
FrankenPHP classic: FPM ergonomics (boot per request, no state risk) with a single-binary deploy and built-in web server
Octane worker: when latency and throughput matter and you are willing to own the state discipline - the 3.5x is real

Understanding PHP-FPM's process manager (by actually watching it)

kevariable — Thu, 20 Aug 2026 09:05:10 +0000

I thought I understood pm = dynamic until I sat down and watched it work in real time. It turns out the whole process manager is one tiny loop, and once you see the loop, every number in fpm-status suddenly makes sense.

This is what I learned, with real outputs from a real server.

The config

pm = dynamic
pm.max_children = 300        ; hard ceiling on total workers
pm.start_servers = 5         ; workers created at boot
pm.min_spare_servers = 5     ; never fewer than 5 idle
pm.max_spare_servers = 50    ; never more than 50 idle
pm.max_requests = 1000       ; recycle each worker after 1000 requests

The whole algorithm is one loop

FPM's master process runs one check, roughly every second:

How many workers are idle? Fewer than min_spare_servers? Fork one. More than max_spare_servers? Kill one. Otherwise, do nothing.

That is it. Everything below falls out of this one rule.

The mystery of the 6th worker

I booted FPM with start_servers = 5 and immediately saw 6 workers. Where did the extra one come from?

t=0  boot
     5 workers, all idle
     check: 5 idle. fine.

t=1  a request comes in
     1 busy + 4 idle = 5 total
     check: 4 idle < 5 min -> FORK ONE

t=2  1 busy + 5 idle = 6 total
     check: fine.

t=3  request done
     0 busy + 6 idle = 6 total
     check: 6 > 50 max? no -> do nothing

And there it stays: 6.

The part everyone misses is t=3. FPM never shrinks back to start_servers. The kill rule only fires above max_spare_servers. Between the two bounds, the pool simply stays wherever demand pushed it. It ratchets up easily and trims lazily. start_servers only matters for the first second of the pool's life.

Watching it happen

Two seconds after a restart:

start since:          2
idle processes:       4
active processes:     1
total processes:      5

The 1 active worker is my own curl. The status request is itself served by a worker, so checking the counter increments the counter. And 4 idle is already below min_spare_servers = 5, which means the fork is about to happen. Thirty seconds later:

start since:          34
accepted conn:        99
idle processes:       5
active processes:     1
total processes:      6

There is the 6th worker. The 99 accepted connections in 34 seconds are my metrics exporter polling /fpm-status a few times per second. That constant trickle is what kept one worker busy and triggered the fork. (accepted conn is a lifetime odometer, by the way. It never resets while the master lives, only on restart or reload.)

What happens under load

I ran a k6 benchmark with 100 virtual users and watched the pool breathe:

quiet:   50 total (49 idle + 1 active)     <- parked at max_spare_servers
burst:   72 total (~70 busy)               <- grew on demand, ceiling is 300
after:   glides back down to 50 over ~a minute

So the worker count floats between three levels:

floor: ~5-6 on a truly idle server (min_spare keeps 5 idle alive)
parked after traffic: ~50, because trimming stops once idle workers are down to max_spare_servers
under load: whatever demand needs, up to max_children

One sentence to remember: the spare settings bound the idle workers, max_children bounds all workers, and the actual count floats between them based on traffic.

Also worth knowing: when load stops, active collapses instantly, but total shrinks slowly on purpose, roughly one worker per second. A traffic dip followed by another spike should not cause a fork-storm.

How much RAM is that?

Each worker holds the framework and its request data in its own memory. You can see it live:

ps -ylC php-fpm --sort:rss

The RSS column is bytes-in-use per process, in KB. Measured on my Laravel app, warm, under load:

workers + master: 51
total RSS:        1866 MB
avg per process:  36.6 MB

The distribution was remarkably tight: nearly every worker sat within 1 MB of the average. Fresh workers start around 14 MB and grow to ~37 MB once they have served requests, so always measure warm and under load, or you will size your pool from the wrong number. A heavy CMS with many packages can run 150-250+ MB per worker.

Which brings us to the sizing formula:

max_children = (RAM for PHP x 0.9) / avg process size

Plugging in my own numbers: 7.7 GB x 0.9 / 37 MB is about 187 children. My config says 300. That means 300 x 37 MB is ~11 GB, more RAM than the box has. If a spike ever pushed the pool to its configured ceiling, the OOM killer would start shooting workers mid-request. I got away with it because my real peak was 72 workers, but strictly speaking my own config flunks my own math. Do the division.

What actually happens at the ceiling

A detail that confused me: max_children = 300 is not a connection limit. It is a concurrency limit. Each worker processes exactly one request at a time, so 300 is how many requests can be in progress simultaneously. Everything else waits:

requests 1-300      -> each gets a worker, processed now
requests 301-4396   -> parked in the kernel's listen queue (backlog 4096)
beyond that         -> the kernel drops new connections, nginx returns 502

Which gives an overloaded FPM box a very recognizable degradation ladder:

workers free           -> fast responses      (healthy)
workers full, queue ok -> slow responses      (latency, silent)
queue full             -> 502s from nginx     (visible failure)

Note who fails: when the queue is full, the kernel rejects the connection before FPM ever sees it. PHP never runs for that request, which is why saturated PHP shows up as gateway errors, not PHP errors.

And 300 concurrent is not 300 requests per second. If each request takes 50 ms, 300 workers can push ~6,000 requests per second. Concurrency times speed equals throughput, which is why my 723 rps benchmark never needed more than ~70 workers.

The status page, decoded

curl localhost:8088/fpm-status

total / active / idle processes: workers alive now, working vs waiting
max active processes: high-score counter, the most workers ever busy at the same moment. Compare it to max_children to see how close you have come to the ceiling
max children reached: how many times ALL workers were busy and a new request had nowhere to go. This is the single most important number on the page. Anything above 0 means real users waited because the pool was too small
listen queue: requests waiting for a free worker right now. The queue is where latency hides before errors appear
listen queue len: the queue's capacity (min of listen.backlog and the kernel's somaxconn)
all of these reset on every restart or reload, which is also why Prometheus samples them into rates instead of trusting raw counters

Takeaways

start_servers only matters for the first second. After that, the spare bounds own the pool.
The pool never returns to its boot size. It parks at max_spare_servers after traffic.
max_children is a memory budget, not a guess: RAM for PHP divided by measured process size.
It is a concurrency ceiling, not a throughput ceiling. Faster requests raise throughput without more workers.
Watch max children reached and the listen queue. Too low a ceiling means queueing while CPU idles; too high means swap or the OOM killer. The queue length itself fixes nothing, it only chooses how long users suffer before the 502.

Adding a New LLM Provider to Prism PHP: How I Shipped Z.AI Support

kevariable — Wed, 29 Jul 2026 08:47:33 +0000

Prism is the Laravel package for talking to LLMs with one fluent API. It ships with OpenAI, Anthropic, Gemini, Groq, Mistral, xAI, Perplexity and more. It did not ship with Z.AI, the provider behind the GLM models, so I opened a PR to add it.

That PR is now merged: prism-php/prism#794. 28 files, ~1.5k lines, text generation, tool calling, multimodal input and structured output.

This post is that PR broken down into the parts you actually need if you want to add your own provider.

The mental model

Prism separates three things:

The provider class, which owns the HTTP client and nothing else.
Handlers, one per capability (text, structured, embeddings, ...). A handler builds a payload, sends it and turns the raw JSON into Prism value objects.
Maps, tiny stateless classes that translate one Prism concept into one provider concept. Messages, tools, tool choice, finish reasons, media.

Every provider in the repo follows this shape. If you copy the shape, review goes fast. If you invent your own, it does not.

Step 1: register the provider

Three small edits get Prism to resolve Provider::Z.

The enum:

enum Provider: string
{
    case Z = 'z';
}

The config, in config/prism.php:

'z' => [
    'url' => env('Z_URL', 'https://api.z.ai/api/coding/paas/v4'),
    'api_key' => env('Z_API_KEY', ''),
],

And a factory method on PrismManager. The manager resolves create{Name}Provider by convention, so the method name is the whole wiring:

protected function createZProvider(array $config): Z
{
    return new Z(
        apiKey: $config['api_key'],
        url: $config['url'],
    );
}

Step 2: the provider class

Z extends Prism's abstract Provider and only decides which handler runs. Note #[\SensitiveParameter] on the API key so it never leaks into a stack trace:

class Z extends Provider
{
    use InitializesClient;

    public function __construct(
        #[\SensitiveParameter] public readonly string $apiKey,
        public readonly string $url,
    ) {}

    #[\Override]
    public function text(TextRequest $request): Response
    {
        $handler = new Handlers\Text(
            $this->client($request->clientOptions(), $request->clientRetry())
        );

        return $handler->handle($request);
    }

    #[\Override]
    public function structured(StructuredRequest $request): StructuredResponse
    {
        $handler = new Handlers\Structured(
            $this->client($request->clientOptions(), $request->clientRetry())
        );

        return $handler->handle($request);
    }
}

One thing I changed during review: I dropped final and made client() and the encoder methods protected. People extend providers to point at gateways and proxies. Sealing the class blocks that for no benefit.

Step 3: mapping messages

This is where providers actually differ. Z.AI speaks an OpenAI shaped chat API, but the media parts are its own thing.

MessageMap merges system prompts in front of the conversation, then dispatches on message class:

protected function mapMessage(Message $message): void
{
    match ($message::class) {
        UserMessage::class => $this->mapUserMessage($message),
        AssistantMessage::class => $this->mapAssistantMessage($message),
        ToolResultMessage::class => $this->mapToolResultMessage($message),
        SystemMessage::class => $this->mapSystemMessage($message),
        default => throw new \InvalidArgumentException('Unsupported message type: '.$message::class),
    };
}

The interesting one is the user message, because Z.AI takes images, files and videos as separate typed content parts rather than one generic attachment:

protected function mapUserMessage(UserMessage $message): void
{
    $images = array_map(fn (Media $media): array => (new DocumentMapper($media, DocumentType::ImageUrl))->toPayload(), $message->images());
    $documents = array_map(fn (Document $document): array => (new DocumentMapper($document, DocumentType::FileUrl))->toPayload(), $message->documents());
    $videos = array_map(fn (Media $media): array => (new DocumentMapper($media, DocumentType::VideoUrl))->toPayload(), $message->videos());

    $this->mappedMessages[] = [
        'role' => 'user',
        'content' => [
            ...$images,
            ...$documents,
            ...$videos,
            ['type' => 'text', 'text' => $message->text()],
        ],
    ];
}

The three media types collapse into one mapper plus an enum, because the payload shape is identical apart from the key:

enum DocumentType: string
{
    case FileUrl = 'file_url';
    case VideoUrl = 'video_url';
    case ImageUrl = 'image_url';
}

public function toPayload(): array
{
    return [
        'type' => $this->type->value,
        $this->type->value => [
            'url' => $this->media->url(),
        ],
    ];
}

validateMedia() returns $this->media->isUrl(), which makes the constraint explicit: this endpoint accepts URLs, not base64 blobs. Prism throws a clear exception instead of the API returning a vague 400.

Step 4: tools

Two more maps. ToolMap converts a Prism Tool into a function definition, and ToolChoiceMap handles the three forcing modes:

public static function map(string|ToolChoice|null $toolChoice): string|array|null
{
    if (is_null($toolChoice)) {
        return null;
    }

    if (is_string($toolChoice)) {
        return [
            'type' => 'function',
            'function' => ['name' => $toolChoice],
        ];
    }

    if (! in_array($toolChoice, [ToolChoice::Auto, ToolChoice::Any])) {
        throw new InvalidArgumentException('Invalid tool choice');
    }

    return match ($toolChoice) {
        ToolChoice::Auto => 'auto',
        ToolChoice::Any => 'required',
    };
}

A string means "call this specific tool". ToolChoice::Any becomes required. Anything else is rejected loudly rather than silently sent and ignored by the API.

Step 5: the text handler and the agent loop

The handler sends the request, then branches on the finish reason. This is the whole multi step tool loop:

public function handle(Request $request): TextResponse
{
    $response = $this->sendRequest($request);
    $data = $response->json();

    $responseMessage = new AssistantMessage(
        data_get($data, 'choices.0.message.content') ?? '',
        $this->mapToolCalls(data_get($data, 'choices.0.message.tool_calls', [])),
    );

    $request->addMessage($responseMessage);

    $finishReason = $this->mapFinishReason($data);

    return match ($finishReason) {
        FinishReason::ToolCalls => $this->handleToolCalls($data, $request),
        FinishReason::Stop, FinishReason::Length => $this->handleStop($data, $request),
        default => throw new PrismException('Z: unknown finish reason'),
    };
}

handleToolCalls executes the tools, appends a ToolResultMessage, records a step, then recurses while steps->count() < $request->maxSteps(). The step cap lives in the request, so a runaway agent stops on the user's terms rather than the provider's.

Two defensive touches worth stealing:

If the finish reason says tool_calls but the array is empty, throw. A malformed response should not turn into a silent empty answer.
An unmapped finish reason throws too, instead of falling through to "stop". I originally reused xAI's finish reason map by accident, and one of the review commits was fixing exactly that.

Payload building uses Arr::whereNotNull so optional parameters simply disappear when unset:

$payload = array_merge([
    'model' => $request->model(),
    'messages' => (new MessageMap($request->messages(), $request->systemPrompts()))(),
], Arr::whereNotNull([
    'max_tokens' => $request->maxTokens(),
    'temperature' => $request->temperature(),
    'top_p' => $request->topP(),
    'tools' => ToolMap::map($request->tools()),
    'tool_choice' => ToolChoiceMap::map($request->toolChoice()),
]));

Step 6: structured output without native schema support

This was the one real design decision in the PR.

OpenAI has strict JSON schema mode. The Z.AI coding endpoint has response_format: json_object, which guarantees valid JSON but not your JSON. So the schema goes in as a final system message, and StructuredMap just extends MessageMap to append it:

class StructuredMap extends MessageMap
{
    public function __construct(array $messages, array $systemPrompts, private readonly Schema $schema)
    {
        parent::__construct($messages, $systemPrompts);

        $this->messages[] = new SystemMessage(
            content: 'Response Format in JSON following:'.json_encode($this->schema->toArray(), JSON_PRETTY_PRINT)
        );
    }
}

The request also sends thinking: ['type' => 'disabled'], because reasoning traces leaking into a JSON payload is exactly the failure mode you do not want here.

Subclassing the message map rather than copying it means multimodal structured requests keep working for free.

Step 7: tests with recorded fixtures

Prism tests providers against recorded HTTP responses, not live APIs. FixtureResponse::fakeResponseSequence replays a numbered sequence, which is what makes multi step tool tests possible:

it('can generate text using multiple tools and multiple steps', function (): void {
    FixtureResponse::fakeResponseSequence('chat/completions', 'z/generate-text-with-multiple-tools');

    $response = Prism::text()
        ->using(Provider::Z, 'z-model')
        ->withTools($tools)
        ->withMaxSteps(4)
        ->withPrompt('What time is the tigers game today in Detroit and should I wear a coat?')
        ->asText();

    expect($response->steps[0]->toolCalls)->toHaveCount(2)
        ->and($response->steps[0]->toolCalls[0]->name)->toBe('search_games');
});

Nine fixtures in total, covering a plain prompt, a system prompt, parallel tool calls, a forced tool call, a 429 rate limit, image, file and video URLs, plus structured output. One of my later commits is literally patch(z): remove token, so: scrub your recorded fixtures before committing them.

Using it

$response = Prism::text()
    ->using('z', 'glm-4.6')
    ->withPrompt('Write a short story about a robot learning to love')
    ->asText();

Multimodal, with glm-4.6v:

$response = Prism::text()
    ->using('z', 'glm-4.6v')
    ->withMessages([
        new UserMessage(
            'What is in this image?',
            additionalContent: [
                Image::fromUrl('https://example.com/image.png'),
            ]
        ),
    ])
    ->asText();

Set Z_API_KEY and you are done.

What I would tell past me

Read a neighbouring provider first. I got the structure right by following the existing providers, and the review comments were about details, not architecture.

Do not copy a map without reading it. The xAI finish reason map compiled fine and was wrong.

Docs are part of the PR. A provider page under docs/providers/ plus a sidebar entry in the VitePress config. Maintainers should not have to ask.

Expect the merge to take a while. I opened this in December and it merged in March, with the maintainer adding formatting and refactor commits on top. That is normal for a repo where every provider is a long term maintenance commitment.

The full diff is on GitHub: prism-php/prism#794.

I turned the claude code cli into a Prism provider

kevariable — Sat, 25 Jul 2026 08:57:35 +0000

so here is the thing. i work on a laravel app where almost every feature touch an llm. extract structured data from a pdf, rewrite a paragraph, summarize, spell check, generate stuff. all of it go through prism, which is nice because i just write Prism::text()->using('gemini', 'gemini-2.5-flash') and forget about http clients.

but the api bill is the api bill. and i already pay for claude code subscription every month, sitting there, doing nothing when i sleep.

then i realize: claude code cli is just a binary. it take stdin, it print json to stdout. that is basically an llm api with extra steps. so why not make prism talk to it?

this post is how i did it. the whole thing is one class.

what prism actually want from a provider

prism is not magic. a provider is a class extending Prism\Prism\Providers\Provider and implementing the methods you care about. you do not need to implement everything. i only need two:

text(TextRequest $request): TextResponse
structured(StructuredRequest $request): StructuredResponse

no embeddings, no images, no streaming. if some code call ->asStream() on my provider it will blow up, and that is fine, because nothing in my app do that.

the cli contract

first, check what the binary give back:

echo "say hi" | claude -p --output-format json --model claude-haiku-4-5

you get an envelope like this:

{
  "is_error": false,
  "result": "hi!",
  "session_id": "abc-123",
  "model": "claude-haiku-4-5",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "cache_read_input_tokens": 0
  }
}

that is everything prism need. result is the text, usage map straight to prism Usage, session_id and model map to Meta. nice.

the provider

app/Prism/ClaudeCli/ClaudeCliProvider.php:

final class ClaudeCliProvider extends Provider
{
    public function __construct(
        private readonly string $binary,
        private readonly ?string $oauthToken,
        private readonly string $defaultModel,
        private readonly int $timeout,
    ) {}

    public function text(TextRequest $request): TextResponse
    {
        $envelope = $this->invoke(
            $this->resolveModel($request->model()),
            $this->composeSystemPrompt($request->systemPrompts()),
            $this->composeUserPrompt($request->prompt(), $request->messages()),
            $this->timeoutFor($request->clientOptions()),
        );

        return new TextResponse(
            steps: new Collection,
            text: $this->resultText($envelope),
            finishReason: FinishReason::Stop,
            toolCalls: [],
            toolResults: [],
            usage: $this->usage($envelope),
            meta: $this->meta($envelope),
            messages: new Collection,
        );
    }
}

that is the whole shape. take the prism request, flatten it to a string, shell out, build a prism response back. no ai, just plumbing.

shelling out without shooting your foot

this is the part where you must be careful:

private function invoke(string $model, string $systemPrompt, string $userPrompt, int $timeout): array
{
    $command = [$this->binary, '-p', '--output-format', 'json', '--model', $model];

    if (trim($systemPrompt) !== '') {
        $command[] = '--append-system-prompt';
        $command[] = $systemPrompt;
    }

    $result = Process::timeout($timeout)
        ->path(sys_get_temp_dir())
        ->env($this->processEnv())
        ->input($userPrompt)
        ->run($command);

    if ($result->failed()) {
        throw PrismException::providerResponseError(
            'claude-cli exited with code '.$result->exitCode().': '.trim($result->errorOutput()),
        );
    }

    $envelope = json_decode($result->output(), true);

    if (! is_array($envelope)) {
        throw PrismException::providerResponseError('claude-cli returned non-JSON output: '.$result->output());
    }

    if (($envelope['is_error'] ?? false) === true) {
        throw PrismException::providerResponseError('claude-cli reported an error: '.($envelope['result'] ?? 'unknown'));
    }

    return $envelope;
}

four things here are not accidents:

command as array, not string. laravel Process with an array never touch a shell. so user input that contain ; rm -rf / is just text. if you build the command as one string you are one paste away from rce. do not do it.

user prompt go through stdin, not argv. prompts get long. argv have a size limit, stdin does not. also stdin is not visible in ps aux.

->path(sys_get_temp_dir()). claude cli read CLAUDE.md, .claude/settings.json, hooks, all from the working directory. if you run it inside your laravel project, your own project instructions leak into every user request. run it from an empty temp dir instead.

is_error check. cli can exit 0 and still say the request failed inside the envelope. exit code alone is not enough.

for auth i pass the subscription oauth token as env:

private function processEnv(): array
{
    $env = ['CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC' => '1'];

    if ($this->oauthToken !== null && $this->oauthToken !== '') {
        $env['CLAUDE_CODE_OAUTH_TOKEN'] = $this->oauthToken;
    }

    return $env;
}

no api key anywhere. it use the subscription.

structured output when the provider have no structured mode

this is the fun part. gemini and openai have native json schema mode. the cli does not. so i fake it: take the prism schema, dump it into the prompt, then be paranoid when parsing.

public function structured(StructuredRequest $request): StructuredResponse
{
    $userPrompt = $this->composeUserPrompt($request->prompt(), $request->messages())
        .$this->schemaInstruction($request->schema()->toArray());

    $envelope = $this->invoke(/* ... */);
    $text = $this->resultText($envelope);

    return new StructuredResponse(
        steps: new Collection,
        text: $text,
        structured: $this->decodeJson($text),
        finishReason: FinishReason::Stop,
        usage: $this->usage($envelope),
        meta: $this->meta($envelope),
    );
}

private function schemaInstruction(array $schema): string
{
    return "\n\nYou must respond with ONLY a single valid JSON object that conforms to the JSON schema below. "
        .'Do not include markdown code fences, comments, or any prose before or after the JSON.'
        ."\n\nJSON schema:\n".json_encode($schema, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
}

the caller side never change. they still write ->withSchema($schema)->asStructured() and get an array. the hack live only inside the provider, which is exactly where a hack should live.

and the parser, three levels of giving up:

private function decodeJson(string $text): array
{
    $candidate = trim($text);

    if (preg_match('/```

(?:json)?\s*(.+?)\s*

```/s', $candidate, $matches) === 1) {
        $candidate = $matches[1];
    }

    $decoded = json_decode($candidate, true);

    if (! is_array($decoded)) {
        $start = strpos($candidate, '{');
        $end = strrpos($candidate, '}');

        if ($start !== false && $end !== false && $end > $start) {
            $decoded = json_decode(substr($candidate, $start, $end - $start + 1), true);
        }
    }

    if (! is_array($decoded)) {
        throw PrismException::providerResponseError('claude-cli did not return valid JSON: '.$text);
    }

    return $decoded;
}

first try raw. then strip code fences, because models love fences even when you say no fences. then cut from first { to last }, because sometimes you get "Sure! Here is the JSON:" in front. after that, give up loudly.

register it

prism use a manager, so extend() is all you need. do it in the boot of a service provider:

public function boot(): void
{
    $this->app->make(PrismManager::class)->extend('claude-cli', fn (): ClaudeCliProvider => new ClaudeCliProvider(
        binary: config('prism.claude_cli.binary'),
        oauthToken: config('prism.claude_cli.oauth_token'),
        defaultModel: config('prism.claude_cli.model'),
        timeout: (int) config('prism.claude_cli.timeout'),
    ));
}

config in config/prism.php:

'claude_cli' => [
    'binary' => env('CLAUDE_CLI_BINARY', 'claude'),
    'oauth_token' => env('CLAUDE_CODE_OAUTH_TOKEN'),
    'model' => env('CLAUDE_CLI_MODEL', 'claude-haiku-4-5'),
    'timeout' => (int) env('CLAUDE_CLI_TIMEOUT', 120),
],

note the closure. under octane the container stay alive between request, so never resolve config in a constructor you register as singleton. closure is resolved per make, so it is safe.

the payoff: swap provider with one env var

every ai call in the app already look like this:

Prism::structured()
    ->using(config('prism.text.provider'), config('prism.text.model'))
    ->withSchema($schema)
    ->withPrompt($prompt)
    ->asStructured();

so switching from gemini to the subscription is:

PRISM_TEXT_PROVIDER=claude-cli
PRISM_TEXT_MODEL=claude-haiku-4-5

and rollback is flipping it back. no code deploy. this is the actual reason i use prism, not the fluent api.

resolveModel also protect me from myself:

private function resolveModel(string $requested): string
{
    return str_starts_with($requested, 'claude') ? $requested : $this->defaultModel;
}

if some old code still pass gemini-2.5-flash to this provider, the cli would explode. instead it fall back to the configured default. small thing, save me one production incident already.

things that bite me

timeout chain. cli call is slow. like 30 to 90 second slow for a big prompt. you have a timeout in the provider, a timeout in the queue worker, a timeout in php-fpm, a timeout in nginx. the innermost one must be the smallest, and every outer one must be bigger. i learn this the hard way when request keep dying with no error in the log.

cli must exist in the container. it is a node binary. your php docker image probably do not have node. either install it in the image, or keep an api provider as fallback.

concurrency. each call is a real process with real memory. api call is cheap to fan out, process is not. if you run twenty in parallel your box will feel it.

no streaming, no tools. i do not implement them, so features that need token by token streaming still use the api provider. mixing is fine, that is the whole point of config per feature.

should you do this

if you are a solo dev or a small product and you already pay for the subscription, yes. it is one class, maybe 200 line, and it cut the inference cost to zero for the features where latency does not matter.

if you serve real traffic at scale, no. process spawning is not a load bearing architecture. use it as a canary, keep the api provider one env var away.

the bigger lesson is not about claude cli anyway. prism extend() mean anything that can take text and return text can become a provider. a local ollama, an internal company gateway, a mock that return fixture in test. you write one class, and the rest of your app never know the difference.

that is the good part.

A practical guide to refactoring complex database queries in Laravel

kevariable — Fri, 21 Nov 2025 20:10:19 +0000

When I opened our Repository Class file and saw a single method spanning 194 lines with nested subqueries, complex conditionals, and duplicated logic, I knew we had a problem. The code worked, but it was a maintenance nightmare.

Fast forward three weeks: the same functionality now lives in clean, composable, testable components. The result? 78% less code complexity and a architecture that actually makes sense.

Here's how we did it.

The Problem: When Repository Methods Become Monsters

Our conversation repository had methods that looked like this:

public function getAllBy(TeamMemberId | CandidateId $id, ConversationMetaDto $meta): CursorPaginatorDto
{
    // 194 lines of this...
    $query = DB::table('conversation')
        ->select(
            'c.*',
            DB::raw('(SELECT _m.content FROM message WHERE...) AS last_message'),
            DB::raw('(SELECT _m.created_at FROM message WHERE...) AS message_updated_at'),
            DB::raw('(SELECT _r.job_title FROM role WHERE...) AS conversation_title'),
            // ... 15 more complex subqueries
        )
        ->when($meta->roleId->isExist(), function ($q) use ($meta) {
            return $q->where('role_id', $meta->roleId->toValue());
        })
        ->when($meta->unread, function ($q) use ($id) {
            if ($id instanceof TeamMemberId) {
                return $q->whereRaw('(SELECT COUNT(m.id) FROM message...) > 0');
            }
            return $q->whereRaw('(SELECT COUNT(_m2.id) FROM message...) > 0');
        })
        ->when($meta->search->isExist(), function ($q) use ($meta, $id) {
            // ... more nested conditionals
        });

    // ... 150 more lines of complexity
}

The issues were glaring:

Mixed responsibilities: SELECT logic, WHERE conditions, and business rules all tangled together
Testing nightmare: How do you unit test a 194-line method?
Code duplication: Similar query patterns repeated across multiple methods
Hard to understand: New team members needed hours just to understand one method
Fragile: Change one thing, risk breaking everything

We violated every SOLID principle in the book, especially the Single Responsibility Principle.

The Solution: Enter the Specification Pattern

The Specification pattern is a design pattern that encapsulates business rules into reusable, composable objects. Think of it as LEGO blocks for your database queries.

Instead of one massive query builder, we break it into small, focused pieces:

public function getAllBy(TeamMemberId | CandidateId $id, ConversationMetaDto $meta): CursorPaginatorDto
{
    // Clean orchestration
    $specifications = $this->buildSpecifications($id, $meta, $companyId, $roleIds);

    $query = $this->query()->from('conversation as c');
    $query = $specifications->apply($query);

    return $this->createCursorPaginator($query->cursorPaginate());
}

private function buildSpecifications(...): CompositeSpecification
{
    // Declarative composition
    return new CompositeSpecification([
        new ConversationSelectSpecification($id),
        new RoleFilterSpecification($roleIds, $meta->roleId->toValue()),
        new CompanyFilterSpecification($companyId),
        new UnreadFilterSpecification($meta->unread, $id),
        new SearchFilterSpecification($meta->search->toValue(), $id),
        new CandidateFilterSpecification($id),
    ]);
}

That's it. The same 194-line method now fits in 38 lines. The query logic hasn't disappeared—it's just organized properly.

Building Blocks: The Architecture

Our implementation has three main components:

1. The Base Interface

Every specification implements this simple contract:

interface ConversationSpecification
{
    public function apply(Builder $query): Builder;
}

That's literally it. Take a query builder, modify it, return it.

2. Individual Specifications

Each specification handles one aspect of the query. For example, filtering by unread status:

final readonly class UnreadFilterSpecification implements ConversationSpecification
{
    public function __construct(
        private bool $unread,
        private TeamMemberId | CandidateId $entityId
    ) {}

    public function apply(Builder $query): Builder
    {
        if (!$this->unread) {
            return $query; // Guard clause
        }

        if ($this->entityId instanceof TeamMemberId) {
            return $query->whereRaw(
                '(SELECT COUNT(m.id) FROM message m
                  LEFT JOIN message_read mr ON m.id = mr.message_id
                  WHERE m.conversation_id = c.id
                  AND m.team_member_id != ?
                  AND mr.id IS NULL) > 0',
                [$this->entityId->toValue()]
            );
        }

        return $query->whereRaw(
            '(SELECT COUNT(_m2.id) FROM message _m2
              WHERE _m2.conversation_id = c.id
              AND _m2.candidate_read_at IS NULL
              AND _m2.candidate_id IS NOT NULL) > 0'
        );
    }
}

Notice how it:

Has a single responsibility (filtering by unread status)
Uses a guard clause to short-circuit when not needed
Is immutable (readonly keyword)
Can be tested independently

3. The Composite

The CompositeSpecification uses the Composite Pattern to combine multiple specifications:

final readonly class CompositeSpecification implements ConversationSpecification
{
    public function __construct(
        private array $specifications
    ) {}

    public function apply(Builder $query): Builder
    {
        foreach ($this->specifications as $specification) {
            $query = $specification->apply($query);
        }

        return $query;
    }
}

Beautiful simplicity. It takes an array of specifications and applies them one by one.

Real-World Examples

Example 1: Basic Query with Filters

Want to get all conversations for a team member, filtered by role and showing only unread?

$specifications = new CompositeSpecification([
    new ConversationSelectSpecification($teamMemberId),
    new RoleFilterSpecification($roleIds),
    new UnreadFilterSpecification(true, $teamMemberId),
]);

$query = DB::table('conversation as c');
$query = $specifications->apply($query);

$conversations = $query->cursorPaginate();

Example 2: Adding Search

Need to add search functionality? Just add another specification:

$specifications = new CompositeSpecification([
    new ConversationSelectSpecification($teamMemberId),
    new RoleFilterSpecification($roleIds),
    new UnreadFilterSpecification(true, $teamMemberId),
    new SearchFilterSpecification('John', $teamMemberId), // New!
]);

No need to modify existing code. Open/Closed Principle in action.

Example 3: Different Context, Same Specifications

Getting a single conversation by ID? Reuse the SELECT logic:

$specifications = new CompositeSpecification([
    new BasicConversationSelectSpecification(),
    new ConversationByIdSpecification($conversationId),
]);

$query = DB::table('conversation as c');
$conversation = $specifications->apply($query)->first();

Creating Your Own Specification

Adding a new specification is straightforward. Let's say you want to filter conversations by status:

Step 1: Create the class

<?php

namespace App\Infrastructure\Specification;

use Illuminate\Database\Query\Builder;

final readonly class StatusFilterSpecification implements ConversationSpecification
{
    public function __construct(
        private string $status
    ) {}

    public function apply(Builder $query): Builder
    {
        return $query->where('c.status', '=', $this->status);
    }
}

Step 2: Use it

$specifications = new CompositeSpecification([
    new ConversationSelectSpecification($id),
    new StatusFilterSpecification('active'), // Add your new spec
    new RoleFilterSpecification($roleIds),
]);

Done. No need to touch existing specifications or repository methods.

The Rules We Follow

After implementing dozens of specifications, we've learned a few best practices:

1. Single Responsibility

One specification = one concern. Don't create a RoleAndUnreadFilterSpecification. Create separate RoleFilterSpecification and UnreadFilterSpecification.

2. Immutability

Always use readonly properties. Specifications should never have mutable state:

// ✅ Good
final readonly class MySpec implements ConversationSpecification
{
    public function __construct(
        private string $value
    ) {}
}

// ❌ Bad
class MySpec implements ConversationSpecification
{
    private string $value;

    public function setValue(string $value): void {
        $this->value = $value;
    }
}

3. Guard Clauses

Use early returns to keep code readable:

public function apply(Builder $query): Builder
{
    if (!$this->shouldApply) {
        return $query; // Short-circuit
    }

    return $query->where(...);
}

4. Separation of Concerns

Keep SELECT logic separate from WHERE logic:

// SELECT specifications
new ConversationSelectSpecification($id)

// WHERE specifications  
new RoleFilterSpecification($roleIds)
new UnreadFilterSpecification($unread)

The Results: Numbers Don't Lie

Here's what we achieved:

Metric	Before	After	Improvement
Lines of code	194	78	60% reduction
Cyclomatic complexity	High	Low	Significantly simplified
Test coverage	23%	87%	264% increase
Bug reports (last 3 months)	12	2	83% reduction
Onboarding time	4 hours	45 minutes	81% faster

But the numbers only tell part of the story. The real win is in maintainability. When a junior developer needed to add a "last active" filter, it took them 15 minutes—including writing tests. Before this refactor, that would've been a day's work.

Testing Becomes Trivial

One of the biggest wins? Testing individual specifications is dead simple:

class UnreadFilterSpecificationTest extends TestCase
{
    public function test_filters_unread_for_team_member(): void
    {
        $teamMemberId = new TeamMemberId(1);
        $spec = new UnreadFilterSpecification(true, $teamMemberId);

        $query = DB::table('conversation as c');
        $result = $spec->apply($query);

        $this->assertStringContainsString(
            'SELECT COUNT(m.id) FROM message',
            $result->toSql()
        );
    }

    public function test_skips_filter_when_unread_is_false(): void
    {
        $teamMemberId = new TeamMemberId(1);
        $spec = new UnreadFilterSpecification(false, $teamMemberId);

        $query = DB::table('conversation as c');
        $result = $spec->apply($query);

        // Query should be unchanged
        $this->assertEquals($query->toSql(), $result->toSql());
    }
}

No mocking, no complex setup, no database seeds. Just pure unit tests.

Common Pitfalls to Avoid

Don't Create God Specifications

// ❌ Bad - too many responsibilities
class MegaFilterSpecification {
    public function apply(Builder $query): Builder {
        return $query
            ->where('role_id', $this->roleId)
            ->where('status', 'active')
            ->where('unread', true)
            ->where('search', 'like', $this->search);
    }
}

// ✅ Good - separate concerns
new RoleFilterSpecification($roleId)
new StatusFilterSpecification('active')
new UnreadFilterSpecification(true)
new SearchFilterSpecification($search)

Don't Make Specifications Depend on Each Other

// ❌ Bad - coupled specifications
class MySpec {
    public function __construct(
        private OtherSpecification $other
    ) {}
}

// ✅ Good - independent specifications composed externally
new CompositeSpecification([
    new FirstSpecification(),
    new SecondSpecification(),
]);

Don't Use Specifications for Writes

Specifications are for query building only. They shouldn't execute queries or modify data:

// ❌ Bad
class SaveConversationSpecification {
    public function apply(Builder $query): Builder {
        $query->insert(['data' => 'value']); // Don't do this!
        return $query;
    }
}

When NOT to Use This Pattern

The Specification Pattern isn't always the answer. Don't use it when:

Your queries are simple: If ->where('status', 'active') is all you need, just write that
Logic isn't reused: One-off queries don't need specifications
Team isn't familiar: Introduce it gradually, don't force it everywhere at once
Performance is critical: The pattern adds minimal overhead, but for ultra-high-performance scenarios, raw SQL might be better

Conclusion

The Specification Pattern transformed our codebase from a tangled mess into a clean, maintainable architecture. We went from 194-line methods to 38-line methods without sacrificing functionality.

More importantly, we now have:

Code that's easy to understand for new team members
Tests that actually test individual behaviors
Changes that don't break existing functionality
Confidence to refactor without fear

If you're dealing with complex repository queries in Laravel, give this pattern a try. Start small—pick your ugliest repository method and extract just one specification. You'll be amazed at how much clearer your code becomes.

Your future self (and your team) will thank you.

Resources

Have you implemented the Specification Pattern in your projects? What challenges did you face? Drop a comment below—I'd love to hear your experiences!