DEV Community: Raheel Shan

The Repository Pattern and AQC — Part 1 of 3: Cleaning Up the Internals

Raheel Shan — Fri, 29 May 2026 09:32:49 +0000

The Series

This is the first article in a three-part series on migrating from a traditional Repository Pattern implementation toward Atomic Query Construction. Each article represents a stage in that migration:

Part 1 (this article): AQC is adopted internally. The repository interface stays the same. Each method privately builds its own $params and delegates to AQC. Callers notice nothing.
Part 2: Parameter definition moves out of the repository and up to the service layer. The repository shrinks to a pure wrapper and its redundancy becomes visible.
Part 3: Two paths forward — drop the repository entirely and call AQC directly, or keep the repository and discipline it with AQC practices without using AQC classes at all.

If you are working with an existing codebase and a team that depends on a familiar repository interface, Part 1 is your entry point. It is the lowest-risk way to introduce AQC, and it delivers immediate benefits even before you take the pattern further.

The Problem This Stage Solves

A traditional Repository Pattern implementation for a product domain might look like this:

interface ProductRepositoryInterface
{
    public function getAllProducts();
    public function getProductById($productId);
    public function getActiveProducts();
    public function createProduct(array $productData);
    public function updateProduct($productId, array $productData);
    public function deleteProduct($productId);
    public function getProductsByCategory($categoryId);
    public function updateStock($productId, $quantity);
}

Eight methods. Each has its own implementation. And inside those implementations, query logic is written directly — Eloquent calls, where clauses, orderBy, eager loading — repeated and scattered across methods. When getActiveProducts and getProductsByCategory both need to eager-load category and inventory, that eager-load is written twice. When the ordering changes, two methods need updating. When a new condition is added to "active" products, every method that deals with active products needs to be found and updated.

This is the internal problem. The interface bloat — too many methods — is a separate concern, and we will address it in Part 2. The problem this article solves is the query duplication and scattered logic inside the existing methods.

AQC eliminates this without touching the repository's public interface at all.

The Approach

Each repository method remains publicly named and individually responsible for its domain operation. But instead of writing Eloquent query logic directly, each method privately constructs a $params array that describes what it needs, and delegates the actual query construction and execution to a dedicated AQC class.

The repository method owns two things:

Deciding what parameters apply to this specific operation
Calling the AQC class with those parameters

The AQC class owns one thing:

Building and executing the query from whatever parameters it receives

The caller owns nothing new. The interface is unchanged.

Step 1 — The AQC Classes

We create one AQC class per CRUD operation. Each class contains all possible conditions for that operation. Repository methods activate the conditions they need by including the relevant keys in $params.

GetProducts:

namespace App\AQC\Product;

class GetProducts
{
    public function handle(array $params): Collection|LengthAwarePaginator
    {
        $query = Product::query();

        if (!empty($params['status'])) {
            $query->where('status', $params['status']);
        }

        if (!empty($params['category_id'])) {
            $query->where('category_id', $params['category_id']);
        }

        if (isset($params['min_stock'])) {
            $query->where('stock_quantity', '>', $params['min_stock']);
        }

        if (!empty($params['search'])) {
            $query->where(function ($q) use ($params) {
                $q->where('name', 'like', '%' . $params['search'] . '%')
                  ->orWhere('sku', 'like', '%' . $params['search'] . '%');
            });
        }

        if (!empty($params['with'])) {
            $query->with($params['with']);
        }

        if (!empty($params['order_by'])) {
            $query->orderBy($params['order_by'], $params['order_dir'] ?? 'desc');
        } else {
            $query->orderBy('created_at', 'desc');
        }

        if (!empty($params['per_page'])) {
            return $query->paginate($params['per_page']);
        }

        return $query->get();
    }
}

GetProduct:

namespace App\AQC\Product;

class GetProduct
{
    public function handle(array $params): ?Product
    {
        $query = Product::query();

        if (!empty($params['id'])) {
            $query->where('id', $params['id']);
        }

        if (!empty($params['sku'])) {
            $query->where('sku', $params['sku']);
        }

        if (!empty($params['with'])) {
            $query->with($params['with']);
        }

        return $query->first();
    }
}

StoreProduct:

namespace App\AQC\Product;

class StoreProduct
{
    public function handle(array $params): Product
    {
        return Product::create([
            'name'           => $params['name'],
            'description'    => $params['description'] ?? null,
            'price'          => $params['price'],
            'sku'            => $params['sku'],
            'stock_quantity' => $params['stock_quantity'] ?? 0,
            'category_id'    => $params['category_id'] ?? null,
            'status'         => $params['status'] ?? 'active',
        ]);
    }
}

UpdateProduct:

namespace App\AQC\Product;

class UpdateProduct
{
    public function handle(array $params): bool
    {
        $query = Product::query();

        if (!empty($params['id'])) {
            $query->where('id', $params['id']);
        }

        if (!empty($params['status'])) {
            $query->where('status', $params['status']);
        }

        if (!empty($params['category_id'])) {
            $query->where('category_id', $params['category_id']);
        }

        return $query->update($params['data'] ?? []) > 0;
    }
}

DeleteProduct:

namespace App\AQC\Product;

class DeleteProduct
{
    public function handle(array $params): bool
    {
        $query = Product::query();

        if (!empty($params['id'])) {
            $query->where('id', $params['id']);
        }

        if (!empty($params['status'])) {
            $query->where('status', $params['status']);
        }

        if (!empty($params['category_id'])) {
            $query->where('category_id', $params['category_id']);
        }

        return $query->delete() > 0;
    }
}

All five classes are defined once. Every condition lives in exactly one place. No duplication anywhere.

Step 2 — The Repository Uses AQC Internally

Now the repository is rewritten to use these AQC classes internally. The public interface is identical to the original. Callers — controllers, services, tests — do not change a single line:

<?php

use App\AQC\Product\GetProducts;
use App\AQC\Product\GetProduct;
use App\AQC\Product\StoreProduct;
use App\AQC\Product\UpdateProduct;
use App\AQC\Product\DeleteProduct;

class ProductRepository implements ProductRepositoryInterface
{
    public function getAllProducts(): Collection
    {
        $aqc = new GetProducts();
        return $aqc->handle([
            'with' => ['category', 'inventory'],
        ]);
    }

    public function getProductById(int $productId): ?Product
    {
        $aqc = new GetProduct();
        return $aqc->handle([
            'id'   => $productId,
            'with' => ['category', 'inventory'],
        ]);
    }

    public function getActiveProducts(): Collection
    {
        $aqc = new GetProducts();
        return $aqc->handle([
            'status'    => 'active',
            'min_stock' => 0,
            'with'      => ['category', 'inventory'],
        ]);
    }

    public function createProduct(array $productData): Product
    {
        $aqc = new StoreProduct();
        return $aqc->handle($productData);
    }

    public function updateProduct(int $productId, array $productData): bool
    {
        $aqc = new UpdateProduct();
        return $aqc->handle([
            'id'   => $productId,
            'data' => $productData,
        ]);
    }

    public function deleteProduct(int $productId): bool
    {
        $aqc = new DeleteProduct();
        return $aqc->handle([
            'id' => $productId,
        ]);
    }

    public function getProductsByCategory(int $categoryId): Collection
    {
        $aqc = new GetProducts();
        return $aqc->handle([
            'category_id' => $categoryId,
            'with'        => ['inventory'],
        ]);
    }

    public function updateStock(int $productId, int $quantity): bool
    {
        $aqc = new UpdateProduct();
        return $aqc->handle([
            'id'   => $productId,
            'data' => ['stock_quantity' => $quantity],
        ]);
    }
}

Study what happened to each method. getAllProducts no longer writes an Eloquent query — it builds a $params array and delegates. getActiveProducts does the same, with the conditions for "active" expressed as parameters. updateStock, which once had its own direct Eloquent logic, now delegates to UpdateProduct with a targeted $params array.

Every method is now three to six lines: construct $params, instantiate the AQC class, return the result. No raw Eloquent. No scattered where clauses. No duplication.

And crucially — the controller that calls $repository->getActiveProducts() has not changed. The service that calls $repository->updateStock($id, $quantity) has not changed. The interface is identical. The migration is invisible to callers.

What Changed and What Did Not

What changed:

Query logic is no longer scattered across repository methods
Conditions like 'status' => 'active' or eager-loading ['category', 'inventory'] are defined once in $params and handled once in the AQC class
Adding a new condition to "active products" means changing one line in GetProducts::handle(), not hunting down every method that touches active products
The AQC classes are independently testable — you can verify query behavior by passing $params combinations directly, without invoking the repository at all

What did not change:

The repository interface — same method names, same signatures, same return types
The number of repository methods — still eight
The caller's experience — controllers and services call the same methods they always called
The fact that new domain requirements still produce new repository methods

The Honest Limitation of This Stage

This approach delivers real value, but it leaves one problem untouched: the repository still grows.

When a new business requirement arrives — say, getLowStockProductsByCategory — a new method still gets added to the repository. The interface expands. The interface contract grows. And every new method follows the same pattern: build $params, call AQC, return result. The methods become predictable and clean, but they keep accumulating.

There is also a subtler issue. The repository is now making business decisions. getActiveProducts knows that "active" means status = active and stock_quantity > 0. That business knowledge lives in the repository, which is a data access layer. Should it? If the definition of "active" changes — if it now also requires verified = true — the change happens in the repository, not in the service or domain layer where business logic is supposed to live.

These are the tensions that Part 2 resolves. By moving parameter definition out of the repository and up to the service layer, the repository loses its business knowledge entirely. It becomes a pure router. And once it is a pure router, its redundancy becomes impossible to ignore.

When to Stop at This Stage

Not every codebase needs to go further. This stage is the right stopping point when:

Your team is not ready for the full AQC migration and needs a familiar repository interface
You are refactoring a large legacy codebase incrementally and cannot change callers yet
Your application is stable with a fixed set of domain operations that are unlikely to grow significantly
The primary goal was eliminating internal query duplication, not restructuring the architecture

