Laravel Scout: настройка поиска на Ubuntu 24.04
Scout добавляет полнотекстовый поиск по моделям Laravel через драйвер из SCOUT_DRIVER. Настройка занимает несколько шагов: пакет, драйвер, трейт в модели, импорт существующих записей и проверка выдачи. Всё выполняется на сервере, где проект уже работает.
01Проверьте, что проект готов к установке Scout
Зайдите в каталог проекта и убедитесь, что Laravel отвечает и база доступна. Версию показывает php artisan --version, наличие таблиц проверяет php artisan migrate:status. Если проект ещё не создан, его разворачивают по отдельной инструкции, здесь нужен рабочий сайт с моделью, по которой будет поиск.
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.
composer require laravel/scout
03Выберите драйвер в.env
Драйвер задаёт переменная SCOUT_DRIVER. Без неё Scout использует algolia, поэтому для локальной проверки без внешнего сервиса ставят database или collection. Драйвер database ищет обычными LIKE-запросами по полям из toSearchableArray(), полнотекстовый индекс MySQL ему не нужен. Для meilisearch и typesense дополнительно задают адрес и ключ движка.
SCOUT_DRIVER=database
SCOUT_QUEUE=false
04Добавьте трейт Searchable в модель
Модель, по которой идёт поиск, получает трейт Laravel\Scout\Searchable. Метод toSearchableArray() возвращает поля, которые попадут в индекс: без него Scout индексирует все атрибуты модели. После правки модель нужно сохранить, чтобы изменения подхватились.
<?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.
php artisan scout:import "App\Models\Post"
06Проверьте поиск из консоли
Запрос через Post::search() возвращает коллекцию найденных моделей. Выведите количество и заголовки, чтобы увидеть, что выдача не пустая. Пустой результат чаще всего значит, что поля в toSearchableArray() пустые или в SCOUT_DRIVER указан не тот драйвер.
php artisan tinker
App\Models\Post::search('laravel')->count()
07Проверьте поиск на сайте
Откройте страницу с поиском и введите слово, которое точно есть в заголовке записи. Убедитесь, что результат приходит из Scout, а не из обычного запроса Eloquent. Если на сервере включён php artisan optimize, правку .env подхватит только новый php artisan optimize или php artisan config:clear.
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 PHP Laravel: пошаговая настройка проекта на Ubuntu 24.04 Создайте проект Laravel на PHP 8.3 в Ubuntu 24.04: Composer,.env, MySQL, миграции, nginx, кэш и проверка запуска. Команды и типичные ошибки.
- Руководство · Laravel Filament в Laravel: установка и настройка панели Установка Filament 5 в Laravel на Ubuntu 24.04: панель /admin, пользователь, ресурс Customer, доступ на сервере и проверка входа без ошибки 403.
- Руководство · Laravel Laravel Livewire: установка и первый компонент на Ubuntu 24.04 Установка Livewire 4 в Laravel на Ubuntu 24.04: создание компонента, вывод на страницу, настройка nginx для livewire.min.js и проверка работы в браузере.
- Руководство · Laravel Laravel API: пошаговая настройка на Ubuntu 24.04 Как поднять API в Laravel на Ubuntu 24.04: установка Sanctum, маршруты в routes/api.php, проверка через curl, ответы 401 и 404, кэш и деплой.
- Руководство · Laravel Laravel Eloquent: настройка и проверка на Ubuntu 24.04 Пошаговая настройка Eloquent в Laravel на Ubuntu 24.04: подключение MySQL, миграции, модели, связи, проверка через tinker и маршрут.
- Руководство · Laravel Laravel install: установка фреймворка на Ubuntu 24.04 Пошаговая установка Laravel на Ubuntu 24.04: проверка PHP 8.3, composer create-project, ключ приложения,.env, миграции и запуск через php artisan serve.
Laravel: руководство по установке и настройке: все материалы темы