HTTP QUERY Method in Laravel

Bheem Sharma

24 July 2026

QUERY is a new HTTP method. The IETF published it as RFC 10008 in June 2026

In short, the HTTP QUERY method in Laravel is a GET request that can carry a body.

It has three key traits:

Safe. It only reads data. It never changes anything on the server.
Idempotent. You can send it ten times. The result stays the same.
Cacheable. A proxy or CDN can store the response, just like a GET response.

Because of this, QUERY sits right between GET and POST. You get the body of POST and the promises of GET.

Why Do We Even Need It?

Think about a product search page in an online store. A shopper picks a brand, a price range, five colours, three sizes, and a sort order.

Today you have two choices. Both hurt.

Option 1: GET With a Long URL

You push every filter into the query string. The URL grows fast:

GET /api/products?brand=nike&color[]=red&color[]=blue&color[]=black&size[]=s&size[]=m&price_min=500&price_max=9000&sort=price_asc

1	GET /api/products?brand=nike&color[]=red&color[]=blue&color[]=black&size[]=s&size[]=m&price_min=500&price_max=9000&sort=price_asc

This works for small filters. However, servers and browsers limit URL length.

Nested filters also look ugly in a URL. Worse, the full filter set lands in your access logs.

Option 2: POST With a Clean Body

So most teams switch to POST

POST /api/products/search

1	POST /api/products/search

The body is clean and easy to read. But now you have a new problem. POST tells every proxy, cache, and client that the request may change data.

As a result, nothing gets cached. Retries also feel risky, even though you are only reading.

Option 3: QUERY

QUERY fixes both problems at once

QUERY /api/products
Content-Type: application/json
{
  "brand": "nike",
  "color": ["red", "blue", "black"],
  "size": ["s", "m"],
  "price": { "min": 500, "max": 9000 },
  "sort": "price_asc"
}

QUERY /api/products

Content-Type: application/json

{

"brand": "nike",

"color": ["red", "blue", "black"],

"size": ["s", "m"],

"price": { "min": 500, "max": 9000 },

"sort": "price_asc"

}

The body stays clean. The request stays safe. Caches can still store the answer.

Where Laravel Stands Today

Laravel 13.19 added support for this method. Symfony 7.4 added it first, so Laravel could build on top of it.

Here is what you get right now

Http::query() in the HTTP client
$this->query() and $this->queryJson() in tests
Route::match(['QUERY'], ...) for your routes

A dedicated Route::query() helper is still open as a pull request. Until it lands, Route::match() does the same job.

Here is how a request using the HTTP QUERY method in Laravel travels from the client to a cacheable response:

Step 1: Register a QUERY Route

Open routes/api.php and add this

use App\Http\Controllers\Api\ProductSearchController;
use Illuminate\Support\Facades\Route;

Route::match(['QUERY'], '/products', ProductSearchController::class);

use App\Http\Controllers\Api\ProductSearchController;

use Illuminate\Support\Facades\Route;

Route::match(['QUERY'], '/products', ProductSearchController::class);

That is all. Laravel now listens for QUERY calls on /api/products.

Step 2: Read the Body in Your Controller

The body works just like a POST body. So $request->input() reads it without any extra setup.

namespace App\Http\Controllers\Api;

use App\Models\Product;
use Illuminate\Http\Request;

class ProductSearchController extends Controller
{
    public function __invoke(Request $request)
    {
        $filters = $request->validate([
            'brand'     => ['nullable', 'string'],
            'color'     => ['nullable', 'array'],
            'price.min' => ['nullable', 'integer', 'min:0'],
            'price.max' => ['nullable', 'integer', 'min:0'],
            'sort'      => ['nullable', 'in:price_asc,price_desc,newest'],
        ]);

        $products = Product::query()
            ->when($filters['brand'] ?? null, fn ($query, $brand) => $query->where('brand', $brand))
            ->when($filters['color'] ?? null, fn ($query, $colors) => $query->whereIn('color', $colors))
            ->when($filters['price']['min'] ?? null, fn ($query, $min) => $query->where('price', '>=', $min))
            ->when($filters['price']['max'] ?? null, fn ($query, $max) => $query->where('price', '<=', $max))
            ->paginate(20);

        return response()->json($products);
    }
}