If any of those describe your situation, this stage is a complete and valid destination. The internals are clean, the query logic is centralized, and the codebase is significantly more maintainable than before.

If you want to go further — if you want to see the repository reduced to a wrapper and ultimately made optional — that is what Part 2 is for.

Summary

	Before	After (Part 1)
Repository interface	8 named methods	8 named methods (unchanged)
Query logic location	Scattered in each method	Centralized in AQC classes
Caller impact	—	None
Duplication	High	Eliminated
Business logic in repository	Yes	Yes (unchanged)
Repository growth	Unbounded	Still unbounded
AQC adoption level	None	Internal only

This is Part 1 of a 3-part series.
Part 2: "The Repository as a Wrapper — When AQC Makes the Repository Redundant."
Part 3: "Two Paths — Go Direct with AQC, or Discipline Your Repository with AQC Practices."

Raheel Shan is the originator of the Atomic Query Construction (AQC) design pattern. He writes about Laravel architecture, query design, and application structure at raheelshan.com, dev.to, and medium.com.

Inspector.dev (Neuron), Laravel AI SDK, and Prism PHP: A Practical Comparison for Laravel Developers

Raheel Shan — Wed, 20 May 2026 19:23:14 +0000

The PHP and Laravel ecosystem has had a quiet revolution in the past year. Where once you had to piece together raw HTTP calls to OpenAI's API and write your own retry logic, token counting, and provider-switching abstractions, you now have not one, not two, but three serious contenders for AI integration in your Laravel apps.

I've spent the last several months evaluating all three in real projects — and I want to give you the honest, side-by-side comparison I wish I'd had when I started.

The three tools in question are:

Inspector.dev / Neuron AI — a PHP-agnostic agentic framework backed by the Inspector monitoring platform
Laravel AI SDK (laravel/ai) — Taylor Otwell's official, first-party SDK that shipped production-stable with Laravel 13
Prism PHP (echolabsdev/prism) — the community-built Laravel package by EchoLabs that's been quietly filling this gap since before the first party entered the room

Let's dig in.

The Lay of the Land

Before I compare them, it's worth being clear about what each one is trying to do, because they don't all occupy the same niche — and that's the most important thing to understand.

Prism PHP is a unified LLM integration layer for Laravel. You pick a provider (OpenAI, Anthropic, Gemini, Ollama, Mistral), fire off a fluent query, get a structured response. Think of it as a clean, opinionated HTTP abstraction over multiple AI providers. It's not an agent framework. It's not a monitoring tool. It's a very good way to talk to LLMs from Laravel.

Laravel AI SDK is Laravel's official answer to that same problem, but with significantly broader scope. It handles text generation, image generation, audio transcription, embeddings, vector stores, structured output, RAG, and first-class Agent classes — all through a single, framework-native package. It shipped in beta with Laravel 12 and became production-stable in Laravel 13 (March 2026).

Inspector.dev / Neuron AI is a different animal entirely. Neuron is an agentic PHP framework — PHP-agnostic, not just Laravel-native — built by the team at Inspector.dev. Its ambition is to bring LangChain/LlamaIndex-style agentic orchestration to the PHP ecosystem. It comes with built-in observability through Inspector, which is its killer feature. You can monitor every LLM call, tool invocation, and agent step in real time.

With that framing in mind, let's compare across dimensions that actually matter.

1. Provider Support

All three tools take a multi-provider stance, but they differ in breadth and maturity.

Prism PHP supports OpenAI, Anthropic, Gemini, Ollama, Mistral, and Groq. The interface is consistent across all of them — you switch providers by changing a single enum value. No other code changes required. This has been battle-tested in production by the community for over a year.

Laravel AI SDK supports OpenAI, Anthropic, Gemini, Groq, xAI, and ElevenLabs out of the box, with more planned. The configuration lives in config/ai.php and aligns with Laravel's familiar patterns. Taylor's team has also built smart fallbacks — if a provider hits a rate limit or goes down, the SDK can automatically fail over to another. That's genuinely impressive and not something you get out of the box with the other two.

Neuron AI is similarly provider-agnostic. It uses a common AIProviderInterface for all LLM calls, so switching from Anthropic to OpenAI to Gemini is a one-line change. The framework-agnostic design means the provider layer works the same whether you're on Laravel, Symfony, WordPress, or vanilla PHP.

Winner: Laravel AI SDK for the automatic failover feature. Runner-up: Prism, which has the most mature multi-provider support in the wild.

2. Developer Experience

This is where they diverge most sharply.

Prism PHP has the best fluent API for raw LLM calls. Here's what a basic Anthropic call looks like:

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::text()
    ->using(Provider::Anthropic, 'claude-3-7-sonnet-latest')
    ->withSystemPrompt(view('prompts.system'))
    ->withPrompt('Explain the Atomic Query Construction pattern.')
    ->asText();

echo $response->text;

It's clean. It's chainable. It feels Laravel-native even though it predates the official SDK. Testing utilities, response faking, and assertion helpers are included.

Laravel AI SDK introduces the concept of Agent classes — dedicated PHP classes that encapsulate your prompts, instructions, tools, and conversation history:

php artisan make:agent SupportAgent

class SupportAgent extends Agent
{
    protected function instructions(): string
    {
        return 'You are a helpful customer support agent...';
    }

    protected function tools(): array
    {
        return [new FetchOrderTool(), new RefundTool()];
    }
}

// Usage:
$agent = new SupportAgent();
$response = $agent->prompt('Where is my order?');

This is a more structured, testable pattern than raw LLM calls. It aligns with how Laravel organizes everything else — you get an Artisan command, a clear class contract, and built-in conversation storage backed by database migrations the SDK publishes for you.

Neuron AI takes the Agent pattern the furthest. You extend a base Agent class, define your provider, instructions, and tools, and get a full agentic system including RAG, multi-agent orchestration, workflow graphs with human-in-the-loop checkpoints, and streaming — all in PHP:

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\Anthropic\Anthropic;

class CustomerServiceAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(config('services.anthropic.key'), 'claude-4-5-sonnet');
    }

    public function instructions(): string
    {
        return new SystemPrompt(
            background: ['You are a helpful customer service assistant'],
            steps: ['Verify order details before processing refunds'],
            output: ['Always confirm actions with the customer']
        );
    }
}

The Neuron approach is the most capable, but also has the steepest learning curve. It's clearly inspired by LangChain and LlamaIndex — those familiar with Python-side agentic development will feel at home.

Winner: Laravel AI SDK for the best balance of structure and familiarity. Prism wins for simple LLM integration with minimal boilerplate. Neuron wins for complex agentic workloads.

3. Agentic Capabilities

If you're building simple chat features or AI-powered text generation, all three will serve you well. But if you're building autonomous agents, multi-step workflows, or RAG systems, the picture changes quickly.

Prism PHP is honest about what it is: a text/LLM integration layer. It's not trying to be an agent framework. It handles tool calling with a clean API, supports structured output, and manages multi-turn conversations — but orchestrating multi-agent workflows is outside its design scope.

Laravel AI SDK is building toward agents. The Agent class system, structured output, RAG support through vector stores, and tool calling are all first-class. The SDK also ships with built-in conversation storage (the agent_conversations and agent_conversation_messages tables), so maintaining chat context across sessions requires zero custom infrastructure. This is a huge win for typical SaaS applications. However, the SDK is still young, and the more advanced agentic patterns (workflow graphs, human-in-the-loop, event-driven multi-agent coordination) aren't yet in the box.

Neuron AI is the most complete agentic framework in the PHP ecosystem, full stop. It gives you workflow orchestration with event-driven architecture, streaming, human-in-the-loop checkpoints, agent-to-agent communication, vision capabilities, and a composable toolkit system. Neuron V2 rewrote the workflow system from scratch around event-driven patterns, making complex multi-step agent workflows practical and testable in PHP — something that was previously only achievable in Python-land.

Winner: Neuron AI for serious agentic applications. Laravel AI SDK for teams that need a structured starting point with room to grow.

4. Observability and Debugging

This is where Inspector.dev / Neuron has a decisive, built-in advantage.

Prism PHP has no built-in observability. You're relying on whatever logging and monitoring you've wired up yourself — Laravel Telescope, your own query observers, or an external APM. For simple use cases this is fine. For complex pipelines, it's a gap.

Laravel AI SDK fires events that you can listen to, which gives you hooks for custom logging and monitoring. But there's no first-party dashboard or trace timeline out of the box. You can build it, but you have to build it.

Neuron AI + Inspector.dev is in a different league here. Because Neuron was built by the Inspector team, observability is first-class — not bolted on. Setting one environment variable is all it takes:

INSPECTOR_INGESTION_KEY=your_key_here

After that, every agent execution — every LLM call, every tool invocation, every workflow step — shows up as a trace in the Inspector dashboard. You can see execution timelines, identify which step in a complex workflow failed, measure token usage per step, and debug non-deterministic agent behaviour in a way that is simply not possible with logging alone.

For production AI agents, this observability is not a nice-to-have. It's essential. Agentic applications are probabilistic — same input does not always equal same output. Without a trace-level view of execution, debugging becomes a nightmare.

Winner: Neuron AI / Inspector.dev, by a wide margin, for production agentic workloads.

5. Ecosystem Fit

Prism PHP is Laravel-only, but it's deeply Laravel-native. It uses the Laravel HTTP client internally, integrates with Laravel's service container, and follows all of Laravel's conventions. If you're a Laravel shop that doesn't care about PHP framework portability, Prism's Laravel-native ergonomics are hard to beat.

Laravel AI SDK is also Laravel-only, but it's first-party Laravel — which means long-term support guarantees, documentation that lives at laravel.com, and tight integration with future Laravel features. For teams that want to bet on the framework's official direction, this is the safest choice.

Neuron AI is deliberately framework-agnostic. Whether you're on Laravel, Symfony, WordPress, or vanilla PHP, Neuron integrates without friction. This is a conscious design decision to grow the PHP ecosystem broadly rather than fragment it by framework. For shops running mixed codebases — say, a Laravel SaaS and a Symfony backend — Neuron lets you share agent implementations across both. This cross-framework portability is genuinely rare in the PHP ecosystem.

