Створення пошукового ендпоінту Laravel Scout із HTTP-методом QUERY

HTTP-метод QUERY - це нове доповнення до специфікації HTTP (RFC 10008), розроблене саме для одного завдання: запитів. Це безпечний метод із підтримкою кешування, який передає параметри в тілі запиту, надаючи виразність POST-payload без відмови від read-only семантики GET - і без необхідності втискати складні фільтри в URL, який може досягти обмежень довжини.

Laravel 13.19 додав Http::query() до HTTP-клієнта разом із тестовими хелперами query() та queryJson(). Повноцінний хелпер Route::query() вже злито для Laravel 14, але чекати не обов'язково: роутер Laravel вже сьогодні приймає користувацькі HTTP-дієслова через Route::match(). У цьому tutorial ми використаємо його для побудови невеликого пошукового ендпоінту на основі database-драйвера Laravel Scout.

Коли потрібен метод QUERY

Один пошуковий рядок, як у нашому прикладі, не обов'язково потребує QUERY - метод починає виправдовувати себе, коли запит розростається до чогось, що GET не може зручно обробити:

• Структуровані фільтри з діапазонами, масивами та групами and/or (пошук продуктів чи оголошень)
• Геопросторові запити, що надсилають координати полігонів ("пошук у цій області карти")
• Пакетні запити, що отримують сотні записів за ID
• Пошук за чутливими значеннями, як-от email або телефони, які не повинні потрапляти в URL, логи доступу або історію браузера
• Ендпоінти звітності з діапазонами дат і group-by, які є читанням, але сьогодні моделюються як POST /reports/run

Налаштування проєкту

Починаючи зі свіжого Laravel 13-додатку, встановіть файл API-маршрутів і Scout:

php artisan install:api
composer require laravel/scout

Database-драйвер Scout не потребує зовнішнього пошукового сервісу - він використовує WHERE LIKE запити до вашої існуючої бази даних, що добре підходить для малих і середніх датасетів. Увімкніть його у файлі .env:

SCOUT_DRIVER=database

Далі створіть модель Article з міграцією та фабрикою:

php artisan make:model Article -mf

Міграція визначає поля title та body:

Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();
});

Додайте трейт Searchable до моделі та визначте, які колонки Scout має шукати:

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Article extends Model
{
    use HasFactory, Searchable;

    protected $fillable = ['title', 'body'];

    public function toSearchableArray(): array
    {
        return [
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}

Визначення QUERY-маршруту

Роутер Laravel не підтримує Route::query() у Laravel 13 (він буде доступний починаючи з Laravel 14). Однак роутер Laravel реєструє маршрути для будь-якого дієслова, яке ви передаєте в Route::match(), включно з QUERY.

Додайте наступне до routes/api.php:

use App\Models\Article;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::match(['QUERY'], '/articles/search', function (Request $request) {
    $validated = $request->validate([
        'search' => ['required', 'string'],
        'per_page' => ['sometimes', 'integer', 'between:1,50'],
    ]);

    return Article::search($validated['search'])
        ->paginate($validated['per_page'] ?? 15);
});

Зверніть увагу, що валідація та $request->input() зчитують дані з JSON-тіла запиту так само, як вони робили б це для POST-запиту - без додаткової роботи. Виконання php artisan route:list підтверджує, що маршрут зареєстровано з дієсловом QUERY:

QUERY  api/articles/search

Запит до цього ендпоінту виглядає як POST із GET-семантикою - критерії пошуку передаються в тілі:

QUERY /api/articles/search HTTP/1.1
Content-Type: application/json
Accept: application/json

{"search": "scout", "per_page": 10}

Тестування ендпоінту

Тестовий хелпер queryJson() Laravel 13.19 дзеркалить postJson() та подібні методи, тому тестування ендпоінту відчувається знайомо:

namespace Tests\Feature;

use App\Models\Article;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class ArticleSearchTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_searches_articles_with_the_query_method(): void
    {
        Article::factory()->create(['title' => 'Getting Started With Laravel Scout']);
        Article::factory()->create(['title' => 'Queues in Depth']);

        $this->queryJson('/api/articles/search', ['search' => 'scout'])
            ->assertOk()
            ->assertJsonCount(1, 'data')
            ->assertJsonPath('data.0.title', 'Getting Started With Laravel Scout');
    }

    public function test_it_validates_the_search_term(): void
    {
        $this->queryJson('/api/articles/search', [])
            ->assertUnprocessable()
            ->assertJsonValidationErrors('search');
    }
}

На стороні клієнта HTTP-клієнт Laravel може викликати QUERY-ендпоінти методом Http::query(), доданим у версії 13.19:

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()->query('https://example.com/api/articles/search', [
    'search' => 'scout',
]);

$articles = $response->json('data');

Підводний камінь: вбудований сервер PHP

Якщо ви розробляєте з php artisan serve, запити з методом QUERY отримують відповідь 501 Not Implemented ще до того, як потраплять до Laravel - вбудований сервер жорстко кодує методи запитів, які він приймає. Середовища на основі Nginx, як-от Laravel Herd та Valet, передають метод до вашого додатку. Тестові хелпери Laravel HTTP повністю уникають цієї проблеми, оскільки вони відправляють запити безпосередньо через фреймворк.

Використання QUERY на веб-маршрутах

Наш ендпоінт знаходиться в routes/api.php, тому захист CSRF взагалі не виникає. Однак якщо ви зареєструєте QUERY-маршрут у routes/web.php, ви отримаєте помилку 419: middleware PreventRequestForgery Laravel 13 трактує лише GET, HEAD та OPTIONS як запити читання, тому QUERY отримує ту саму перевірку токена, що й POST. RFC 10008 визначає QUERY як безпечний метод, і наступний мажорний реліз Laravel звільняє його відповідно - але до того часу у вас є два варіанти.

Перший варіант переносить майбутню поведінку, розширюючи middleware та додаючи QUERY до списку read-дієслів:

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery as Middleware;

class PreventRequestForgery extends Middleware
{
    /**
     * Визначити, чи HTTP-запит використовує read-дієслово.
     * QUERY є безпечним методом (RFC 10008), тому трактуємо його як GET.
     * Laravel 14 поставляється з цією поведінкою; видаліть це перевизначення після оновлення.
     */
    protected function isReading($request)
    {
        return in_array($request->method(), ['HEAD', 'GET', 'OPTIONS', 'QUERY']);
    }
}

Потім замініть його в групі middleware web у bootstrap/app.php:

use App\Http\Middleware\PreventRequestForgery;
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery as BasePreventRequestForgery;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->web(replace: [
        BasePreventRequestForgery::class => PreventRequestForgery::class,
    ]);
})