namespace App\Http\Controllers\Api;

use App\Models\Product;

use Illuminate\Http\Request;

class ProductSearchController extends Controller

{

public function __invoke(Request $request)

{

$filters = $request->validate([

'brand' => ['nullable', 'string'],

'color' => ['nullable', 'array'],

'price.min' => ['nullable', 'integer', 'min:0'],

'price.max' => ['nullable', 'integer', 'min:0'],

'sort' => ['nullable', 'in:price_asc,price_desc,newest'],

]);

$products = Product::query()

->when($filters['brand'] ?? null, fn ($query, $brand) => $query->where('brand', $brand))

->when($filters['color'] ?? null, fn ($query, $colors) => $query->whereIn('color', $colors))

->when($filters['price']['min'] ?? null, fn ($query, $min) => $query->where('price', '>=', $min))

->when($filters['price']['max'] ?? null, fn ($query, $max) => $query->where('price', '<=', $max))

->paginate(20);

return response()->json($products);

}

Notice one rule. Your controller must only read. Never create, update, or delete inside a QUERY route.

Otherwise you break the contract, and caches will serve stale or wrong data.

Step 3: Call the API From Laravel

Laravel’s HTTP client now ships a query() method. It sends JSON by default:

use Illuminate\Support\Facades\Http;

$response = Http::query('https://shop.test/api/products', [
    'brand' => 'nike',
    'color' => ['red', 'blue'],
    'sort'  => 'price_asc',
]);

$products = $response->json();

use Illuminate\Support\Facades\Http;

$response = Http::query('https://shop.test/api/products', [

'brand' => 'nike',

'color' => ['red', 'blue'],

'sort' => 'price_asc',

]);

$products = $response->json();

Do you need form data instead? Then chain asForm():

$response = Http::asForm()->query('https://shop.test/api/products', [
    'brand' => 'nike',
]);

$response = Http::asForm()->query('https://shop.test/api/products', [

'brand' => 'nike',

]);

Step 4: Call It From JavaScript

The Fetch API accepts any method name. So the front end stays simple:

const response = await fetch('/api/products', {
    method: 'QUERY',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
    body: JSON.stringify({
        brand: 'nike',
        color: ['red', 'blue'],
    }),
});

const products = await response.json();

const response = await fetch('/api/products', {

method: 'QUERY',

headers: {

'Content-Type': 'application/json',

'Accept': 'application/json',

body: JSON.stringify({

brand: 'nike',

color: ['red', 'blue'],

}),

});

const products = await response.json();

Step 5: Write a Test

Laravel gives you two helpers for this. Use queryJson() for JSON APIs:

it('filters products by brand', function () {
    Product::factory()->create(['brand' => 'nike']);
    Product::factory()->create(['brand' => 'puma']);

    $this->queryJson('/api/products', ['brand' => 'nike'])
        ->assertOk()
        ->assertJsonCount(1, 'data');
});

it('filters products by brand', function () {

Product::factory()->create(['brand' => 'nike']);

Product::factory()->create(['brand' => 'puma']);

$this->queryJson('/api/products', ['brand' => 'nike'])

->assertOk()

->assertJsonCount(1, 'data');

});

Things to Watch Out For

QUERY is new. Therefore a few pieces of the stack still need to catch up.

Old proxies may block it. Some load balancers and firewalls only allow a fixed list of methods. Check your Nginx, CDN, and WAF rules first.

Browsers are still catching up. Fetch works fine. Native form submits do not support QUERY yet.

Caching needs the body. A normal cache key uses the URL only.

For QUERY, the cache key must include the request body. Please confirm this before you turn caching on.

Keep a fallback. Many public clients cannot send QUERY today. So keep your POST endpoint alive for a while. You can drop it later.

Should You Use It Now?

Start with internal APIs. Your own mobile app, your admin panel, or a service-to-service call all fit well. You control both sides, so nothing breaks.

Wait a bit longer for public APIs. Third-party clients need time to adapt.

Final Thoughts

QUERY solves an old, annoying problem cleanly. For years we forced search into POST and lost caching. Now we have a proper method for reads with a body.

Laravel already supports it. Start with one search endpoint, test it well, and grow from there.