Winner: Laravel AI SDK for pure Laravel shops. Neuron AI for teams with mixed PHP codebases or long-term portability concerns.

6. Scope and Multimodality

Prism PHP: Text generation, embeddings, image input (multi-modal), tool calling, structured output. Clean and focused.

Laravel AI SDK: Text generation, image generation (DALL-E, Gemini), audio transcription (Whisper), embeddings, vector stores, RAG, file search, web search, reranking. Possibly the broadest scope of the three by design.

Neuron AI: Text generation, tool calling, RAG, vector store integration, vision/image input, multi-agent orchestration, workflow graphs. Focused on the agentic surface area rather than generative media.

If you need to generate images or transcribe audio directly through the same package, the Laravel AI SDK is the only one that covers you today without additional packages.

The Honest Recommendation

After working with all three in real projects, here's how I think about choosing between them:

Choose Prism PHP if you want to add LLM-powered features (text generation, tool calling, structured output) to a Laravel app as quickly as possible with minimal architecture overhead. It's the most mature community solution, the most ergonomic for straightforward use cases, and it's not going anywhere. If all you need is a clean way to talk to multiple LLM providers from Laravel, Prism is the right tool.

Choose Laravel AI SDK if you're starting a new Laravel 12/13 project and want to bet on the official, first-party direction. The Agent class model, database-backed conversation storage, built-in fallbacks, and official documentation support make this the safest long-term choice for teams building within the Laravel ecosystem. It's young, but it's Taylor Otwell's team maintaining it — that carries weight.

Choose Neuron AI if you're building serious agentic applications — autonomous workflows, multi-agent systems, RAG pipelines that need to run reliably in production. The built-in observability through Inspector.dev is genuinely irreplaceable for this class of problem. And if your team works across multiple PHP frameworks, Neuron's framework-agnostic design is a strategic advantage no other tool offers.

The Bigger Picture

What strikes me most about this moment is that the PHP ecosystem finally has credible answers to Python's LangChain and JavaScript's Vercel AI SDK. A year ago, if a CTO asked their PHP team to build autonomous agents, the honest answer was "we'd need Python for that." That's no longer true.

Each of these tools reflects a different philosophy: Prism values ergonomics and focus. The Laravel AI SDK values official integration and comprehensive scope. Neuron values deep production reliability and cross-framework reach.

None of them are wrong. They're solving different problems at different levels of abstraction. The best choice depends on your project's complexity, your team's PHP ecosystem footprint, and whether observability in production is a day-one requirement.

For what it's worth: in my own projects at Ohad Technologies, I've been reaching for Prism for straightforward LLM integration and Neuron for anything involving multi-step agentic workflows where I need to understand what's happening in production. The Laravel AI SDK is the one I'm watching most closely — first-party support in a fast-moving space like AI is not a minor thing.

Pick the right tool for the job. And if you're not sure, start with Prism — you can always layer in more architecture later.

Raheel Shan is the co-founder and CTO of Ohad Technologies and the originator of the Atomic Query Construction (AQC) design pattern. He writes about Laravel architecture, AI integration, and software engineering at raheelshan.com.

Your Laravel Queries Are Lying to You

Raheel Shan — Fri, 27 Mar 2026 14:14:38 +0000

How many times does Product::latest() appear in your codebase?

If the answer is more than once, you're not DRY — you're just organized duplication. Every repeated query entry point is another interpretation of how that query should behave. Inconsistencies creep in silently, and future changes become a scavenger hunt.

Atomic Query Construction (AQC) fixes this with one rule:

Every model gets exactly one query entry point, inside a dedicated execution class.

// Every. Single. Time.
(new GetProducts())->handle($params);

Filters, sorting, pagination — all controlled through params. One place to change, one place to debug, zero drift.

📖 Read the complete article here.

Stop Writing Queries Everywhere: The Atomic Habit Your Laravel Codebase Needs

Raheel Shan — Mon, 23 Mar 2026 07:19:24 +0000

You Have a Query Problem. You Just Haven’t Admitted It Yet.

Let’s describe a normal Laravel codebase.

A controller fetches active users
A job fetches almost the same users, with one extra condition
A service fetches them again, missing a condition
A test rebuilds the query from scratch

Same intent. Different queries. Different results.

Nobody notices until something breaks. Then everyone starts guessing which version is “correct”.

That’s the problem.

Not complexity. Not scale.

Inconsistency.

The Problem Isn’t Duplication. It’s Drift.

People love saying “don’t repeat yourself”.

They still write this everywhere:

User::where('active', true)->get();

Then somewhere else:

User::where('active', true)
    ->whereNotNull('email_verified_at')
    ->get();

Then somewhere else:

User::where('active', true)
    ->where('role', 'admin')
    ->get();

Now you don’t have duplication.

You have different definitions of the same thing.

That’s worse.

Because now your system behaves differently depending on which file you opened.

The Rule: One Layer Owns All Queries

There is only one way to stop this:

Every database query must live in one layer. That layer is AQC.

And once it exists:

Controllers do not write queries
Services do not write queries
Jobs do not write queries
Tests do not write queries

If a query exists outside AQC, it’s wrong. No debate. Its violation of AQC.

Instead of this in a controller:

public function index(Request $request)
{
    $users = User::where('active', true)
        ->whereNotNull('email_verified_at')
        ->get();
    return view('users.index',compact('users'));
}

You do this:

public function index(Request $request)
{
    $users = (new GetUsers())->handle(['active' => true]);
    return view('users.index',compact('users'));
}

Now the query has one home.

Same Rule Everywhere

Controller

$users = (new GetUsers())->handle([
    'role' => $request->role,
]);

Service

$users = (new GetUsers())->handle([
    'digest_enabled' => true,
]);

Job

$users = (new GetUsers())->handle([
    'active' => false,
]);

Test

$users = (new GetUsers())->handle([
    'active' => true,
]);

Nobody writes queries anymore.

They just use them.

And guess what? You have composition.

With AQC, you can make a single query class handle multiple contexts, without repeating yourself or risking divergence.

Look at this example:

<?php

namespace App\AQC\User;

use App\Models\User;

class GetUsers
{
    public function handle(array $params = [])
    {
        $query = User::query();

        // apply filters conditionally
        if (!empty($params['active'])) {
            $query->where('active', $params['active']);
        }

        if (!empty($params['digest_enabled'])) {
            $query->where('digest_enabled', $params['digest_enabled']);
        }

        if (!empty($params['role'])) {
            $query->where('role', $params['role']);
        }

        // Apply sorting when requested otherwise do it on id by default
        if(isset($params['sortBy']) && isset($params['type'])){
            $sortBy = $params['sortBy'];
            $type = $params['type'];    
            $query->orderBy($sortBy, $type);
        }

        return isset($params['paginate'])
            ? $query->paginate(User::PAGINATE)
            : $query->get();   
    }
}

Here’s what’s happening:

Conditional filters – Active users, digest-enabled users, role-based filtering – all controlled by the caller. Nothing is hard-coded in multiple places.
Flexible sorting – The query supports dynamic ordering, but defaults to a predictable behavior if nothing is specified.
Pagination or full collection – One class handles both paginated lists for the UI and full collections for jobs or exports.

This is composition in action. One query class serves multiple consumers, each passing their parameters. The base conditions and logic live in one place. No controller, service, or job reimplements a filter or accidentally forgets a condition.

The beauty? Every consumer gets exactly what it needs without duplicating or diverging query logic. You maintain a single source of truth for fetching users.

What You Gain (And What You Stop Losing)

When queries live in one place:

You stop redefining business rules
You stop forgetting conditions
You stop chasing bugs across files
You stop guessing which query is correct

Change happens once. Behavior updates everywhere.

That’s it.

What Counts as a Violation

Let’s make this uncomfortable:

If you write this anywhere outside AQC:

User::where(...)

You just broke the architecture. You just violated the AQC Design pattern rule.

Doesn’t matter if it’s “just one condition” Doesn’t matter if it’s “temporary” Doesn’t matter if it’s “faster this way”

It’s wrong.

AQC only works if it’s enforced. Not suggested. But enforced.

The Habit

Before writing any query, there are only two options:

It already exists → use it
It doesn’t exist → create it in AQC

There is no third option.

Final Thoughts

Atomic Query Construction removes the repeatitive queries by giving every query a single home. One layer. One class per operation. One public method. One parameter signature. Every consumer uses the same query, every time.

Controllers call AQC classes. Services call AQC classes. Jobs call AQC classes. Tests call AQC classes. The database answers to one layer — and one layer only.

Stop guessing. Stop duplicating. Stop chasing subtle divergences across files. Build the layer, enforce the rules, and make query discipline a habit.

This is not optional. This is the foundation of a maintainable, predictable Laravel codebase.

The Reasoning Behind AQC Class Design Choices

Raheel Shan — Tue, 17 Mar 2026 18:51:43 +0000

The Atomic Query Construction (AQC) design pattern is all about precision, clarity, and predictability. Over time, I’ve developed a consistent structure for AQC classes that may seem restrictive at first glance, but each restriction serves a practical purpose. Let’s break down why AQC classes are defined the way they are.

1. No Constructor: Avoiding Dependency Injection

In many design patterns, constructors are used to inject dependencies—services, repositories, or other objects. AQC classes intentionally avoid constructors. Why? Because the AQC philosophy assumes that the underlying service or query builder never changes internally.

Injecting a dependency through a constructor implies that the class can be swapped or configured differently for each instance. For AQC classes, this is unnecessary overhead. The logic is atomic, deterministic, and isolated. By not requiring a constructor, you eliminate boilerplate, reduce configuration errors, and keep the class focused purely on its query logic.

It also simplifies instantiation. You just create an instance whenever needed, without worrying about passing services or setup parameters that will never vary.

$getUsers = new GetUsers(); // simple and predictable
$result = $getUsers->handle(['status' => 'active']);

2. Non-Static Methods: Encouraging Instance-Based Clarity

