Laravel Scout Array Driver Laravel Package

Getting Started

The ArrayEngine is an in-memory Scout driver: it lets search() calls run against a plain PHP array instead of Meilisearch/Algolia/Typesense. That makes it a test-time and local-dev tool, not a production engine.

1. Require Scout 11 and the engine's v5 major together — v5 is the release that aligns with Scout 11's builder internals:

   composer require laravel/scout:^11
   composer require --dev <engine-package>:^5.0
   

2. Point Scout at it. For tests, do it in phpunit.xml so it applies before the app boots:

   <env name="SCOUT_DRIVER" value="array"/>
   

   For local-only use, register the driver in config/scout.php:

   'array' => ['driver' => 'array'],
   

3. First use case: a feature test that hits a search endpoint without a container running.

   public function test_search_returns_published_posts(): void
   {
       Post::factory()->create(['title' => 'Laravel queues', 'status' => 'published']);
       Post::factory()->create(['title' => 'Laravel queues', 'status' => 'draft']);
   
       $this->get('/search?q=queues')
           ->assertOk()
           ->assertJsonCount(1, 'data');
   }
   

Where to look first: the ArrayEngine class itself (update(), delete(), search()), the service provider's Scout::extend('array', ...) registration, and the engine's handling of the builder's where/orderBy clause arrays — that last one is exactly what #34 touched.

Implementation Patterns

Test isolation over mocking. Prefer the array driver to hand-rolled Scout::shouldReceive(...) mocks. Because Searchable models index on saved, a factory create is enough to make a record findable — no explicit indexing step.

Filtering and sorting now behave like Scout 11. The v5 fix means the engine reads the same clause shape Scout 11's Builder emits, so this works as written:

Post::search('queues')
    ->where('status', 'published')
    ->whereIn('tag', ['php', 'laravel'])
    ->orderBy('published_at', 'desc')
    ->paginate(15);

Treat this as a contract test on your query shape (does the controller build the right builder?), not on relevance.

Trait hooks still apply. searchableAs(), shouldBeSearchable(), and toSearchableArray() are honored on write, so you can test that draft records never enter the index without touching a real engine.

Local dev fallback. Set SCOUT_DRIVER=array in .env.local / a non-production env so sail up-style workflows don't require Meilisearch. Combine with Searchable::withoutSyncingToSearch(fn () => ...) in seeders when the index volume is large and irrelevant to the page you're building.

Custom engines. If you need extra behavior (custom operators, relevance stubs), extend ArrayEngine and re-register the driver in a service provider rather than editing vendor code:

Scout::extend('array', fn ($app) => new CustomArrayEngine($app['config']));

Assertions worth writing. Result IDs and ordering, pagination totals (total()), and that a deleted model disappears ($post->delete() then Post::search('queues')->get() is empty).

Gotchas and Tips

• Hard requirement on Scout 11. v5 exists because Scout 11 changed the where/orderBy builder format. On Scout 10 the engine will silently drop or misread clauses, so pin v4 if you cannot upgrade Scout. This is the single most likely upgrade failure.
• State is per-process, not persisted. php artisan scout:import and scout:flush against the array driver write to memory that dies with the command. Do not use it to "populate" anything, and do not expect data to survive across requests under PHP-FPM or Octane. Index-then-query must happen in the same test method.
• Not a relevance oracle. Matching rules are simplified versus Meilisearch/Typesense — no typo tolerance, no ranking scores, no highlighting. Green tests here do not license you to delete an integration test against the real engine for search-quality-sensitive features.
• Case sensitivity and partial matches differ. Assert on data you control (distinct titles, explicit status fields) rather than assuming LIKE-style behavior.
• Config caching bites tests. If phpunit.xml sets SCOUT_DRIVER but a cached config.php exists locally, the env var is ignored. Run php artisan config:clear when a driver switch "doesn't take".
• Debugging: dump config('scout.driver') inside the test to confirm the driver, and Post::search('x')->toArray() — no wait, use ->get()->pluck('id') — to see what the builder actually produced. If clauses vanish, you are almost certainly on the wrong Scout/engine major pair.
• Extension point to watch on future Scout releases. Any engine that reimplements clause parsing must track Scout's internal builder array shape; this package broke once already on that boundary. Pin the major version and read the release notes on every Scout bump.