Add Scout utility class for customizable job dispatch

Introduces Scout utility class with:
- Static $makeSearchableJob and $removeFromSearchJob properties
- makeSearchableUsing() and removeFromSearchUsing() setters
- engine() convenience method for engine access
- resetJobClasses() for test isolation

Updates Searchable trait to dispatch jobs via Scout::$makeSearchableJob
and Scout::$removeFromSearchJob, enabling users to customize job classes
for logging, monitoring, retry behavior, etc.

Author: binaryfire

src/scout/src/Scout.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Scout;
+
+use Hypervel\Scout\Jobs\MakeSearchable;
+use Hypervel\Scout\Jobs\RemoveFromSearch;
+
+/**
+ * Scout utility class for job customization and engine access.
+ *
+ * Provides static configuration for customizing the job classes used
+ * when indexing models via the queue. Set these in a service provider
+ * boot method to use custom job implementations.
+ *
+ * Note: These static properties are set at boot time and read during
+ * request handling. This is safe in Swoole/coroutine environments
+ * because they store class names (strings), not stateful objects.
+ */
+class Scout
+{
+    /**
+     * The job class that makes models searchable.
+     *
+     * @var class-string<MakeSearchable>
+     */
+    public static string $makeSearchableJob = MakeSearchable::class;
+
+    /**
+     * The job class that removes models from the search index.
+     *
+     * @var class-string<RemoveFromSearch>
+     */
+    public static string $removeFromSearchJob = RemoveFromSearch::class;
+
+    /**
+     * Get a Scout engine instance by name.
+     */
+    public static function engine(?string $name = null): Engine
+    {
+        return app(EngineManager::class)->engine($name);
+    }
+
+    /**
+     * Specify the job class that should make models searchable.
+     *
+     * @param class-string<MakeSearchable> $class
+     */
+    public static function makeSearchableUsing(string $class): void
+    {
+        static::$makeSearchableJob = $class;
+    }
+
+    /**
+     * Specify the job class that should remove models from the search index.
+     *
+     * @param class-string<RemoveFromSearch> $class
+     */
+    public static function removeFromSearchUsing(string $class): void
+    {
+        static::$removeFromSearchJob = $class;
+    }
+
+    /**
+     * Reset the job classes to their defaults.
+     *
+     * Useful for testing to ensure clean state between tests.
+     */
+    public static function resetJobClasses(): void
+    {
+        static::$makeSearchableJob = MakeSearchable::class;
+        static::$removeFromSearchJob = RemoveFromSearch::class;
+    }
+}

src/scout/src/Searchable.php

@@ -13,8 +13,6 @@
 use Hypervel\Database\Eloquent\Builder as EloquentBuilder;
 use Hypervel\Database\Eloquent\Collection;
 use Hypervel\Database\Eloquent\SoftDeletes;
-use Hypervel\Scout\Jobs\MakeSearchable;
-use Hypervel\Scout\Jobs\RemoveFromSearch;
 use Hypervel\Support\Collection as BaseCollection;
 
 /**
@@ -151,7 +149,8 @@ public function queueMakeSearchable(Collection $models): void
         }
 
         if (static::getScoutConfig('queue.enabled', false)) {
-            $pendingDispatch = MakeSearchable::dispatch($models)
+            $jobClass = Scout::$makeSearchableJob;
+            $pendingDispatch = $jobClass::dispatch($models)
                 ->onConnection($models->first()->syncWithSearchUsing())
                 ->onQueue($models->first()->syncWithSearchUsingQueue());
 
@@ -195,7 +194,8 @@ public function queueRemoveFromSearch(Collection $models): void
         }
 
         if (static::getScoutConfig('queue.enabled', false)) {
-            $pendingDispatch = RemoveFromSearch::dispatch($models)
+            $jobClass = Scout::$removeFromSearchJob;
+            $pendingDispatch = $jobClass::dispatch($models)
                 ->onConnection($models->first()->syncWithSearchUsing())
                 ->onQueue($models->first()->syncWithSearchUsingQueue());
 

tests/Scout/Unit/QueueDispatchTest.php

@@ -8,6 +8,7 @@
 use Hypervel\Database\Eloquent\Collection;
 use Hypervel\Scout\Jobs\MakeSearchable;
 use Hypervel\Scout\Jobs\RemoveFromSearch;
+use Hypervel\Scout\Scout;
 use Hypervel\Support\Facades\Bus;
 use Hypervel\Tests\Scout\Models\SearchableModel;
 use Hypervel\Tests\Scout\ScoutTestCase;
@@ -20,6 +21,12 @@
  */
 class QueueDispatchTest extends ScoutTestCase
 {
+    protected function tearDown(): void
+    {
+        Scout::resetJobClasses();
+        parent::tearDown();
+    }
+
     public function testQueueMakeSearchableDispatchesJobWhenQueueEnabled(): void
     {
         $this->app->get(ConfigInterface::class)->set('scout.queue.enabled', true);
@@ -144,4 +151,50 @@ public function testEmptyCollectionDoesNotDispatchRemoveFromSearchJob(): void
 
         Bus::assertNotDispatched(RemoveFromSearch::class);
     }
+
+    public function testQueueMakeSearchableDispatchesCustomJobClass(): void
+    {
+        $this->app->get(ConfigInterface::class)->set('scout.queue.enabled', true);
+
+        Scout::makeSearchableUsing(TestCustomMakeSearchable::class);
+
+        Bus::fake([TestCustomMakeSearchable::class]);
+
+        $model = new SearchableModel(['title' => 'Test', 'body' => 'Content']);
+        $model->id = 1;
+
+        $model->queueMakeSearchable(new Collection([$model]));
+
+        Bus::assertDispatched(TestCustomMakeSearchable::class);
+    }
+
+    public function testQueueRemoveFromSearchDispatchesCustomJobClass(): void
+    {
+        $this->app->get(ConfigInterface::class)->set('scout.queue.enabled', true);
+
+        Scout::removeFromSearchUsing(TestCustomRemoveFromSearch::class);
+
+        Bus::fake([TestCustomRemoveFromSearch::class]);
+
+        $model = new SearchableModel(['title' => 'Test', 'body' => 'Content']);
+        $model->id = 1;
+
+        $model->queueRemoveFromSearch(new Collection([$model]));
+
+        Bus::assertDispatched(TestCustomRemoveFromSearch::class);
+    }
+}
+
+/**
+ * Custom job class for testing custom MakeSearchable dispatch.
+ */
+class TestCustomMakeSearchable extends MakeSearchable
+{
+}
+
+/**
+ * Custom job class for testing custom RemoveFromSearch dispatch.
+ */
+class TestCustomRemoveFromSearch extends RemoveFromSearch
+{
 }