Some developers might wonder: why not make handle() static? A static method would avoid instantiation and look simpler. But static methods carry hidden costs: they obscure state, make testing harder, and encourage global coupling.

Using non-static methods ensures each instance is independent, even if it doesn’t hold state now. It’s a design discipline. By always creating an object before calling handle(), the code communicates intent: “this is a self-contained, reusable atomic query unit.”

3. Single Public Method (handle) with params Array

The handle() method is the only public interface of an AQC class. This makes the API extremely predictable: no guessing which method to call or which method affects the query.

The params array standardizes input. Whether the query needs a filter, a sort order, or pagination, everything is passed through a single array. This avoids proliferating method signatures and keeps the class atomic.

$params = [
    'status' => 'active',
    'role' => 'admin',
    'sort' => 'created_at'
];

$result = (new GetUsers())->handle($params);

Private methods handle the internal steps, such as building joins, filtering conditions, or selecting columns. They are invisible externally, which keeps the class contract simple and ensures maintainers only focus on the handle method.

4. Why This Pattern Works

This design achieves three key goals:

Predictability: Every AQC class looks and behaves the same way.
Simplicity: No unnecessary constructors, no dependency injection, no multiple public methods.
Flexibility: While the class is simple externally, private methods allow complex query construction internally.

By following these rules, teams can read, use, and maintain AQC classes without worrying about hidden state, dependencies, or inconsistent public APIs.

Final Thoughts

The structure of AQC classes—no constructor, non-static methods, single handle() public method accepting a **params** array—is deliberate. It enforces atomicity, simplicity, and predictability, which are the core principles of the Atomic Query Construction design pattern. Each class becomes a self-contained unit that can be easily reused, tested, and maintained without overengineering or unnecessary complexity.

Why Atomic Query Construction (AQC) Intentionally Uses Arrays Instead of DTOs

Raheel Shan — Mon, 16 Mar 2026 21:30:13 +0000

One question keeps appearing whenever someone looks at the Atomic Query Construction (AQC) pattern for the first time:

Why are parameters passed as arrays instead of DTOs?

At first glance, DTOs sound like the “cleaner” solution. They provide type safety, structure, and explicit contracts. In many architectures, DTOs make perfect sense.

But AQC is intentionally designed around arrays, and replacing them with DTOs would undermine one of the core ideas of the pattern.

To understand why, we need to look at how AQC actually works.

AQC Is Parameter-Driven

The central idea behind AQC is simple:

Parameters shape the query.

Each parameter activates a specific atomic piece of logic.

For example:

$params = [
    'category_id' => 5,
    'min_price' => 100,
    'max_price' => 500,
    'with' => ['brand']
];

Inside the query class:

$query = Product::query();

if (!empty($params['category_id'])) {
    $query->where('category_id', $params['category_id']);
}

if (!empty($params['min_price'])) {
    $query->where('price', '>=', $params['min_price']);
}

if (!empty($params['max_price'])) {
    $query->where('price', '<=', $params['max_price']);
}

if (!empty($params['with'])) {
    $query->with($params['with']);
}

Each parameter independently contributes to the final query.

This means query composition is dynamic.

And this is where arrays become important.

The Cartesian Flexibility of Parameters

AQC relies on the idea that parameters can combine freely.

If you have five optional parameters:

category_id
brand_id
price_min
price_max
with

You don't just have five scenarios.

You have dozens of possible combinations.

Examples:

category_id
category_id + brand_id
category_id + price_min
brand_id + price_max
price_min + price_max
category_id + brand_id + with
brand_id + price_min + price_max

The number of combinations grows quickly.

Arrays allow this naturally because parameters are simply present or absent.

Each parameter acts like a switch that activates a piece of query logic.

DTOs don't work well in this environment because they encourage rigid structures, where every field is predefined and expected.

AQC is not designed for rigid structures.

It is designed for combinatorial flexibility.

DTOs Introduce Unnecessary Rigidity

A DTO typically looks like this:

class ProductQueryDTO
{
    public ?int $categoryId;
    public ?int $brandId;
    public ?int $priceMin;
    public ?int $priceMax;
}

This immediately creates a few problems.

1. DTOs Define Structure Too Early

DTOs force you to define all possible parameters upfront.

But queries evolve.

Tomorrow you may add:

min_stock
max_stock
rating
visibility
published_at

Now your DTO grows. Then another developer creates another DTO for a slightly different query.

Soon you have DTOs multiplying.

2. DTOs Add an Extra Layer

AQC classes already serve a single purpose: build and execute queries.

Introducing DTOs means adding a translation layer:

Request → DTO → AQC → Query

With arrays the flow stays simple:

Request → AQC → Query

AQC intentionally avoids unnecessary layers.

3. DTOs Reduce Dynamic Composition

DTOs imply a fixed contract.

But AQC is built on conditional query pieces.

Each parameter activates a piece of logic.

Arrays support that naturally because they allow parameters to appear or disappear without forcing structural constraints.

Arrays Match the Philosophy of AQC

AQC is built on a few clear ideas:

One class = one intention
Parameters control query behavior
Queries are composed conditionally
Controllers remain thin

Arrays align perfectly with this philosophy.

Each parameter acts as a trigger for an atomic query segment.

That makes the query builder inside the AQC class extremely flexible without introducing complexity elsewhere.

Final Thought

DTOs are useful in many architectural patterns.

But AQC is intentionally parameter-driven, and arrays preserve the dynamic nature of query composition.

Each parameter activates an atomic query piece, and arrays allow those pieces to combine freely into a Cartesian number of possible query scenarios.

Trying to force DTOs into this pattern doesn't improve it.

It just makes the system heavier while removing the flexibility AQC was designed to provide.

Atomic Query Construction (AQC) Design Pattern: A Practical CRUD Implementation Guide

Raheel Shan — Mon, 16 Mar 2026 20:32:16 +0000

When I first introduced the Atomic Query Construction (AQC) design pattern, the focus was on breaking down monolithic repositories into small, single-purpose query classes. These classes are driven entirely by parameters, not hard-coded logic. That philosophy allows a single class to handle multiple query intentions without method explosion, while keeping code readable and maintainable.

In this article, I want to show you how to implement AQC for full CRUD operations, following the same parameter-first approach. This is the practical way to apply the pattern in a Laravel application but you are free to adopt this pattern in any language of your preference.

The Philosophy Recap

AQC is based on one principle

One class = one intention. Parameters define the variations.

Folder Structure

A simple organization for CRUD operations:

app/
 └─ AQC/
     ├─ Product/
     │   ├─ GetProducts.php
     │   ├─ GetProduct.php
     │   ├─ CreateProduct.php
     │   ├─ UpdateProduct.php
     │   └─ DeleteProduct.php
     │
     └─ User/
         ├─ GetUsers.php
         ├─ GetUser.php
         ├─ CreateUser.php
         ├─ UpdateUser.php
         └─ DeleteUser.php

1. Fetch Multiple Records (GetProducts)

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProducts
{
    public function handle($params = [])
    {
        $productObj = Product::latest('id');

        // apply filters
        if (isset($params['category_id']) && $params['category_id'] > 0) {
            $productObj->where('category_id', $params['category_id']);
        }

        if (isset($params['brand_id']) && $params['brand_id'] > 0) {
            $productObj->where('brand_id', $params['brand_id']);
        }

        // add more filters according to your requirements

        // select columns
        if(isset($params['columns']) && ($params['columns']) > 0){
            $productObj->select($params['columns']);
        }else{
            $productObj->select('*');
        }        

        // Apply sorting when requested otherwise do it on id by default
        if(isset($params['sortBy']) && isset($params['type'])){
            $sortBy = $params['sortBy'];
            $type = $params['type'];    
            $query->orderBy($sortBy, $type);
        }

        return isset($params['paginate'])
            ? $productObj->paginate(Product::PAGINATE)
            : $productObj->get();    
    }
}

if handle method grows create internal helper methods.

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProducts
{
    public function handle($params = [])
    {
        $query = Product::latest('id');

        $this->applyFilters($query, $params);
        $this->selectColumns($query, $params);
        $this->applySorting($query, $params);

        return isset($params['paginate'])
            ? $this->handlePagination($query, $params)
            : $query->get();    
    }

    private function applyFilters($query, $params) { /* ... */ }
    private function selectColumns($query, $params) { /* ... */ }
    private function applySorting($query, $params) { /* ... */ }
    private function handlePagination($query, $params) { /* ... */ }
}

2. Fetch a Single Record (GetProduct)

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProduct
{
    public function handle($params = [])
    {
        $query = Product::query();

        if (!empty($params['id'])) {
            $query->where('id', $params['id']);
        }

        if (!empty($params['slug'])) {
            $query->where('slug', $params['slug']);
        }

        if (!empty($params['sku'])) {
            $query->where('sku', $params['sku']);
        }

        return $query->firstOrFail();
    }
}

Product can be fetched based on id, slug or sku.

Beware: Passing 2 parameters togather can result in not found.

3. Create a Record (CreateProduct)

<?php

namespace App\AQC\Product;

use App\Models\Product;

class CreateProduct
{
    public function handle(array $params)
    {
        return Product::create($params);
    }
}

The parameters are the source of truth. No mapping or rigid arguments required. Create is straightforward.

4. Update a Record Conditionally (UpdateProduct)

<?php

namespace App\AQC\Product;

use App\Models\Product;

class UpdateProduct
{
    public function handle($params = [])
    {
        $productObj = Product::query();

        // Conditional WHERE clauses
        if (!empty($params['id'])) {
            $productObj->where('id', $params['id']);
        }

        if (isset($params['category_id']) && $params['category_id'] > 0) {
            $productObj->where('category_id', $params['category_id']);
        }

        // update provided columns only
        return $productObj->update($params['columns']);
    }
}

One class handles updating multiple fields, conditionally, depending on what parameters exist. No need for separate methods like updatePrice() or updateStock().

5. Delete Records Conditionally (DeleteProduct)

<?php

namespace App\AQC\Product;

use App\Models\Product;

