feat: add Scout package - full-text search for Hypervel

[binaryfire]

Summary

This PR introduces Hypervel Scout, a full-text search package for Eloquent models ported from Laravel Scout and adapted for Hypervel's Swoole-based coroutine environment.

Key Features

Search Engines

• Meilisearch - Production-ready full-text search with typo-tolerance and instant search
• Typesense - Fast, typo-tolerant search engine with automatic schema management
• Database - LIKE queries and native full-text search (MySQL FULLTEXT, PostgreSQL tsvector) with no external dependencies
• Collection - In-memory filtering for testing
• Null - Disabled search for environments where search isn't needed

Core Functionality

• Automatic indexing - Models are indexed on save and removed on delete via model callbacks
• Batch operations - searchable() and unsearchable() macros on query builders and collections
• Soft delete support - Index and search soft-deleted records with withTrashed() / onlyTrashed()
• Fluent search builder - where(), whereIn(), whereNotIn(), orderBy(), take(), pagination
• Custom keys - Use UUIDs, ULIDs, or any unique identifier via getScoutKey() / getScoutKeyName()
• Conditional indexing - Control what gets indexed via shouldBeSearchable()
• Search callbacks - Customize queries with callbacks and raw result access

Hypervel-Specific Adaptations

Laravel Scout	Hypervel Scout	Rationale
ModelObserver class with static state	registerCallback() with Context	Coroutine-safe state management
Queues or synchronous execution	Coroutine::defer() by default	Non-blocking indexing after response
Sequential command processing	WaitConcurrent parallel execution	Leverages Swoole coroutines for fast imports
Static $syncingDisabledFor	Context::set() / Context::get()	Per-coroutine isolation
config('scout.queue') boolean	queue.enabled + queue.after_commit	Explicit control with transaction safety
Process-level engine caching via Manager	Static $engines array	Worker-level caching for Swoole

Additional Features Not in Laravel Scout

• SearchableInterface contract - Explicit interface for type-safe searchable models
• command_concurrency config - Control parallel coroutine count during bulk imports (default: 50)

Features Not Ported from Laravel Scout

• Algolia engine - Meilisearch and Typesense cover the same use cases as open-source alternatives
• scout:queue-import command - Replaced by WaitConcurrent parallel processing in standard import
• MakeRangeSearchable job - Range-based queue import replaced by concurrent coroutine processing

Architecture

src/scout/
├── Attributes/               # PHP 8 attributes for database engine
│   ├── SearchUsingFullText.php
│   └── SearchUsingPrefix.php
├── Console/                  # Artisan commands
│   ├── DeleteAllIndexesCommand.php
│   ├── DeleteIndexCommand.php
│   ├── FlushCommand.php
│   ├── ImportCommand.php
│   ├── IndexCommand.php
│   └── SyncIndexSettingsCommand.php
├── Contracts/                # Interfaces
│   ├── PaginatesEloquentModels.php
│   ├── PaginatesEloquentModelsUsingDatabase.php
│   ├── SearchableInterface.php
│   └── UpdatesIndexSettings.php
├── Engines/                  # Search engine implementations
│   ├── CollectionEngine.php
│   ├── DatabaseEngine.php
│   ├── MeilisearchEngine.php
│   ├── NullEngine.php
│   └── TypesenseEngine.php
├── Events/                   # Import/flush events
├── Exceptions/               # Scout-specific exceptions
├── Jobs/                     # Queue jobs for async indexing
├── Builder.php               # Fluent search query builder
├── Engine.php                # Abstract engine base class
├── EngineManager.php         # Engine factory and resolution
├── Scout.php                 # Utility class for job customization
├── Searchable.php            # Model trait with event handling
├── SearchableScope.php       # Global scope for batch macros
├── ScoutServiceProvider.php  # Service provider
└── config/scout.php          # Configuration

Usage

Basic Setup

use Hypervel\Database\Eloquent\Model;
use Hypervel\Scout\Contracts\SearchableInterface;
use Hypervel\Scout\Searchable;

class Post extends Model implements SearchableInterface
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}

Searching

// Basic search
$posts = Post::search('query')->get();

// With filters and ordering
$posts = Post::search('query')
    ->where('status', 'published')
    ->whereIn('category_id', [1, 2, 3])
    ->orderBy('created_at', 'desc')
    ->paginate(15);