tests/Scout/Unit/ScoutTest.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Scout\Unit;
+
+use Hypervel\Scout\Engine;
+use Hypervel\Scout\EngineManager;
+use Hypervel\Scout\Jobs\MakeSearchable;
+use Hypervel\Scout\Jobs\RemoveFromSearch;
+use Hypervel\Scout\Scout;
+use Hypervel\Tests\Scout\ScoutTestCase;
+use Mockery as m;
+
+/**
+ * Tests for the Scout utility class.
+ *
+ * @internal
+ * @coversNothing
+ */
+class ScoutTest extends ScoutTestCase
+{
+    protected function tearDown(): void
+    {
+        Scout::resetJobClasses();
+        m::close();
+        parent::tearDown();
+    }
+
+    public function testDefaultMakeSearchableJobClass(): void
+    {
+        $this->assertSame(MakeSearchable::class, Scout::$makeSearchableJob);
+    }
+
+    public function testDefaultRemoveFromSearchJobClass(): void
+    {
+        $this->assertSame(RemoveFromSearch::class, Scout::$removeFromSearchJob);
+    }
+
+    public function testMakeSearchableUsingChangesJobClass(): void
+    {
+        Scout::makeSearchableUsing(CustomMakeSearchable::class);
+
+        $this->assertSame(CustomMakeSearchable::class, Scout::$makeSearchableJob);
+    }
+
+    public function testRemoveFromSearchUsingChangesJobClass(): void
+    {
+        Scout::removeFromSearchUsing(CustomRemoveFromSearch::class);
+
+        $this->assertSame(CustomRemoveFromSearch::class, Scout::$removeFromSearchJob);
+    }
+
+    public function testResetJobClassesRestoresDefaults(): void
+    {
+        Scout::makeSearchableUsing(CustomMakeSearchable::class);
+        Scout::removeFromSearchUsing(CustomRemoveFromSearch::class);
+
+        Scout::resetJobClasses();
+
+        $this->assertSame(MakeSearchable::class, Scout::$makeSearchableJob);
+        $this->assertSame(RemoveFromSearch::class, Scout::$removeFromSearchJob);
+    }
+
+    public function testEngineMethodReturnsEngineFromManager(): void
+    {
+        $engine = m::mock(Engine::class);
+
+        $manager = m::mock(EngineManager::class);
+        $manager->shouldReceive('engine')
+            ->with('meilisearch')
+            ->once()
+            ->andReturn($engine);
+
+        $this->app->instance(EngineManager::class, $manager);
+
+        $result = Scout::engine('meilisearch');
+
+        $this->assertSame($engine, $result);
+    }
+
+    public function testEngineMethodWithNullUsesDefaultEngine(): void
+    {
+        $engine = m::mock(Engine::class);
+
+        $manager = m::mock(EngineManager::class);
+        $manager->shouldReceive('engine')
+            ->with(null)
+            ->once()
+            ->andReturn($engine);
+
+        $this->app->instance(EngineManager::class, $manager);
+
+        $result = Scout::engine();
+
+        $this->assertSame($engine, $result);
+    }
+}
+
+/**
+ * Custom job class for testing makeSearchableUsing().
+ */
+class CustomMakeSearchable extends MakeSearchable
+{
+}
+
+/**
+ * Custom job class for testing removeFromSearchUsing().
+ */
+class CustomRemoveFromSearch extends RemoveFromSearch
+{
+}