class DeleteProduct
{
    public function handle(array $params = [])
    {
        $query = Product::query();

        if (!empty($params['id'])) {
            $query->where('id', $params['id']);
        }

        if (!empty($params['category_id'])) {
            $query->where('category_id', $params['category_id']);
        }

        if (!empty($params['brand_id'])) {
            $query->where('brand_id', $params['brand_id']);
        }

        return $query->delete();
    }
}

Conditional deletion using the same class for multiple delete intentions. Flexible, atomic, and predictable.

Controller Example

Using AQC inside a controller becomes very clean.

class ProductController extends Controller
{
    public function index()
    {
        $products = (new GetProducts())->handle(request()->all());
        return view('products.index', compact('products'));
    }

    public function show($id)
    {
        $product =(new GetProduct())->handle(['id' => $id]);
        return view('products.index', compact('product'));      
    }

    public function store(Request $request)
    {
        $result = (new StoreProduct())->handle($request->all());
        session()->flash('message', 'Product has been saved successfully.');
        return redirect()->route('products.index');
    }

    public function update(Request $request, $id)
    {
        $params = $request->all();
        $params['id'] = $id;
        $result = (new UpdateProduct())->handle($params);
        session()->flash('message', 'Product has been updated successfully.');
        return redirect()->route('products.index');     
    }

    public function destroy($id)
    {
        $result = (new DeleteProduct())->handle(['id' => $id]);
        session()->flash('message', 'Product has been deleted successfully.');
        return redirect()->route('products.index');     
    }
}

Why This Works

Parameter-driven: No rigid methods. Flexible to multiple scenarios.
Single class = single intention: Each class is atomic.
Controllers stay thin: All query logic is inside AQC.
No dependency injection required: Eloquent is enough, because these queries have fixed intentions.
Reusable atomic filters: Common filters (e.g., active, status, role) can be moved into static helpers to be applied across multiple query classes.

Final Thoughts

AQC isn’t about complexity. It’s about clarity, atomicity, and flexibility.

Fetch multiple records? Use GetProducts() with parameters.
Fetch a single record? Use GetProduct().
Create, update, delete? Each has its own atomic class with conditional behavior.

When applied correctly, AQC keeps controllers thin, and queries flexible. It scales with your application without creating method explosion or unnecessary abstraction layers.

Laravel Blade Partial Api Pattern

Raheel Shan — Sat, 14 Mar 2026 17:40:57 +0000

Laravel Blade Partial API Pattern: Fetching Data — The Missing Part

Raheel Shan ・ Nov 1 '25

#webdev #programming #laravel #designpatterns

Write One Query Class Instead of Many: The AQC Design Pattern for Laravel

Raheel Shan — Thu, 12 Mar 2026 20:04:52 +0000

When I introduced the Atomic Query Construction (AQC) design pattern, a few people asked: "Is this something new? Or is it just a renamed version of something that already exists?"

Fair question. And the honest answer is: it's both.

AQC isn't pulling ideas out of thin air. It's a deliberate combination of three well-established software design principles, packaged into a focused, practical approach to managing query logic. Once you see those foundations clearly, you'll understand not just what AQC does — but why it works.

The three pillars are:

Query Object Pattern
Single Responsibility Principle (SRP)
Pipeline / Composition Pattern

Let me walk through each one.

1. Query Object Pattern

The Query Object pattern is a lesser-known but well-documented pattern from Martin Fowler's Patterns of Enterprise Application Architecture. The idea is straightforward: represent a database query as an object. Instead of scattering query logic across controllers, services, and helpers you encapsulate it in a dedicated class.

class ActiveProducts
{
    public function get()
    {
        return Product::query()
          ->where('active',1)
          ->paginate();
    }
}

In AQC, the same idea is implemented. A dedicated class is created for specific type for operation. Fetch products for example. See, the class accepts parameters and returns results. The caller doesn't care how the query is built. It just calls the class and gets what it needs.

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProducts
{
    public static function handle($params = [], $columns = ['*'])
    {
        $query = Product::latest('id');

        // other code goes here

        return $query
            ? $query->paginate(Product::PAGINATE)
            : $query->get();
    }
}

This is a query object. It has one job. It accepts inputs. It builds the query internally. It returns results.

Instead of putting query logic inside controllers, repositories, or helpers, the query lives in its own class. Not a method buried in a repository. Not a static helper in some utility class. The query is the object. It has a name, a namespace, and a clear contract.

What AQC adds on top of the raw Query Object pattern is the use of dynamic parameters and scenarios to handle multiple use cases within a single class. Instead of creating a separate class for GetActiveProducts() and GetProductsByCategory(), you have one GetProducts() class that handles both and every combination through parameters.

You call it from a controller:

// Admin panel
$columns = ['*'];
$products = GetProducts::handle([], $columns);

// Frontend filtered by category
$params = ['category_id' => 5, 'active' => true];
$products = GetProducts::handle($params , $columns);

// Mobile API - out of stock report
$params = ['out_of_stock' => 5];
$products = GetProducts::handle($params , $columns);

Same class. Same method. Different parameters, different results. That's the Query Object pattern doing its job.

This is framework agnostic. The pattern doesn't care whether you're using Eloquent, Doctrine, SQLAlchemy, or raw PDO. The concept is the same: encapsulate the query in an object.

2. Single Responsibility Principle (SRP)

SRP is one of the five SOLID principles. Robert C. Martin's definition is simple: a class should have one, and only one, reason to change.

Most developers have heard this. But in practice, it gets violated constantly — especially with query logic. A service class ends up with getActiveProducts(), getProductsByCategory(), getExpiredProducts(), and fifteen other methods. The class has dozens of reasons to change. That's the opposite of SRP.

class ProductRepository 
{
    // base methods
    public function create(array $data) { /* ... */ }
    public function update(Product $product, array $data) { /* ... */ }
    public function delete(Product $product) { /* ... */ }
    public function find(int $id): ?Product { /* ... */ }
    public function all(): Collection { /* ... */ }

    // new fetch methods
    public function getActiveProducts() { 
        return Product::where('active', 1)->get();
    }

    public function getProductsByCategory(int $categoryId) { 
        return Product::where('category_id', $categoryId)->get();
    }

    public function getActiveProductsByCategory(int $categoryId) {
        return Product::where('active', 1)
                      ->where('category_id', $categoryId)
                      ->get();
    }

    public function getProductsByStore(int $storeId) { 
        return Product::where('store_id', $storeId)->get();
    }

    public function getActiveProductsByStore(int $storeId) { 
        return Product::where('active', 1)
                      ->where('store_id', $storeId)
                      ->get();
    }

    // and so on...
}

AQC enforces SRP at a structural level. Every query gets its own class. One class, one job.

app/
└── AQC/
    └── Product/
        └── CreateProduct.php
        └── UpdateProduct.php
        └── GetAllProducts.php
        └── GetProduct.php           
        └── DeleteProduct.php

GetProducts() only knows how to fetch a list of products. StoreProduct() only knows how to save a new product. They don't bleed into each other. When a requirement changes — say, the listing query needs a new filter — you go to exactly one class and change exactly one thing.

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProducts
{
    public static function handle($params = [], $columns)
    {
        $query = Product::latest('id');

        // other code goes here
        // always return products (more than one)

        return $query->get();
    }
}

That's SRP in practice.

This might sound trivial, but it's the reason AQC scales. As your application grows, you add new classes, you don't bloat existing ones. The structure stays flat, discoverable, and predictable regardless of the size of your codebase.

And this isn't Laravel-specific. Whether you're working in Node.js, Python, or .Net, the principle holds. One class, one query, one reason to change.

3. Pipeline / Composition Pattern

This is the one people notice last, but it's what makes AQC genuinely powerful.

Look at the GetProducts() class below. The handle() method doesn't do everything in one monolithic block. Internally, it's building the query in stages:

Apply filters
Select columns based on scenario
Apply sorting
Handle pagination

Each step is a distinct concern. In a more explicit implementation, these stages become private methods that each receive the query, add their piece, and pass it along.

<?php

namespace App\AQC\Product;

use App\Models\Product;

class GetProducts
{
    public static function handle($params = [], $columns)
    {
        $query = Product::latest('id');

        self::applyFilters($query, $params);
        self::selectColumns($query, $params);
        self::applySorting($query, $params);

        return isset($params['paginate'])
            ? self::handlePagination($query, $params)
            : $query->get();    
    }

    private static function applyFilters($query, $params) { /* ... */ }
    private static function selectColumns($query, $params) { /* ... */ }
    private static function applySorting($query, $params) { /* ... */ }
    private static function handlePagination($query, $params) { /* ... */ }
}

This is a pipeline. The query object passes through a sequence of stages. Each stage does one thing. Each stage is independently readable, testable, and modifiable.

The Composition pattern takes this further — you build complex behavior by composing smaller, focused pieces rather than writing one massive function. In AQC, you're composing query conditions. In more advanced implementations, you could compose multiple AQC classes together when building complex reporting queries.

A class that does ten things in one method is a class that will break in ten different ways. Split the stages. Compose the result.

This is also why AQC classes are naturally easy to unit test. You're not testing a sprawling 200-line method. You're testing a pipeline where each stage has a clear input and output. You can test the filter stage independently. You can test the pagination stage independently. That's composition paying dividends.

The Underlying Power of Composition Pattern

One of the most powerful aspects of composition in AQC is how filters combine dynamically based on the parameters passed to the query. Each filter is applied conditionally, which means the query does not follow a fixed path. Instead, every parameter acts like a switch that may or may not add a constraint to the query. When multiple parameters are provided, the resulting query becomes a combination of all applicable filters. In practical terms, this creates a flexible query system where a single query class can support many possible filter combinations without needing dozens of specialized query methods. The behavior is similar to a Cartesian combination of conditions: any subset of parameters can be used together, and the query naturally adapts by composing only the relevant constraints. This keeps the code simple while still allowing a wide range of filtering scenarios.

