Laravel Searchable від розробника Mozex додає Eloquent-моделі трейт, який шукає по її власних колонках, по зв'язаних записах і по поліморфних зв'язках через один скоп search(). Пакет помітили в огляді Laravel News, а найцікавіше в ньому - те, як він обходиться з morphTo і з таблицями Filament.
Задача знайома кожному, хто збирав адмінку. Пошук по коментарях має знаходити не лише текст коментаря, а й ім'я автора та заголовок поста чи відео, до якого коментар прив'язано. Зазвичай це закінчується стосом orWhereHas, а для поліморфного зв'язку ще й whereHasMorph з переліком типів. Пакет переносить цей опис у модель і робить його декларативним.
Як підключити
Пакет ставиться через Composer, міграцій немає:
composer require mozex/laravel-searchable
Далі трейт Searchable і метод searchableColumns(), у якому перелічено все, по чому треба шукати. Власні колонки, звичайні зв'язки і поліморфні можна змішувати в одному масиві:
use Mozex\Searchable\Searchable;
class Comment extends Model
{
use Searchable;
public function searchableColumns(): array
{
return [
'body', // колонка самої моделі
'author.name', // BelongsTo
'tags.name', // зв'язок "один до багатьох"
'commentable:post.title', // morphTo на Post
'commentable:video.name', // morphTo на Video
];
}
public function commentable(): MorphTo
{
return $this->morphTo();
}
}
Головне, що search() - це скоп, а не окремий пошуковий об'єкт. Він загортає свої умови в одну групу WHERE (... OR ...), тож запит лишається звичайним Eloquent-запитом:
Comment::query()
->where('published', true)
->with('author')
->search($request->input('q'))
->paginate();
Якщо потрібні дефолти інші, ніж у пакета, php artisan searchable:install публікує config/searchable.php.
Зв'язки і типізований синтаксис для morph
Правило просте: крапка - для звичайних зв'язків, двокрапка - для поліморфних. Шлях через крапку може бути будь-якої глибини, останній сегмент - це колонка, усе перед ним - ланцюжок зв'язків: author.company.name, comments.author.team.name.
З morphTo пакет не вгадує, на яку модель дивитися, і вимагає назвати тип явно: commentable:post.title. Тип має збігатися з аліасом у вашому Relation::morphMap(). Після типу можна йти далі по зв'язках цільової моделі: commentable:post.author.name спершу розв'язує morph до Post, а потім шукає ім'я його автора. Якщо ж написати просто commentable.title, без типу, пакет цю колонку пропустить, а не здогадуватиметься.
Ще кілька деталей, які вирішують за вас, а не перекладають на вас:
- Кілька слів.
search('Doe Jane') знайде «Jane Doe»: кожне слово має збігтися хоч десь, але не обов'язково в одній колонці й не в тому ж порядку. Лапки тримають фразу разом. Розбиття зупиняється на 10 словах, це налаштовується параметром maxTerms.
- Регістр ігнорується навіть на бінарних колаціях MySQL, бо пакет приводить до нижнього регістру обидві сторони. Виняток - SQLite, де це працює лише для ASCII.
- Символи
% і _ у запиті екрануються, тож користувач, який ввів _, не отримає всю таблицю.
- Колонки на окремий запит перевизначаються параметрами
in, include і except.
- Зв'язки на іншому з'єднанні з базою пакет помічає сам: робить окремий запит, бере до 50 ключів і підставляє їх через
whereIn.
Сортування за релевантністю і Filament
Результати повертаються не за id, а за тим, наскільки добре вони збігаються. Порядок у searchableColumns() задає пріоритет: збіг у першій колонці важить більше, ніж у п'ятій. Усередині колонки точний збіг стоїть вище за префікс, а префікс вище за входження посередині рядка. Для зв'язків глибше одного кроку діє спрощена оцінка «збіглося чи ні». Власне orderBy() перед search() лишається головним сортуванням, а релевантність розбиває нічиї. Вимкнути ранжування можна через orderByRelevance: false.
У Filament пакет реєструє макрос advancedSearchable() на TextColumn. Достатньо одної колонки, і пошук таблиці піде по всіх searchableColumns() моделі:
TextColumn::make('title')
->advancedSearchable(except: ['author.name'])
->sortable(),
Ранжування в таблицях вмикається саме: пакет додає глобальний скоп запиту таблиці. Поки нічого не шукають, ваш defaultSort працює як раніше. Під час пошуку першою йде релевантність, а defaultSort розбиває нічиї. Якщо користувач клікнув заголовок колонки, виграє його сортування. Для глобального пошуку панелі є окремий провайдер SearchableGlobalSearchProvider, а ресурс без getGloballySearchableAttributes() до нього не потрапляє.
Чим це відрізняється від spatie/laravel-searchable
Назви однакові, задачі різні. spatie/laravel-searchable збирає результати з кількох моделей і навіть зовнішніх джерел в одну колекцію SearchResult, згруповану за типом. Це інструмент для сторінки «знайти по всьому сайту».
Пакет Mozex нічого не об'єднує. Він фільтрує один Eloquent-запит однієї моделі і повертає той самий Query Builder. Тому він природно лягає туди, де вже є запит із умовами, жадібним завантаженням і пагінацією: у список у контролері, в API-ендпоінт, у таблицю Filament.
Зі Scout пакет теж не конфліктує технічно, хоча обидва дають моделі search(). Автор радить у такому разі перейменувати скоп через аліас трейта (scopeSearch as scopeDatabaseSearch) і передати нову назву в макрос: advancedSearchable(method: 'databaseSearch').
Межі: це LIKE, а не повнотекстовий пошук
Автор пакета пише про це прямо в README, і варто сприйняти це серйозно. Усе компілюється в LIKE '%term%'. Провідний % не дає використати B-tree-індекс, тож пошукова колонка сканується повністю, а кожен зв'язок чи morph-зв'язок додає корельований підзапит EXISTS. Кожне додаткове слово в запиті додає ще одну групу OR у WHERE.
Що з цього випливає на практиці:
- індекс на самій пошуковій колонці не допоможе, а от індекси на колонках, по яких ви фільтруєте поруч (
tenant_id, status), дадуть базі відсіяти рядки до LIKE;
- у Postgres реально прискорити
LIKE '%term%' може GIN-індекс pg_trgm;
- на мільйонах рядків або з багатьма зв'язками в
searchableColumns() час переходити на Laravel Scout з Meilisearch, Typesense чи Algolia, або на повнотекстові індекси бази;
- ранжування рахується лише по рядках, що пройшли
WHERE, тож його ціна залежить від кількості збігів, а не від розміру таблиці.
Вимоги і чи варто брати
Пакет під ліцензією MIT, потребує PHP 8.2+ і Laravel 12.69+ або 13.30+. Підтримку Laravel 11 прибрали у версії 1.3.0, і автор пояснює чому: три advisory, опубліковані після кінця підтримки Laravel 11, виправили лише в Laravel 12 і 13. На Laravel 11 Composer лишить вас на 1.2.2. Filament - опційна залежність, підтримуються версії 4 і 5.
Майте на увазі, що пакет молодий і невеликий: репозиторій з'явився у квітні 2026 року і його розвиває один автор. А в 1.2.1 змінилася поведінка пошуку з кількох слів: раніше search('jane doe') шукав рядок цілком, тепер шукає слова окремо. Якщо вам потрібна стара поведінка, передайте maxTerms: 1.
Брати його варто для адмінок, внутрішніх панелей і невеликих каталогів, де пошук має «дотягуватися» до зв'язаних і поліморфних записів, а ставити окремий пошуковий рушій зарано. Особливо якщо у вас Filament: ранжування таблиць без жодного рядка коду - відчутний виграш. Для публічного пошуку по великих обсягах він не заміна Scout, і автор цього не приховує.