Commands

php artisan scout:import "App\Models\Post"      # Import with parallel coroutines
php artisan scout:import "App\Models\Post" --fresh  # Flush and reimport
php artisan scout:flush "App\Models\Post"       # Remove all from index
php artisan scout:sync-index-settings           # Sync Meilisearch settings

Configuration

Key configuration options in config/scout.php:

return [
    'driver' => env('SCOUT_DRIVER', 'collection'),
    'prefix' => env('SCOUT_PREFIX', ''),

    'queue' => [
        'enabled' => env('SCOUT_QUEUE', false),
        'after_commit' => env('SCOUT_AFTER_COMMIT', false),
    ],

    'command_concurrency' => env('SCOUT_COMMAND_CONCURRENCY', 50),
    'soft_delete' => env('SCOUT_SOFT_DELETE', false),

    'meilisearch' => [
        'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
        'key' => env('MEILISEARCH_KEY'),
        'index-settings' => [
            // Per-model settings
        ],
    ],

    'typesense' => [
        'client-settings' => [...],
        'model-settings' => [
            // Per-model collection schema and search parameters
        ],
    ],
];

Engine-Specific Helpers

MeilisearchEngine includes a generateTenantToken() convenience method for multi-tenant applications. This implements Meilisearch's recommended multi-tenancy pattern where all tenants share a single index and tenant tokens enforce data isolation at query time:

$engine = app(EngineManager::class)->engine('meilisearch');
$token = $engine->generateTenantToken([
    'posts' => ['filter' => "tenant_id = {$tenantId}"]
]);
// Use token for frontend-direct search with scoped access

This is a driver-specific helper, not a core Scout feature.

Testing Considerations

• Use collection driver for unit tests (in-memory, no external dependencies)
• Use null driver to disable search entirely in test environments
• withoutSyncingToSearch() is coroutine-safe for isolating test cases
• Engine instances are statically cached - use EngineManager::forgetEngines() to reset between tests

Changes vs Laravel Scout

1. Models must implement SearchableInterface in addition to using the Searchable trait. Required for proper type safety / PHPStan level 5
2. Queue configuration uses queue.enabled instead of a simple queue boolean
3. No Algolia support - use Meilisearch or Typesense instead
4. syncWithSearchUsing() returns null by default instead of falling back to default queue connection

Related Documentation

• Configuration: src/scout/config/scout.php

[Copilot]

Pull request overview

This PR introduces Hypervel Scout, a comprehensive full-text search package adapted from Laravel Scout for Hypervel's Swoole-based coroutine environment. The package provides multiple search engine implementations (Meilisearch, Typesense, Database, Collection, Null) with automatic indexing, batch operations, soft delete support, and a fluent search builder API.

Key Changes:

• Full-text search infrastructure with coroutine-safe state management using Context API
• Five search engine implementations with different use cases
• Test infrastructure supporting parallel test execution with unique prefixes
• Queue-based or deferred indexing with configurable concurrency
• Comprehensive test suite including unit, feature, and integration tests

Reviewed changes

Copilot reviewed 90 out of 91 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/bootstrap.php	Test bootstrap for loading .env configuration
tests/Support/*.php	Base test cases for Meilisearch and Typesense integration tests with parallel safety
tests/Scout/migrations/*.php	Database migrations for test models
tests/Scout/Models/*.php	Test model implementations for various scenarios
tests/Scout/Unit/*.php	Unit tests for core Scout functionality
tests/Scout/Feature/*.php	Feature tests for search engines and coroutine safety
tests/Scout/Integration/*.php	Integration tests for Meilisearch and Typesense
src/scout/src/Searchable.php	Core trait providing search capabilities with coroutine-safe state
src/scout/src/SearchableScope.php	Global scope adding batch search macros to query builder
src/scout/src/Scout.php	Utility class for job customization and engine access
src/scout/src/Jobs/*.php	Queue job implementations for async indexing
src/scout/src/Exceptions/*.php	Scout-specific exception classes
src/scout/src/Events/*.php	Event classes for import/flush operations
src/scout/src/ScoutServiceProvider.php	Service provider for Scout registration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 90 out of 91 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.