private static function applyFilters($query , $params)
    {
        // apply requested filters
        if (isset($params['category_id']) && $params['category_id'] > 0) {
            $query->where('category_id', $params['category_id']);
        }

        if (isset($params['brand_id']) && $params['brand_id'] > 0) {
            $query->where('brand_id', $params['brand_id']);
        }

        if (isset($params['keyword'])) {
            $query->where('name', 'like', '%' . $params['keyword'] . '%')
                        ->orWhere('sku', 'like', '%' . $params['keyword'] . '%')
                        ->orWhere('description', 'like', '%' . $params['keyword'] . '%');
        }

        if (isset($params['low_stock'])) {
            $query->where('stock', '<=' , 'low_stock_point');
        }

        if (isset($params['out_of_stock'])) {
            $query->where('stock', 0);
        }

        if (isset($params['expired'])) {
            $query->whereDate('expired_date', '<', today())->get();
        }

        if (isset($params['featured'])) {
            $query->where('is_featured', true);
        }

        if (isset($params['trending'])) {
            $query->where('is_trending', true);
        }

        if (isset($params['product_id'])) {
            $query->where('related_product_id', $params['product_id']);
        }

        return $query;
    }

In a typical Repository or naive Query Object setup, every meaningful filter combination often turns into a separate method or class. Instead of one flexible query that reacts to parameters, developers end up writing many rigid query variants to cover different filtering needs.

Consider the above applyFilters(), it would have been turned into the classes or repository methods listed below.

getProductsByCategory()
getProductsByBrand()
getProductsByCategoryAndBrand()
searchProductsByKeyword()
searchProductsByKeywordAndCategory()
searchProductsByKeywordAndBrand()
searchProductsByKeywordCategoryAndBrand()
getLowStockProducts()
getOutOfStockProducts()
getExpiredProducts()
getFeaturedProducts()
getTrendingProducts()
getProductsByCategoryAndLowStock()
getProductsByBrandAndLowStock()
getProductsByCategoryBrandAndLowStock()
getFeaturedProductsByCategory()
getTrendingProductsByBrand()
getExpiredProductsByCategory()
getLowStockProductsByBrand()
getProductsRelatedToProduct()
getFeaturedProductsByCategoryAndBrand()
searchFeaturedProductsByKeyword()
searchTrendingProductsByKeyword()

Why These Three, Together

Individually, none of these patterns is a complete solution.

SRP tells you to split things apart — but doesn't tell you how to organize query logic specifically.

The Query Object pattern gives you the structural template — but doesn't enforce clean internal organization.

The Pipeline / Composition pattern gives you internal clarity — but doesn't tell you how to structure the class's public contract.

Together, they give you AQC:

SRP defines the boundary: one class, one query.
The Query Object pattern defines the structure: a named class that encapsulates query construction.
The Pipeline pattern defines the internals: stages that compose to produce the final result.

The result is a pattern that's modular, reusable, testable, and predictable. Every query has a home. Every home has a consistent contract. Every contract is built in composable stages.

A Note on Class Naming and Static Methods

One thing that may look slightly unconventional in this pattern is the class naming. In many object-oriented conventions, class names typically represent entities such as Product, Order, or User. In AQC, however, the class name often represents an action or intent, such as GetProducts(), GetOrders(), or GetUsers(). While this may feel unusual at first, it is not entirely new. Many established patterns, including Query Objects, Actions, and Command patterns, follow the same idea where a class represents a specific operation rather than a domain entity.

Another stylistic choice in AQC is the use of static methods. Some developers prefer static entry points for simplicity, while others prefer instance methods for better dependency handling or testability. The pattern itself does not require one approach over the other. Teams are free to implement AQC using static or non-static methods depending on their coding standards and architectural preferences.

The Framework Agonist Pattern

I use Laravel, so the examples above use Eloquent. But AQC is not a Laravel pattern. It's a software design pattern that happens to be demonstrated with Laravel.

You can apply the same thinking in Node.js, Python, .Net Framework or any language you use.

The three underlying principles — SRP, Query Object, Pipeline/Composition are language-agnostic. AQC is simply an opinionated application of those three principles to the specific problem of managing query logic across a growing application.

Final Thoughts

When people see AQC for the first time, it looks deceptively simple. Just a class with a handle() method. But the simplicity is intentional — it's what you get when three well-understood patterns come together cleanly.

SRP says: give every query a dedicated home. Query Object says: make the query a first-class object with a clear contract. Pipeline/Composition says: build that query in stages, each one doing exactly one thing.

That's AQC. Not magic. Not reinvention. Just three good ideas in the right combination.

If you've been using these principles in your work already, AQC will feel like familiar ground with a concrete name and structure. If you haven't, this is a good place to start.

Hope this article gives you new way of thinking and writing queries. Let me know what you think of it.

Four Ways to Trigger Delete Row from a Table

Raheel Shan — Sun, 08 Mar 2026 18:29:45 +0000

Assume we have this route:

Route::delete('/pages/{page}',
    [PageController::class, 'destroy']
)->name('site.pages.destroy');

Every delete must:

Open confirmation modal
Wait for user confirmation
Then trigger DELETE request

We are only discussing how the front end triggers the route.

1. One Form Per Row

Each row contains its own form.

Blade

@foreach ($pages as $page)
<tr>
    <td>{{ $page->title }}</td>
    <td>
        <form id="delete-form-{{ $page->id }}"
              action="{{ route('site.pages.destroy', $page->id) }}"
              method="POST">
            @csrf
            @method('DELETE')

            <button type="button"
                    onclick="openModal({{ $page->id }})">
                Delete
            </button>
        </form>
    </td>
</tr>
@endforeach

JavaScript

<script>
let selectedId = null;

function openModal(id) {
    selectedId = id;
    document.getElementById('delete-user-modal').classList.remove('hidden');
}

function submitDelete() {
    document
        .getElementById('delete-form-' + selectedId)
        .submit();
}
</script>

What’s Happening

Each row has its own form
Modal opens
On confirmation → that specific form submits

Works fine.

If you render 300 rows, you now have 300 forms sitting in your DOM.

2. Ajax / Fetch DELETE Request

Here, rows do not contain forms.

Blade

@foreach ($pages as $page)
<tr id="row-{{ $page->id }}">
    <td>{{ $page->title }}</td>
    <td>
        <button type="button"
                onclick="openModal({{ $page->id }})">
            Delete
        </button>
    </td>
</tr>
@endforeach

Layout (CSRF Meta)

<meta name="csrf-token" content="{{ csrf_token() }}">

JavaScript

<script>
let selectedId = null;

function openModal(id) {
    selectedId = id;
    document.getElementById('delete-user-modal').classList.remove('hidden');
}

function submitDelete() {

    fetch(`/pages/${selectedId}`, {
        method: 'DELETE',
        headers: {
            'X-CSRF-TOKEN': document
                .querySelector('meta[name="csrf-token"]')
                .getAttribute('content'),
            'Content-Type': 'application/json'
        }
    }).then(response => {
        if (response.ok) {
            document.getElementById('row-' + selectedId).remove();
        }
    });
}
</script>

What’s Happening

Modal confirms
JavaScript sends DELETE request
On success → remove row from DOM

No page reload. Clean UI.

But you are now responsible for handling errors properly.

3. One Form Wrapping the Table

Instead of many forms, use one.

Blade

<form id="delete-form" method="POST">
    @csrf
    @method('DELETE')

    <input type="hidden" name="page" id="delete-id">

    <table>
        @foreach ($pages as $page)
        <tr>
            <td>{{ $page->title }}</td>
            <td>
                <button type="button"
                        onclick="openModal({{ $page->id }})">
                    Delete
                </button>
            </td>
        </tr>
        @endforeach
    </table>
</form>

JavaScript

<script>
let selectedId = null;

function openModal(id) {
    selectedId = id;
    document.getElementById('delete-user-modal').classList.remove('hidden');
}

function submitDelete() {

    const form = document.getElementById('delete-form');

    form.action = `/pages/${selectedId}`;
    form.submit();
}
</script>

What’s Happening

One form
Hidden input stores ID
Action set dynamically
Full page reload

Cleaner than method one. Still traditional submission.

4. Hidden Global Form + Route Placeholder (Preferred)

This is my pattern.

One hidden form. Outside the table. No ID in the initial action.

Hidden Form

<form method="POST"
      action="{{ route('site.pages.destroy', ['page' => 0]) }}"
      id="delete-form"
      class="hidden">
    @csrf
    @method('DELETE')
</form>

Notice:

We deliberately pass 0 as a placeholder.

Laravel generates a valid route:

/pages/0

We will replace 0 dynamically.

Delete Button

<button type="button"
        data-modal-target="delete-user-modal"
        data-modal-toggle="delete-user-modal"
        onclick="setID({{ $page->id }})">
    Delete
</button>

JavaScript

<script>
let selectedId = null;

function setID(id) {

    selectedId = id;

    let path = "{{ route('site.pages.destroy', ['page' => 0]) }}";

    path = path.replace('/0', '/' + id);

    document.getElementById('delete-form').action = path;
}

function submitForm() {
    document.getElementById('delete-form').submit();
}
</script>

Modal Confirmation Button

<a href="#" onclick="submitForm()">Yes</a>

What’s Happening

Route is generated once with placeholder 0
When delete button is clicked → ID is captured
JavaScript replaces /0 with real ID
Confirmation button submits the hidden form

You get:

One form in DOM
Clean table markup
Proper Laravel route usage
No route string hardcoded
Centralized delete logic
Modal confirmation built-in

Structurally, this is clean and scalable.

Bonus: The HTMX Way

If you’re using HTMX, you don’t need custom fetch calls, and you don’t need to manually submit hidden forms.

HTMX lets you trigger HTTP requests directly from HTML attributes.

Yes. Just attributes.

Basic HTMX Delete Example

First, include HTMX in your layout:

<script src="https://unpkg.com/htmx.org@1.9.10"></script>
<meta name="csrf-token" content="{{ csrf_token() }}">

Now your table:

