Forem: Raheel Shan

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.

I’m SO Looking Forward to Not Needing a Build System Again

Raheel Shan — Sat, 18 Oct 2025 06:17:37 +0000

Have you been working on the frontend with Javascript? Have you ever noticed what used to be simple <script> has become a full build system? Frontend development has involved more tools than needed just to feel "modern," "reactive," and "interactive". Lets first talk about the problems.

The Compromised SEO

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. 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 problem isn’t JSX syntax—it’s that markup moved to the JavaScript end. When that happened, the backend stopped sending HTML and started sending JSON instead.

Now the frontend has to do many things.

1. The Build Tool Spiral

Once your markup lives in JavaScript, raw files can’t run directly in the browser anymore. You need a build pipeline—Babel, TypeScript, Vite, Webpack, or something else—to transpile JSX, resolve imports, bundle dependencies, minify assets, and compile everything into a format the browser understands. What started as a simple template now requires a full compiler chain just to draw a div.

2. The TypeScript Dependency

Because JSX is code, not markup, you end up mixing presentation with typing rules, interfaces, and generics. You can’t just “return HTML”; you have to satisfy the TypeScript compiler before you can even see what your component looks like.

3. The Tooling Cascade

Once you add TypeScript, you add linters. Once you add linters, you need formatters. Once you add formatters, you add CI checks to enforce them. Your “simple view component” now depends on Node, npm, ESLint, Prettier, and a small stack of plugins. Isn't that great? :)

4. The Build-Time Wall

Every change to the frontend must now pass through a build. You can’t tweak markup and refresh—you have to wait for the bundler to recompile, rebuild, and reload.

5. The Fragile Runtime

If JavaScript fails, the UI fails. Since the markup is built at runtime, there’s no fallback HTML. One syntax error, one missing dependency, or one hydration mismatch and the entire interface collapses—blank screen, cryptic console errors, broken user experience.

6. The Over-Delegation Problem

We’ve given JavaScript far more responsibility than it deserves. It’s now responsible for:

Fetching data
Building markup
Managing state
Rendering updates
Coordinating routing
Each of these used to be handled by the web platform or the backend. Now they all sit on the same fragile runtime that wasn’t designed for this workload.

7. The JSON Middleman

Because markup is gone from the backend, every UI element now depends on a JSON contract. Controllers return data, not views; the frontend reinterprets it into markup. So two systems—backend and frontend—must now stay perfectly in sync about what “a post” or “a user” looks like. That’s duplication. That’s maintenance debt.

It's time to pause and see why we chose a path we never had to in the first place.

What Backend Can Do?

The backend has always been capable of full interactivity. It can render and persist state, handle routes, validate input, and return partial HTML—everything a frontend framework does, but faster and more predictably.

Any backend framework doesn't need a frontend babysitter. It already knows how to build reactive, server-driven interfaces—we just forgot to let it.

How Backend Used to Work and Can Still Do

The backend always gave reactivity on two simple tags.

(anchor) tags for navigation
elements for interaction

Take a look at the snippet below.

<a href="/blog">Blog</a>

This anchor tag tells a browser:

When a user clicks on this link, issue an HTTP GET request to ‘/blog’ and load the response content into the browser window

Here's with the <form> tag.

<form method="post" action="./save-post" >
    <button type="submit" >Save</button>
</form>

The form tag tells the browser:

When form is submitted, issue a post request, process data in the server and let server issue an HTTP Get request in response to form and load the response content into the browser window.

HTMX: HTML That Fights Back

Then comes HTMX, the library that makes HTML behave like it remembers how the web works. No build step. No bundler. No JavaScript build tools. Just attributes that turn your markup alive.

Now consider the following HTML snippet.

<button hx-post="/clicked"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="outerHTML">
    Click Me!
</button>

This tells HTMX:

When a user clicks on this button, issue an HTTP POST request to ‘/clicked’ and use the content from the response to replace the element with the id parent-div in the DOM.

HTMX has gone a step further and implemented this idea to other HTML elements so that they can be interactive as well.

And here's the summary taken from HTMX docs.

Now any element, not just anchors and forms, can issue an HTTP request
Now any event, not just clicks or form submissions, can trigger requests
Now any HTTP verb, not just GET and POST, can be used
Now any element, not just the entire window, can be the target for update by the request

