---
title: "Laravel Searchable від Mozex: пошук по зв'язках і поліморфних моделях одним скопом"
url: https://laravelukraine.com/blog/laravel-searchable-vid-mozex-posuk-po-zviazkax-i-polimorfnix-modeliax-odnim-skopom
date: 2026-11-13
---

# Laravel Searchable від Mozex: пошук по зв'язках і поліморфних моделях одним скопом

[Laravel Searchable](https://github.com/mozex/laravel-searchable) від розробника Mozex додає Eloquent-моделі трейт, який шукає по її власних колонках, по зв'язаних записах і по поліморфних зв'язках через один скоп `search()`. Пакет помітили в [огляді Laravel News](https://laravel-news.com/mozex-laravel-searchable), а найцікавіше в ньому - те, як він обходиться з `morphTo` і з таблицями Filament.

Задача знайома кожному, хто збирав адмінку. Пошук по коментарях має знаходити не лише текст коментаря, а й ім'я автора та заголовок поста чи відео, до якого коментар прив'язано. Зазвичай це закінчується стосом `orWhereHas`, а для поліморфного зв'язку ще й `whereHasMorph` з переліком типів. Пакет переносить цей опис у модель і робить його декларативним.

### Як підключити

Пакет ставиться через Composer, міграцій немає:

```bash
  composer require mozex/laravel-searchable
```

Далі трейт `Searchable` і метод `searchableColumns()`, у якому перелічено все, по чому треба шукати. Власні колонки, звичайні зв'язки і поліморфні можна змішувати в одному масиві:

```php
  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-запитом:

```php
  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()` моделі:

```php
  TextColumn::make('title')
      ->advancedSearchable(except: ['author.name'])
      ->sortable(),
```

Ранжування в таблицях вмикається саме: пакет додає глобальний скоп запиту таблиці. Поки нічого не шукають, ваш `defaultSort` працює як раніше. Під час пошуку першою йде релевантність, а `defaultSort` розбиває нічиї. Якщо користувач клікнув заголовок колонки, виграє його сортування. Для глобального пошуку панелі є окремий провайдер `SearchableGlobalSearchProvider`, а ресурс без `getGloballySearchableAttributes()` до нього не потрапляє.

### Чим це відрізняється від spatie/laravel-searchable

Назви однакові, задачі різні. [spatie/laravel-searchable](https://github.com/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](https://github.com/mozex/laravel-searchable/releases/tag/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, і автор цього не приховує.
