К содержимому

Laravel Scout: настройка поиска на Ubuntu 24.04

Scout добавляет полнотекстовый поиск по моделям Laravel через драйвер из SCOUT_DRIVER. Настройка занимает несколько шагов: пакет, драйвер, трейт в модели, импорт существующих записей и проверка выдачи. Всё выполняется на сервере, где проект уже работает.

Руководство Laravel 3 мин чтения

01Проверьте, что проект готов к установке Scout

Зайдите в каталог проекта и убедитесь, что Laravel отвечает и база доступна. Версию показывает php artisan --version, наличие таблиц проверяет php artisan migrate:status. Если проект ещё не создан, его разворачивают по отдельной инструкции, здесь нужен рабочий сайт с моделью, по которой будет поиск.

bash
cd /var/www/example.com
php artisan --version
php artisan migrate:status

02Установите пакет Scout

Пакет ставят через Composer от владельца проекта, без sudo. После установки файл config/scout.php не публикуется: Scout читает настройки из .env, а конфиг публикуют только при необходимости. Для публикации есть команда php artisan vendor:publish --tag=scout-config.

bash
composer require laravel/scout

03Выберите драйвер в.env

Драйвер задаёт переменная SCOUT_DRIVER. Без неё Scout использует algolia, поэтому для локальной проверки без внешнего сервиса ставят database или collection. Драйвер database ищет обычными LIKE-запросами по полям из toSearchableArray(), полнотекстовый индекс MySQL ему не нужен. Для meilisearch и typesense дополнительно задают адрес и ключ движка.

ini
SCOUT_DRIVER=database
SCOUT_QUEUE=false

04Добавьте трейт Searchable в модель

Модель, по которой идёт поиск, получает трейт Laravel\Scout\Searchable. Метод toSearchableArray() возвращает поля, которые попадут в индекс: без него Scout индексирует все атрибуты модели. После правки модель нужно сохранить, чтобы изменения подхватились.

php
<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

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

05Загрузите существующие записи в индекс

Записи, которые уже лежат в базе, попадают в индекс командой scout:import с полным именем класса модели в кавычках. Новые и изменённые записи Scout индексирует сам при сохранении модели. Если задан SCOUT_QUEUE=true, индексация уходит в очередь, и её должен разбирать обработчик php artisan queue:work.

bash
php artisan scout:import "App\Models\Post"

06Проверьте поиск из консоли

Запрос через Post::search() возвращает коллекцию найденных моделей. Выведите количество и заголовки, чтобы увидеть, что выдача не пустая. Пустой результат чаще всего значит, что поля в toSearchableArray() пустые или в SCOUT_DRIVER указан не тот драйвер.

bash
php artisan tinker
App\Models\Post::search('laravel')->count()

07Проверьте поиск на сайте

Откройте страницу с поиском и введите слово, которое точно есть в заголовке записи. Убедитесь, что результат приходит из Scout, а не из обычного запроса Eloquent. Если на сервере включён php artisan optimize, правку .env подхватит только новый php artisan optimize или php artisan config:clear.

bash
php artisan config:clear
php artisan optimize

Частые ошибки

  • Поиск возвращает пустой результат при драйвере database.

    Проверьте, что toSearchableArray() возвращает непустые поля и что в SCOUT_DRIVER стоит нужный драйвер. Полнотекстовый индекс MySQL драйверу database не требуется, он ищет через LIKE.

  • После composer require laravel/scout нет файла config/scout.php.

    Scout не публикует конфиг при установке. Файл создаёт php artisan vendor:publish --tag=scout-config, без него настройки берутся из .env.

  • Новые записи не находятся, хотя старые в индексе есть.

    При SCOUT_QUEUE=true индексация идёт через очередь. Запустите php artisan queue:work и проверьте, что задания разбираются без ошибок.

  • После правки .env драйвер не меняется.

    Конфиг закэширован командой php artisan optimize. Выполните php artisan config:clear или php artisan optimize заново, чтобы новые значения попали в приложение.

Deploykin

Как это делается в Deploykin

В Deploykin сайт на Laravel создаётся из панели: стек под приложение, key:generate и storage:link выполняются при создании, а доступы к базе сами попадают в .env. Деплой идёт без простоя, с миграциями и кэшами, а очереди держат демоны Horizon или Queue Worker.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Какой драйвер Scout выбрать без внешнего поискового сервиса?

Для проверки на сервере подойдёт database: он ищет через LIKE по полям из toSearchableArray() и не требует отдельного движка. collection работает в памяти и годится только для небольших наборов данных.

Нужен ли полнотекстовый индекс MySQL для драйвера database?

Нет. Драйвер database строит обычные LIKE-запросы по полям из toSearchableArray(), FULLTEXT-индекс для него не нужен.

Как загрузить в индекс записи, которые уже есть в базе?

Командой php artisan scout:import "App\Models\Post" с полным именем класса модели. Новые и изменённые записи Scout индексирует сам при сохранении.

Почему поиск не видит новые записи?

Если в .env стоит SCOUT_QUEUE=true, индексация попадает в очередь. Её разбирает php artisan queue:work, без запущенного обработчика записи в индекс не попадают.

Ещё по теме

Laravel: руководство по установке и настройке: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.