@foreach ($pages as $page)
<tr id="row-{{ $page->id }}">
    <td>{{ $page->title }}</td>
    <td>
        <button 
            hx-delete="{{ route('site.pages.destroy', $page->id) }}"
            hx-target="#row-{{ $page->id }}"
            hx-swap="outerHTML"
            hx-confirm="Are you sure you want to delete this page?"
            hx-headers='{"X-CSRF-TOKEN": "{{ csrf_token() }}"}'
        >
            Delete
        </button>
    </td>
</tr>
@endforeach

What’s Happening

hx-delete sends a DELETE request
hx-confirm shows confirmation popup automatically
hx-target tells HTMX which element to update
hx-swap="outerHTML" removes the row after successful response
CSRF token is passed via header

No custom JavaScript required.

No hidden forms.

No manual fetch logic.

Just attributes.

Which Method Is Better?

With confirmation required, method one becomes noisy because you must track many forms.

Method three is acceptable but still tied to page reload behavior.

Ajax is powerful if you want instant UI updates.

But from a structural Laravel perspective, the hidden global form with placeholder replacement is the most balanced:

Clean Blade
Clean routes
Clean confirmation flow
Minimal DOM pollution
Easy to maintain

It separates concerns properly.

Table renders data. Modal handles confirmation. Hidden form handles submission.

Why HTMX Is Interesting

It gives you:

AJAX behavior
Confirmation
DOM update
RESTful requests

Without writing JavaScript logic yourself.

It keeps your Blade readable.

It keeps your routes clean.

It feels like traditional server-driven apps, but dynamic.

Hope this gives you clearer picture what you can adopt to delete a row.

Laravel Blade Partial API Pattern: Fetching Data — The Missing Part

Raheel Shan — Sat, 01 Nov 2025 11:18:54 +0000

In the previous article, we built the foundation for what I called Laravel Blade Partial API Pattern. The idea was simple—to make every Blade partial directly accessible through an API-style URL using HTMX, without writing individual controller methods or route definitions.

That worked fine until we hit one problem: data.

The route knew how to locate and render a partial, but it didn’t know what data that partial needed. Some partials required a single record (like a product card), others needed multiple records (like a product list), and a few needed data built from complex DTO classes. This article is about that missing piece—how to fetch and pass the correct data automatically.

The Problem Recap

The old global route could do this much:

/products/partials/product-card/2

→ find `resources/views/products/partials/product-card.blade.php`

→ load view

→ done

That’s it.

It didn’t care whether that partial needed one product, a list of products, or a composed object with multiple models. We’re now going to fix that.

The Rules (The Contract Between View and Data)

To make the system predictable and maintainable, there need to be rules. After experimenting, I came up with six clear steps that define how a partial route resolves data.

Find the correct partial to load Every request like `/products/partials/product-card/2` should map directly to `resources/views/products/partials/product-card.blade.php`.
Find the resource from the first segment The first segment `products` is always the model reference. It’s converted to singular form `product` to locate the model: `App\Models\Product`.
Decide if one or more records are required This comes from the filename prefix. Starts with `products-` → multiple records Starts with `product-` → single record
Extract the DTO or ViewModel annotation At the top of each partial, I can define what data structure it expects:`/** @var \App\ViewModels\ProductCardDTO $model */.` This tells the route what class to instantiate and which columns the AQC should select.
Fetch the data using AQC Once the DTO is known, the system calls the AQC Design Pattern class to select the appropriate columns and fetch records from the corresponding model.
Return the rendered HTML Finally, the resolved data is passed to the partial and returned as raw HTML — ideal for HTMX swaps or inline updates.

Example in Action

Let’s take these partials:

/resources/views/products/partials/products-list.blade.php  // multiple
/resources/views/products/partials/product-card.blade.php   // single
/resources/views/products/partials/product-row.blade.php    // single
/resources/views/products/partials/product-quick-view.blade.php // single

And these URLs:

/products/partials/products-list 
/products/partials/product-card/2
/products/partials/product-row/2 
/products/partials/product-quick-view/2

Here’s the global route refactored.

use App\Helpers\PartialApiResolver;

Route::match(['get', 'post'], '{path}', function(string $path, Request $request){
    return App\Helpers\PartialApiResolver::handle($path, $request);
})->where('path', '.*');

And here's the helper class with all 6 steps.

<?php
namespace App\Helpers;

use Illuminate\Http\Request;
use Illuminate\Support\Str;

class PartialApiResolver
{
    public static function handle(string $path, Request $request)
    {
        $path = trim($path, '/');
        if ($path === '') abort(404);

        $segments = explode('/', $path);
        $id = self::extractId($segments);
        $viewPath = self::viewPath($segments);
        $resourceName = self::detectResource($segments);
        $dtoClass = self::extractDto($segments);
        $data = self::fetchData($resourceName, $id, $dtoClass, $request);

        return view($viewPath, $data);
    }

    private static function extractId(array &$segments): ?int
    {
        $maybeLast = end($segments);
        if (is_numeric($maybeLast)) {
            array_pop($segments);
            return (int) $maybeLast;
        }
        return null;
    }

    private static function viewPath(array $segments): string
    {
        return implode('.', $segments);
    }

    private static function detectResource(array $segments): ?string
    {
        $resourceSegment = $segments[0] ?? null;
        return $resourceSegment ? Str::singular($resourceSegment) : null;
    }

    private static function extractDto(array $segments): ?string
    {
        $bladeFile = resource_path('views/' . implode('/', $segments) . '.blade.php');
        if (!file_exists($bladeFile)) return null;

        $contents = file_get_contents($bladeFile);
        if (preg_match('/@var\s+([A-Za-z0-9_\\\\<>]+)\s+\$[A-Za-z0-9_]+/m', $contents, $m)) {
            return trim($m[1]);
        }
        return null;
    }

    private static function fetchData(?string $resource, ?int $id, ?string $dto, Request $request): array
    {
        if (!$resource) return [];
        $aqcNamespace = "App\\AQC\\" . ucfirst($resource);
        $columns = $dto && method_exists($dto, 'columns') ? $dto::columns() : '*';

        try {
            if ($id) {
                $aqcClass = "{$aqcNamespace}\\Get" . ucfirst($resource);
                if (!class_exists($aqcClass)) abort(404, "AQC class [$aqcClass] not found.");

                $item = $aqcClass::handle($id, $request->all(), $columns);
                return [$resource => $item ?: new ("App\\Models\\" . ucfirst($resource))];
            } else {
                $aqcClass = "{$aqcNamespace}\\Get" . Str::plural($resource);
                if (!class_exists($aqcClass)) abort(404, "AQC class [$aqcClass] not found.");

                $items = $aqcClass::handle($request->all(), $columns);
                return [Str::plural($resource) => $items];
            }
        } catch (\Throwable $e) {
            return $id
                ? [$resource => new ("App\\Models\\" . ucfirst($resource))]
                : [Str::plural($resource) => collect()];
        }
    }
}

Now that you know how we load partials, let’s look at how we prepare their data at a structural level.

Note before you move on

To fully understand why I’m using DTO classes and the Atomic Query Construction (AQC) pattern in this setup, don’t skip this part. Both are essential to how the Partial API pattern works under the hood. DTOs define the structure of data your Blade partial expects, while AQC defines how that data is fetched. The rest of this article will make a lot more sense once you grasp both pieces—so read carefully.

Using DTO Classes with Blade Partials

In this pattern, every Blade partial should know exactly what data structure it’s getting — and that’s where DTO classes come in. Instead of passing a random collection of variables from your controller or resolver, define a dedicated DTO (or ViewModel) that represents the data contract for that specific partial. For example, a ProductCardDTO might expose only name, price, and imageUrl. This makes your Blade file predictable, testable, and IDE-friendly. If you’ve never structured your Blade files around contracts before, you can read my detailed explanation here: 👉 Don’t Pass Array or Variables to Laravel Blade Views Instead Do This

That article shows how to make each Blade file behave like a component with a well-defined interface, keeping logic where it belongs and leaving the template clean. Once you apply that mindset, the Partial API pattern becomes far more maintainable because every endpoint and partial communicates through a stable contract instead of loose variables.

The Role of the AQC Design Pattern

Behind the DTOs sits the Atomic Query Construction (AQC) pattern. AQC lets you build reusable, composable query classes that encapsulate all data-fetching logic. Instead of sprinkling Model::query() all over your project, each AQC class handles one atomic concern — fetching users, filtering products, calculating stats — and can be reused across controllers, APIs, and partials.

When you combine AQC with DTOs, the flow becomes clean and layered: AQC → DTO → Blade Partial. Your AQC class produces the data. The DTO shapes it. The partial displays it.

You can explore the full pattern in this article: 👉 Introducing the Atomic Query Construction (AQC) Design Pattern

That post dives deeper into why atomic queries outperform ad-hoc query logic and how they integrate naturally with the Partial API pattern described here.

Implementation Notes

Here's what we have done so far.

Detect plural or singular pattern to decide between collection or single model.
Check for numeric ID in the URL (if found, load a single record).
Parse the partial file to extract the DTO or ViewModel class name from annotations.
Pass model and DTO into your AQC pipeline to build queries dynamically.
Graceful fallback: if a record is missing, provide a new model instance instead of throwing an error.

This way, even if you hit a partial like /product/partials/product-card/9999, it still renders without breaking the flow.

Why This Works So Well

Because it combines the predictability of Laravel’s Blade conventions with the flexibility of APIs. HTMX requests behave like AJAX calls but stay fully server-driven. Your AQC pattern handles the data efficiently. And your Blade partials now serve as self-contained, declarative view components that know what data they need.

You don’t have to touch controllers, define routes, or mix JSON and HTML responses. The system just knows what to do.

Final Thoughts

This pattern now feels complete. The first part gave partials their own routes. This part gave them data.

What you have now is a unified layer where every Blade partial can act like an API endpoint — with model discovery, DTO integration, and automatic data fetching.

This is what I have experienced recently. What is your take on this approach? Let's hear your ideas and thoughts.

Laravel Blade Partial API Pattern with HTMX

Raheel Shan — Mon, 20 Oct 2025 11:48:56 +0000