And guess what? What are we receiving from the backend in response?

HTML, not JSON.

Receiving a response in HTML format is deliberate. This gives rendering/hydration responsibility back to the backend, which Javascript snatched in the name of interactivity.

What About Reactivity?

But yes—you’ll sometimes want UI state that reacts instantly without hitting the server. HTMX handles interactivity, not reactivity.

That’s where most people add Alpine.js. It’s light and works fine. I wanted to go one step further, though—something that truly treats the DOM as the source of truth. So I built JSRibbon.

JSRibbon: Reactivity From the DOM Outward

JSRibbon is my ongoing experiment in DOM-first reactivity—a small, component-based library that learns from the last decade of frontend chaos without copying it.

Here’s the heart of it:

The DOM is The State: No virtual layers or hydration. The HTML itself defines current data.

The DOM is the Markup: No additional markup on the Javascript end. DOM is the actual markup to render more nodes when needed.

Event Delegation is Core: Inspired by jQuery’s .on(), events bubble to component roots, so handlers never die when the DOM changes.

Component Composition and Context: Each component has its own scope but can pass state to children—React’s good ideas, minus the ceremony.

Mutation Awareness: A built-in MutationObserver means that if new HTML arrives from HTMX, JSRibbon automatically detects and wires it. Nothing to reinitialize, nothing to refresh manually.

The Quiet Revolution

The mix of Backend + HTMX + JSRibbon doesn’t look flashy—and that’s the point. It gives you reactivity, partial page updates, and component logic without a single build step. You deploy PHP, Blade, and two small JS files. That’s it.

No npm. No transpiler. No “dev mode.” Just clean, reactive, server-first HTML.

Why It Matters

The industry has over-engineered frontends into exhaustion. We ship megabytes of JavaScript to re-render what the server already produced perfectly. HTMX and JSRibbon offer an alternative path: HTML as the API, the DOM as the framework, and the server as the brain.

If this approach catches on—and it should—we may finally get to build interactive web apps that age gracefully instead of breaking every six months.

Livewire without Livewire, Inertia without Inertia, GraphQL without GraphQL. And all with plain Laravel

Raheel Shan — Fri, 10 Oct 2025 19:27:28 +0000

Every few years, the Laravel ecosystem forgets how powerful it actually is. We start believing we need something else on top of it — something that promises “reactivity,” an “SPA feel,” or “exact data fetching.”

So we bolt on Livewire for “no-JS reactivity.” Inertia to feel “modern.” And GraphQL to “fetch only what you need.”

And suddenly, a simple Laravel app has more layers then needed as well as additional learning curves, all trying to fix problems that Laravel already solved.

This article is about walking back from that mess. It's about achieving the goals of these popular tools without ever leaving the comfort and simplicity of plain Laravel.

The Foundation: Laravel Was Always the Component Framework

Laravel’s request-response cycle was never a limitation; it’s the cleanest form of state management in web history. The problem isn’t that Laravel can’t be reactive—it’s that developers stopped using Blade the way it was meant to be used.

Blade was never the problem. It just got treated like a trash bin of mixed markup and business logic. But once you start giving your Blade files contracts and structure, as I explained in Don’t Pass Array or Variables to Laravel Blade Views Instead Do This, the entire architecture changes.

Each Blade partial becomes a real, reusable component.
Each partial expects a defined data shape, enforced by DTOs or queries.
Each partial becomes testable and predictable.

This is the foundation. Now let’s see how it can replace Livewire, Inertia, and GraphQL—one by one.

The Real Problem: We Outsourced What Laravel Does Best

The promise of Livewire, Inertia, and GraphQL stems from three core desires:

Dynamic UI updates without a full page reload.
Seamless data exchange between the backend and frontend.
Reusable, component-based UI parts.

Laravel can already do all of this. We’ve just stopped trusting its native capabilities because of a psychological dependency on JavaScript frameworks. So instead of using Laravel properly, we’ve started wrapping it in unnecessary layers.

Let's strip it down and rebuild from the foundation.

1. Dynamic UI: Livewire without Livewire

Livewire’s idea is clever: run backend logic on the server and send back rendered HTML over AJAX. But you don’t need the entire Livewire runtime to do that. Laravel can already render partial HTML views dynamically.