Тепер кожен QUERY-маршрут звільнено від CSRF, тоді як POST, PUT, PATCH та DELETE зберігають повний захист, відповідаючи тому, що Laravel 14 робитиме з коробки. Коли ви оновитеся, видаліть клас і рядок replace, і нічого більше не зміниться.

Другий варіант виключає один маршрут із middleware:

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;

Route::match(['QUERY'], '/articles/search', $handler)
    ->withoutMiddleware(PreventRequestForgery::class);

Це добре працює для разового ендпоінту, але вам потрібно буде пам'ятати про це на кожному QUERY-маршруті, який ви додаєте, і це повністю видаляє middleware з маршруту, а не класифікує дієслово як читання. Оскільки перевизначення middleware - це зміна двох файлів, яка чисто зникає після оновлення, ми б обрали його першим.

Одна примітка щодо перевірки будь-якого підходу: CSRF middleware пропускає перевірку, коли середовище додатка - testing, тому feature-тест не отримає 419, якщо ви спочатку не переназначите середовище (наприклад, $this->app['env'] = 'production'; у методі setUp() вашого тесту).

Нарешті, пам'ятайте, що означає звільнення: фреймворк довіряє, що ваші QUERY-обробники є read-only, так само як він довіряє вашим GET-обробникам. Не змінюйте стан у QUERY-маршруті.

Перед відправкою QUERY у production

Laravel добре обробляє QUERY - маршрути навіть працюють із php artisan route:cache - але фреймворк - це лише один крок у ланцюгу. Кілька речей, які потрібно перевірити перед використанням методу в production API:

• Кожен проміжний сервіс має пропускати метод. Ми вже бачили, як вбудований сервер PHP повертає 501; CDN, WAF та load balancer можуть бути так само категоричними щодо дієслів, які вони не розпізнають. Тестуйте повний шлях від клієнта до додатка, а не лише додаток.
• Браузерні виклики мають застереження. fetch() надсилає QUERY без проблем, але HTML-форми говорять лише GET та POST, і QUERY не є CORS-safelisted методом - кожен cross-origin запит викличе preflight.
• Переваги кешування поки що на папері. RFC визначає QUERY як cacheable, але браузери та CDN ще не реалізують кешування QUERY, тому не приймайте метод лише через цю перевагу сьогодні.
• Інструменти специфікацій наздоганяють. OpenAPI отримав повноцінну операцію query лише у версії 3.2, випущеній у вересні 2025 року - генератори та SDK-ланцюжки інструментів, які все ще орієнтуються на 3.0 або 3.1, не можуть описати ендпоінт, а деякі HTTP-клієнтські бібліотеки жорстко кодують дієслова, які вони приймають.

Жодне з цього не є dealbreaker для внутрішнього API, де ви контролюєте обидва кінці - що також є найпростішим місцем для першої спроби QUERY.

Що далі

Коли вийде наступна мажорна версія Laravel, виклик Route::match(['QUERY'], ...) може стати Route::query('/articles/search', ...), а перевизначення CSRF вище можна видалити - решта коду в цьому tutorial залишається незмінною.

Між маршрутизацією, HTTP-клієнтом і тестовими хелперами Laravel покриває обидва кінці методу QUERY сьогодні. Ви можете дізнатися більше про метод QUERY у RFC 10008 та слідкувати за підтримкою маршрутизації в Pull Request #60655.