We have seen splendid UIs in this latest era. All thanks to Javascript, which has snatched the rendering responsibility from the backend that was always good at doing it. But it has also come with some cost. On the way to achieving SPA, reactivity, and interactivity, we have faced the following issues.

The SEO Compromised

This is the most important issue. When users or crawlers come to visit our page, the page is empty with a div with an id may be root. Users wait for the page to be loaded, but crawlers go back, marking this page empty without data. This heavily affects the ranking in search engines. To counter this issue, people started to use static site generation. Now that the pages are statically generated, they are not updated frequently, yet another problem to be solved.

The Markup Drift

The real issue isn’t JSX syntax — it’s that markup moved to the JavaScript side. Once that happened, the frontend had to take over everything the backend used to handle effortlessly.

Now the UI stack needs a build pipeline before a single element can render. JSX won’t run on its own, so tools like Babel, Vite, and Webpack become mandatory. Then come TypeScript, linters, formatters, and dependency managers — a full ecosystem just to output HTML.

This shift adds layers of fragility. Every change passes through a build; every runtime error risks a blank screen. The frontend must now fetch data, construct markup, manage reactivity, and coordinate state — all inside one sensitive language runtime.

And because markup no longer comes from the server, everything must be serialized into JSON first. The browser becomes responsible for turning that JSON back into visible UI. Two systems — backend and frontend — must now agree on the same shape of data and structure of views.

We didn’t simplify web development; we just moved the complexity closer to the user’s browser.

The Hidden Cost of JavaScript-Controlled Rendering

When JavaScript took over rendering, the web quietly stopped being simple. Every framework—React, Vue, Svelte, even the old Knockout and Backbone—started rebuilding what the browser was already doing just fine: creating and updating the DOM. Now, instead of writing HTML, frontend engineers spend their time being part-time compiler engineers—setting up build tools, handling hydration, debugging mismatched markup, and wrestling with virtual DOMs. What used to be a plain document has turned into a fragile choreography between server and client, where one small issue can break rendering, kill performance, or confuse search engines. We ended up building complex systems mostly to fix problems introduced by the same complexity.

How to Avoid JavaScript Hell

Since we have given JavaScript the responsibility to render/hydrate the frontend and have stuck with what we have experienced, what if we take back the responsibility from JavaScript and make it a little simple? Let Javascript only do what it is best at. We are simply going to use a few techniques.

Let's start step by step. First we are going to load a full page with Laravel Blade.

Let's say we need to display a list of products in a table. Each row will have a refresh button. A very basic example. We will do the below code.

class ProductController extends Controller
{
    public function index(Request $request)
    {
        $products = Product::paginate(10);
        return view('product.index', compact('products'));
    }
}

Next, let's load the blade view.

// resources/views/product/index.blade.php
@extends('layouts.app')

@section('content')
<div class="container">
    <h2>Products</h2>
    <table>
        <thead>
            <tr>
                <th scope="col">Product</th>
                <th scope="col">Category</th>
                <th scope="col">Brand</th>
                <th scope="col">Actions</th>
            </tr>
        </thead>
        <tbody>
            @if (isset($products) && count($products) > 0)
                @foreach ($products as $product)
                    @include('product.partials.table.row',['product' => $product])
                @endforeach
            @endif

        </tbody>
    </table>
</div>
@endsection

Do pay attention to how we are adding a partial inside loop.

You must load HTMX in your page before using it. HTMX installation.

//resources/views/product/partials/table/row.blade.php
<tr id="product-{{ $product->id }}">
    <td>{{ $product->name }}</td>
    <td>{{ $product->category }}</td>
    <td>{{ $product->brand }}</td>
    <td>
        <button 
            type="button"
            hx-get="{{ url('product/partials/table/row/'. $product->id) }}" 
            hx-target="#product-{{ $product->id }}"
            hx-swap="outerHTML" 
            class="btn btn-sm btn-primary mb-3">
            Refresh
        </button>    
    </td>
</tr>

And here we are telling HTMX to refresh the current product row. We have provided it with a unique ID product-x and an API endpoint to fetch partial from.

Now let's move to Laravel routes.

Global Arrival Route Setup

To make this pattern fully reusable across any part of the application, we define a single global route that will handle all incoming requests for Blade partials through HTMX.

use Illuminate\Support\Str;
use Illuminate\Support\Facades\View;
use Illuminate\Http\Request;

Route::match(['get', 'post'], '{path}', function ($path, Request $request) {
    // convert "product/partials/table/row" to "product.partials.table.row"
    $viewPath = str_replace('/', '.', $path);

    // ensure view exists
    if (!View::exists($viewPath)) {
        abort(404, "Partial [$viewPath] not found.");
    }

    // split segments for context
    $segments = explode('/', $path);

    // detect model name (singular or plural)
    $modelSegment = $segments[0] ?? null;
    $modelName = ucfirst(Str::singular($modelSegment));
    $modelClass = "App\\Models\\$modelName";

    $data = [];

    // only attempt model binding if model class exists
    if (class_exists($modelClass)) {
        // if last segment is numeric, assume it’s an ID → single item
        $last = end($segments);
        if (is_numeric($last)) {
            $data = [Str::lower($modelName) => $modelClass::findOrFail($last)];
        }
        // if plural model segment detected → fetch collection
        elseif (Str::plural($modelSegment) === $modelSegment) {
            $data = [Str::lower(Str::plural($modelName)) => $modelClass::all()];
        }
    }

    return view($viewPath, $data);
})->where('path', '.*');

This route is responsible for:

Handling both GET and POST requests so partials can support form submissions or dynamic interactions.
Parsing the requested URL to determine which Blade partial should be loaded.
Loading any dynamic data required by that partial. (This is currently experimental.)
Returning a fully Blade-rendered HTML partial back to HTMX.

This global route acts like a content dispatcher. Once it is configured, any partial inside your views directory becomes instantly accessible through HTMX calls, simply by referencing its path as a URL. It removes repetitive route creation and keeps your backend clean while enabling front-end interactivity powered by Blade and HTMX.

HTMX request → Arrival Route → Resolve Partial → Fetch Data → Return Rendered HTML

With this approach in place, you can focus on building partials and dynamic UI behavior without needing dedicated routes for every small UI update.

Another example.

Let's say we need to refresh the whole table this time and we are defining a button to refresh the table data. In this case, here is the example.

@extends('layouts.app')

@section('content')
<div class="container">
    <h2>Products</h2>
    <button 
        type="button"
        hx-get="{{ url('product/partials/table') }}" 
        hx-target="#product-rows"
        hx-swap="innerHTML" 
        class="btn btn-sm btn-primary mb-3">
        Refresh Table
    </button>       
    <table>
        <thead>
            <tr>
                <th scope="col">Product</th>
                <th scope="col">Category</th>
                <th scope="col">Brand</th>
                <th scope="col">Actions</th>
            </tr>
        </thead>
        <tbody id="product-rows">
            @include('products.partials.table.list',['products' => $products])
        </tbody>
    </table>
</div>
@endsection

And again, extract the partial where needed.

//resources/views/product/partials/table/list.blade.php

@if (isset($products) && count($products) > 0)
    @foreach ($products as $product)
        @include('products.partials.table.row',['product' => $product])
    @endforeach
@endif

In this setup we need to respect some rules. Here we go.

Rule 1—Directory equals URL

Every request path directly maps to a Blade file under resources/views. /product/partials/form → resources/views/product/partials/form.blade.php

Rule 2 — Dots replace slashes

Internally, Laravel views use dot notation, so the route simply replaces / with . before rendering.

Rule 3 — Any depth allowed

There’s no fixed folder depth. The resolver supports nested structures like /product/partials/table/row → product.partials.table.row

Rule 4 — No model or data assumptions

The resolver doesn’t inject or infer data. Every partial is responsible for its own context (passed from the parent view or controller).

Rule 5 — 404 for missing partials

If the resolved view doesn’t exist, the route gracefully fails with a 404. No silent fallbacks, no guesswork.

Rule 6 — Both GET and POST supported

The same route handles GET and POST, so it can respond to hx-get, hx-post, or form submissions without extra definitions.

Rule 7 — Everything is a partial endpoint

Any Blade file—model-specific or global—can act as an endpoint. You’re free to mix singular (product) or plural (products) folders; the router doesn’t care.

How This Solves the SEO Problem

When the page first loads, Laravel renders everything—a fully formed HTML document with all partials in place. Search engines see a complete, server-rendered page.

After that, HTMX takes over. The same partials that were included during the initial load can now be reloaded individually via the same Blade templates and route pattern.

That means:

The page is crawlable and SEO-friendly.
The partials are reusable.
You’re not duplicating frontend logic or templates.

Why This Pattern Works

No duplication. The same Blade partials power both full-page and partial loads.
SEO intact. The first render is full HTML, not JavaScript-rendered fluff.
Reusable. Any component can be loaded standalone or as part of a bigger page.
Simple routing. One global route pattern controls all partial endpoints.
No JSON. The browser never has to assemble UI from raw data again.

This is Laravel doing what Laravel does best: serving clean HTML from the server, enhanced with just enough JavaScript to feel dynamic.

A Simpler Future

The Blade Partial API Pattern isn’t a framework or a library. It’s just Laravel used properly—with HTMX as the final piece that gives your pages dynamic behavior without losing their soul. It’s fast, indexable, and human to read. Server-driven UI, but done right. No build tools, no JSON, no magic—just Blade.

Final Thoughts

The beauty of this pattern is that every request still flows through Laravel’s full stack—middleware, validation, gates, and permissions. You’re not giving up structure or safety for convenience. Each Blade partial can be protected, validated, or even transformed the same way as any API route. The difference is that the response isn’t JSON—it’s ready-to-render markup, straight from the server, exactly as Laravel intended.

It’s not about going backward. It’s about taking what’s already powerful and using it as it was meant to be used—without pretending the browser needs to be a compiler.

Ending Notes

This article is experimental, and I am going to do a bit more research so we can complete all scenarios. if you are interested. Subscribe to my blog and stay tuned.