Here’s how. You can define a global partial route that acts as a universal entry point:

Route::post('{path}', function ($path) {
    // Convert URL path to view dot notation
    $view = str_replace('/', '.', $path);

    // Sanitize to prevent directory traversal, etc.
    $view = preg_replace('/[^A-Za-z0-9_.-]/', '', $view);

    // Logic to resolve models, DTOs, and data based on the path
    // For example, pull the first segment to resolve a model
    $segments = explode('/', $path);
    $modelKey = $segments[0] ?? null;
    $modelInstance = $modelKey ? resolve_model_logic($modelKey) : null; 
    // Your logic here      

    // Check if the Blade partial exists and render it
    if (view()->exists($view)) {
        // Pass relevant data to the view
        return view($view, [$modelKey => $modelInstance]);
    }

    abort(404);
})->where('path', '.*');

This single route acts as a universal entry point. Whenever the frontend hits an API like /user/profile, this route:

Maps it to resources/views/user/profile.blade.php.
Decides which model to load (User in this case)
Passes it through Laravel's validation, policies, and middleware.
Returns ready-made HTML, not JSON.

Your frontend doesn’t care how it happened—it just receives HTML to render. No component classes, no lifecycle hooks, no hydration overhead. Just Laravel doing what it does best.

Any partial can be loaded with relevant data from this universal route for example resources/views/user/partials/list.blade.php can be called with this end point user/partials/list.

2. SPA Feel: Inertia without Inertia

Inertia’s goal is to make Laravel feel like a single-page app—navigating without full reloads. You can achieve the "SPA feel" for form submissions and partial updates with one tiny JavaScript function.

function enhanceForm({
  formId,
  targetId,
  method = null,
  swap = "innerHTML",
  beforeSend = null,
  onSuccess = null,
  onError = null
}) {
  const form = document.getElementById(formId);
  const target = document.getElementById(targetId);

  if (!form || !target) return;

  form.addEventListener("submit", async function (e) {
    e.preventDefault();
    if (typeof beforeSend === "function") beforeSend(form);

    const formData = new FormData(form);
    const reqMethod = method || form.method || "POST";

    try {
      const response = await fetch(form.action, {
        method: reqMethod.toUpperCase(),
        headers: { 'X-Requested-With': 'fetch' },
        body: formData
      });

      const contentType = response.headers.get("content-type") || "";
      const result = contentType.includes("application/json")
        ? await response.json()
        : await response.text();

      if (response.ok) {
        if (typeof onSuccess === "function") onSuccess(result);
        else applySwap(target, result, swap);
      } else {
        if (typeof onError === "function") onError(result, response.status);
        else applySwap(target, `<strong>Error:</strong> ${response.status}`, swap);
      }
    } catch (err) {
      if (typeof onError === "function") onError(err.message, 0);
      else applySwap(target, `<strong>Network Error:</strong> ${err.message}`, swap);
    }
  });
}

function applySwap(target, content, swap) {
  switch (swap) {
    case "outerHTML": target.outerHTML = content; break;
    case "append": target.insertAdjacentHTML("beforeend", content); break;
    case "prepend": target.insertAdjacentHTML("afterbegin", content); break;
    case "innerHTML":
    default: target.innerHTML = content;
  }
}

enhanceForm("myForm", "result");

This helper submits a form asynchronously and swaps the server-rendered HTML response into the DOM. That’s all you need for dynamic pages.

To achieve full SPA-style navigation, you simply extend this idea: write a small script that intercepts link clicks, loads the target page via AJAX, replaces a container like <main>, and updates the browser history using pushState().

Boom. Your app behaves like an SPA, but it’s still a multi-page, server-rendered system under the hood. No JSON hydration, no frontend router, no dual rendering layers.

3. Fetching Data Like GraphQL, Without GraphQL

GraphQL was invented to fix REST’s under- and over-fetching problems by letting you "fetch only what you need." Atomic Query Construction (AQC) and Data Transfer Objects (DTOs) already solve this in a cleaner, native way.

With DTOs, you decide what data shape goes into each partial—it’s explicit, documented, and type-safe.

class SimpleProduct extends BaseDTO
{
    public string $name;
    public string $image;
    public float $price;
    public int $stock;
}

