DEV Community: kevariable

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!