Scout Full-Text Search

## What the trait wires up **Laravel Scout** is a first-party package that mirrors Eloquent models into a search engine. You opt a model in by adding the `Laravel\Scout\Searchable` trait. When the model class boots, the trait's `bootSearchable()` method does three things: - registers a **`ModelObserver`** that listens to the model's Eloquent events; - adds a `SearchableScope`, which gives Eloquent queries and relations `searchable()` and `unsearchable()` macros; - adds `searchable()` / `unsearchable()` macros to collections of models. Nothing else in the app changes: you keep calling `save()`, `create()` and `delete()`, and the observer keeps the index in step. | Eloquent event | What the observer does | |---|---| | `saved` (create or update) | upserts the record, or removes it if `shouldBeSearchable()` now returns false | | `deleted` | removes the record, or keeps it flagged `__soft_deleted` when `scout.soft_delete` is true and the model soft-deletes | | `forceDeleted` | removes the record | | `restored` | upserts the record again | ## The document: toSearchableArray() Each model becomes one **document** in the index. Its content is whatever `toSearchableArray()` returns. The default implementation returns `$this->toArray()`, so every visible attribute, including appended ones, is sent. In a recipe catalogue you normally override it to send only what users search or filter on: 1. the `title`; 2. the `ingredients` text; 3. a `cuisine` or `vegetarian` field you want to filter with `where()`. Keeping the array small matters: every byte is shipped on every save, and hosted engines often bill or limit by record size. Returning an empty array tells the Meilisearch engine, for example, to skip that record. ## The index name: searchableAs() `searchableAs()` names the index. Its default is `config('scout.prefix')` followed by the model's table name, so a `Recipe` model lands in `recipes`, or in `staging_recipes` when `SCOUT_PREFIX=staging_`. The prefix lets several environments or tenants share one search service. Override `searchableAs()` to pick another name. The key stored with each document comes from `getScoutKey()`, the primary key by default. ## Deciding what gets indexed Two hooks run inside the observer on every save: - **`shouldBeSearchable()`** returns `true` by default. Return `false` for unpublished recipes and the observer removes them instead of indexing them. - **`searchIndexShouldBeUpdated()`** also returns `true` by default. Return `false` when only irrelevant columns changed, for example `return $this->wasRecentlyCreated || $this->wasChanged(['title', 'ingredients']);`. `withoutSyncingToSearch(fn () => ...)` pauses syncing for one model class while a closure runs, which is useful for bulk maintenance you plan to reindex afterwards. ## Searching returns Eloquent models `Recipe::search('basil')` returns a `Laravel\Scout\Builder`, not an Eloquent query. When you call `get()`: 1. the engine runs the text search and returns matching keys; 2. Scout loads those rows from your database with a `whereIn` on the key; 3. you receive an Eloquent `Collection` of `Recipe` models, in the engine's ranking order. Because the rows come from the database, a stale index can return fewer models than it matched, but never data that is no longer in your table. Use `raw()` when you want the engine's own response instead. ## Where automatic sync stops The observer only hears **Eloquent model events**. These writes do not fire them, so the index silently drifts: - mass updates and deletes on a query, such as `Recipe::where('cuisine', 'thai')->update([...])`; - `DB::table('recipes')` statements and raw SQL; - writes made by another application or a database console. The repair tools are the query macro `Recipe::where(...)->searchable()`, which chunks the matching rows and upserts them, and the `scout:import` command for a whole model. For the `database` and `collection` engines there is no separate index to drift, which is one reason small apps start there. ## Interview traps Interviewers probe the edges of this model with a few recurring follow-ups: - **"Does Scout index existing rows when you add the trait?"** No. The observer only reacts to future events; rows already in the table reach an external index through `scout:import`. - **"What about soft deletes?"** By default a soft-deleted recipe is removed from the index. With `scout.soft_delete` set to `true`, Scout keeps it with a `__soft_deleted` flag, and `withTrashed()` or `onlyTrashed()` on the search builder bring it back into results. - **"Can one model use a different engine?"** Yes: override `searchableUsing()` on that model. - **"Why are my results Eloquent models with relations missing?"** Hydration is a plain `whereIn`; eager-load through the search builder's `query()` callback.