Example with AQC Design Pattern:

namespace App\AQC\User;

use App\Models\User;

class GetUsers
{
    public static function handle($params = [], $paginate = true, $columns = '*')
    {
        $userObj = User::latest('id');

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

        // add more conditions for different use cases

        $userObj->select($columns);

        return $paginate
            ? $userObj->paginate(User::PAGINATE)
            : $userObj->get();
    }
}

Pass that DTO straight into your Blade partial. Done. You get precise data with zero over-fetching. No schemas, no resolvers, no query strings—just pure Laravel. GraphQL made this pattern popular; With Laravel you can make it simple.

The Full Cycle: Bringing It All Together

1. Solving SEO — The Biggest Hidden Problem

SPA-like systems often destroy SEO because everything depends on JavaScript to render content. When crawlers visit, they see an empty root div.

With plain Laravel, we render everything server-side. Your page loads with full HTML and data — perfect for both users and crawlers.

Then, when something changes, instead of reloading the entire page, we fetch the updated partial using AJAX and replace only the relevant part of the DOM.

2. Reusability — The Power of Laravel Partials

When you treat every section of your app as a reusable Blade partial, you start to realize something powerful:

Each partial can:

Be loaded on page load (with all data).
Be individually fetched later via AJAX for updates.

That means the same file acts both as:

The initial render.
The live-update endpoint.

It’s a component system — but server-driven and native.

3. Backend Re-render — No Duplicate Validation and Authentication Logic

The backend re-renders just that one partial with updated data, running it through the same validation, policies, and middleware as always. This means backend is the source of truth not javascript.

4. DOM Update

The lightweight JavaScript helper swaps the returned HTML directly into the page. No reload, no state loss. No hydeation.

Want More Interactivity?

The only missing piece now is navigation. If you can find a tiny javascript library that can do a few things, you are good to go.

Intercepts link clicks.
Updates the browser history using pushState().

Once done, this whole setup stands on the principle of progressive enhancement. It doesn’t punish users—or search engines—if JavaScript takes a day off. Every interaction that happens through Ajax or fetch calls is just a graceful improvement over a fully functional server-rendered page. The HTML you send from Laravel is always complete, crawlable, and independently usable. If someone disables JavaScript, they still get the same data, same structure, and same experience—just with full-page reloads. That’s the real strength of building this way: your site behaves like a single-page app when JavaScript is present, but remains a perfectly valid multi-page Laravel app when it isn’t.

You can easily layer AlpineJS, HTMX, or your favorite micro-reactive system on top.

The Critical Advantage You Gain: Perfect SEO

When you heavily depend on frontend framework for rendering and hyderation of HTML, you often compromise SEO by turning your application into a JavaScript-driven experience. Search engines crawl static HTML, and when your content depends on a dynamic render, your ranking suffers.

With the native Laravel approach, SEO is never a problem. Why? Because we render the full, complete HTML on the first load—just as Laravel does naturally. The content is immediately available for crawlers and users. The dynamic, AJAX-powered partial swaps are a progressive enhancement, not a requirement. You get reactivity without sacrificing your SEO foundation.

The Laravel Native Way Forward

What I’m showing isn’t a library. It’s a mindset:

Render everything through Blade.
Deliver HTML, not JSON.
Structure data with DTOs and AQC.
Swap partials, not full pages.
Stay inside Laravel.

Why This Matters

The more layers we add, the more we drift away from Laravel’s real advantage — its native simplicity and coherence. Every added dependency is another mental model, another bundle of complexity, and another place for things to break.

What I’m advocating for is returning home — to Laravel itself. Let Laravel render your HTML. Let Blade handle your logic. Let small, replaceable partials handle reactivity. And let minimal JavaScript handle your page transitions.

You’ll end up with:

Perfect SEO.
Full control over your templates.
Zero external build systems.
Real-time updates with no extra layer.

All native. All Laravel.

Final Thoughts

We don’t need another framework to make Laravel powerful. We just need to rediscover what it already can do — and stop outsourcing what’s already possible natively.

Livewire without Livewire. Inertia without Inertia. GraphQL without GraphQL. All with plain Laravel.

Sometimes, the best innovation is realizing you already have everything you need.