README

This package makes it easy to add full text search support to your models with Laravel 12 and 13.

Important

The features from the Scout driver in this repo have been merged upstream into Laravel Scout natively.

So we've temporarily paused development in this repo and plan to instead address any issues or improvements in the native Laravel Scout driver instead.

If there are any Typesense-specific features that would be hard to implement in Laravel Scout natively (since we need to maintain consistency with all the other drivers), then at that point we plan to add those features into this driver and maintain it as a "Scout Extended Driver" of sorts. But it's too early to tell if we'd want to do this, so we're in a holding pattern on this repo for now.

In the meantime, we recommend switching to the native Laravel Scout driver and report any issues in the Laravel Scout repo.

Installation
Usage
Migrating from siberfx/typesense-scout
Authors
License

Installation

The Typesense PHP SDK uses httplug to interface with various PHP HTTP libraries through a single API.

First, install the correct httplug adapter based on your guzzlehttp/guzzle version. For example, if you're on Laravel 8, which includes Guzzle 7, then run this:

composer require php-http/guzzle7-adapter

Then install the driver:

composer require siberfx/typesense-scout

And add the service provider:

// config/app.php
'providers' => [
    // ...
    Siberfx\Typesense\TypesenseServiceProvider::class,
],

Ensure you have Laravel Scout as a provider too otherwise you will get an "unresolvable dependency" error

// config/app.php
'providers' => [
    // ...
    Laravel\Scout\ScoutServiceProvider::class,
],

Add SCOUT_DRIVER=typesense to your .env file

Then you should publish scout.php configuration file to your config directory

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

In your config/scout.php add:

'typesense' => [
    'api_key'         => 'abcd',
    'nodes'           => [
      [
        'host'     => 'localhost',
        'port'     => '8108',
        'path'     => '',
        'protocol' => 'http',
      ],
    ],
    'nearest_node'    => [
        'host'     => 'localhost',
        'port'     => '8108',
        'path'     => '',
        'protocol' => 'http',
    ],
    'connection_timeout_seconds'   => 2,
    'healthcheck_interval_seconds' => 30,    
    'num_retries'                  => 3,
    'retry_interval_seconds'       => 1,
  ],

Usage

If you are unfamiliar with Laravel Scout, we suggest reading it's documentation first.

After you have installed scout and the Typesense driver, you need to add the Searchable trait to your models that you want to make searchable. Additionaly, define the fields you want to make searchable by defining the toSearchableArray method on the model and implement TypesenseSearch:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Siberfx\Typesense\Interfaces\TypesenseDocument;
use Laravel\Scout\Searchable;

class Todo extends Model implements TypesenseDocument
{
    use Searchable;
    
     /**
     * Get the indexable data array for the model.
     *
     * @return array
     */
    public function toSearchableArray()
    {
        return array_merge(
            $this->toArray(), 
            [
                // Cast id to string and turn created_at into an int32 timestamp
                // in order to maintain compatibility with the Typesense index definition below
                'id' => (string) $this->id,
                'created_at' => $this->created_at->timestamp,
            ]
        );
    }

     /**
     * The Typesense schema to be created.
     *
     * @return array
     */
    public function getCollectionSchema(): array {
        return [
            'name' => $this->searchableAs(),
            'fields' => [
                [
                    'name' => 'id',
                    'type' => 'string',
                ],
                [
                    'name' => 'name',
                    'type' => 'string',
                ],
                [
                    'name' => 'created_at',
                    'type' => 'int64',
                ],
            ],
            'default_sorting_field' => 'created_at',
        ];
    }

     /**
     * The fields to be queried against. See https://typesense.org/docs/0.24.0/api/search.html.
     *
     * @return array
     */
    public function typesenseQueryBy(): array {
        return [
            'name',
        ];
    }    
}

Then, sync the data with the search service like:

php artisan scout:import App\\Models\\Todo

After that you can search your models with:

Todo::search('Test')->get();

Adding via Query

The searchable() method will chunk the results of the query and add the records to your search index. Examples:

$todo = Todo::find(1);
$todo->searchable();

$todos = Todo::where('created_at', '<', now())->get();
$todos->searchable();

Multi Search

You can send multiple search requests in a single HTTP request, using the Multi-Search feature.

$searchRequests = [
    [
      'collection' => 'todo',
      'q' => 'todo'
    ],
    [
      'collection' => 'todo',
      'q' => 'foo'
    ]
];

Todo::search('')->searchMulti($searchRequests)->paginateRaw();

Generate Scoped Search Key

You can generate scoped search API keys that have embedded search parameters in them. This is useful in a few different scenarios:

You can index data from multiple users/customers in a single Typesense collection (aka multi-tenancy) and create scoped search keys with embedded filter_by parameters that only allow users access to their own subset of data.
You can embed any search parameters (for eg: exclude_fields or limit_hits) to prevent users from being able to modify it client-side.

When you use these scoped search keys in a search API call, the parameters you embedded in them will be automatically applied by Typesense and users will not be able to override them.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
use Siberfx\Typesense\Concerns\HasScopedApiKey;
use Siberfx\Typesense\Interfaces\TypesenseDocument;

class Todo extends Model implements TypesenseDocument
{
    use Searchable, HasScopedApiKey;
}

Usage

Generate a scoped search key from a parent search-only API key, embedding the parameters you want to enforce (e.g. a per-tenant filter_by and/or an expires_at), then use it for searching:

// Generate a scoped key that locks searches to a single tenant.
$scopedKey = Todo::generateScopedSearchKey('parent-search-only-key', [
    'filter_by'  => 'company_id:42',
    'expires_at' => now()->addHour()->timestamp,
]);

// Use a (pre-)generated scoped key for subsequent searches.
Todo::setScopedApiKey($scopedKey)->search('todo')->get();

You can also create new API keys server-side:

app(\Siberfx\Typesense\Typesense::class)->createApiKey([
    'description' => 'Search-only key',
    'actions'     => ['documents:search'],
    'collections' => ['*'],
]);

Filtering

Standard Scout where, whereIn and whereNotIn clauses are supported:

Todo::search('shoes')
    ->where('user_id', 1)
    ->whereIn('status', ['open', 'in_progress'])
    ->whereNotIn('team_id', [9, 10])
    ->get();

For comparison and range filters, pass the operator as an array value:

Todo::search('shoes')
    ->where('price', ['>', 100])        // price:>100
    ->where('rating', ['[3..5]'])       // rating:[3..5]
    ->get();

Boolean values are rendered as Typesense literals (true/false) automatically.

Vector / Hybrid Search

Search a vector field by nearest neighbours. Use nearestNeighbors() to build the vector_query for you:

// Pure vector search: query '*' plus a vector field.
Todo::search('*')
    ->nearestNeighbors('embedding', [0.12, 0.34, 0.56], k: 10)
    ->get();

// Hybrid search: combine a text query with a vector query.
Todo::search('running shoes')
    ->nearestNeighbors('embedding', $vector, k: 20, distanceThreshold: 0.3, alpha: 0.4)
    ->get();

Or pass a raw vector_query string for full control:

Todo::search('*')
    ->vectorQuery('embedding:([0.12, 0.34, 0.56], k:10, alpha:0.4)')
    ->get();

Synonyms, Curation, Aliases & Analytics

Collection-level admin operations are available on the Typesense instance (resolve it from the container or via the Typesense facade).

use Siberfx\Typesense\Typesense;

$typesense = app(Typesense::class);

// Synonyms (per collection)
$typesense->upsertSynonym('todos', 'coat-synonyms', [
    'synonyms' => ['blazer', 'coat', 'jacket'],
]);
$typesense->retrieveSynonyms('todos');
$typesense->retrieveSynonym('todos', 'coat-synonyms');
$typesense->deleteSynonym('todos', 'coat-synonyms');

// Curation / overrides (per collection)
$typesense->upsertOverride('todos', 'promote-tidy', [
    'rule'     => ['query' => 'tidy', 'match' => 'exact'],
    'includes' => [['id' => '123', 'position' => 1]],
]);
$typesense->retrieveOverrides('todos');
$typesense->retrieveOverride('todos', 'promote-tidy');
$typesense->deleteOverride('todos', 'promote-tidy');

// Collection aliases
$typesense->upsertAlias('todos', ['collection_name' => 'todos_v2']);
$typesense->retrieveAliases();
$typesense->retrieveAlias('todos');
$typesense->deleteAlias('todos');

// Analytics rules
$typesense->upsertAnalyticsRule('popular-todos', [
    'type'   => 'popular_queries',
    'params' => [/* ... */],
]);
$typesense->retrieveAnalyticsRules();
$typesense->retrieveAnalyticsRule('popular-todos');
$typesense->deleteAnalyticsRule('popular-todos');

Presets, Stopwords, Stemming, Conversation & NL Models

use Siberfx\Typesense\Typesense;

$typesense = app(Typesense::class);

// Search presets
$typesense->upsertPreset('listing', ['value' => ['query_by' => 'name']]);
$typesense->retrievePresets();
$typesense->retrievePreset('listing');
$typesense->deletePreset('listing');

// Stopwords
$typesense->upsertStopword('common', ['stopwords' => ['a', 'the'], 'locale' => 'en']);
$typesense->retrieveStopwords();
$typesense->retrieveStopword('common');
$typesense->deleteStopword('common');

// Stemming dictionaries (no delete endpoint)
$typesense->upsertStemmingDictionary('plurals', [['word' => 'people', 'root' => 'person']]);
$typesense->retrieveStemmingDictionaries();
$typesense->retrieveStemmingDictionary('plurals');

// Conversation models (conversational / RAG search)
$typesense->createConversationModel([
    'model_name'         => 'openai/gpt-3.5-turbo',
    'api_key'            => 'OPENAI_API_KEY',
    'history_collection' => 'conversation_store',
]);
$typesense->retrieveConversationModels();
$typesense->retrieveConversationModel('model-id');
$typesense->updateConversationModel('model-id', ['system_prompt' => '...']);
$typesense->deleteConversationModel('model-id');

// Natural language search models
$typesense->createNLSearchModel(['model_name' => 'openai/gpt-4', 'api_key' => '...']);
$typesense->retrieveNLSearchModels();
$typesense->retrieveNLSearchModel('nl-model-id');
$typesense->updateNLSearchModel('nl-model-id', [/* ... */]);
$typesense->deleteNLSearchModel('nl-model-id');

Migrating from siberfx/laravel-typesense

Replace siberfx/laravel-typesense in your composer.json requirements with siberfx/typesense-scout
The Scout driver is now called typesense, instead of typesensesearch. This should be reflected by setting the SCOUT_DRIVER env var to typesense, and changing the config/scout.php config key from typesensesearch to typesense
Instead of importing Siberfx\Typesense\*, you should import Siberfx\Typesense\*
Instead of models implementing Siberfx\Typesense\Interfaces\TypesenseSearch, they should implement Siberfx\Typesense\Interfaces\TypesenseDocument

Testing

composer install
vendor/bin/phpunit

The suite has two groups:

Unit — pure logic (filter building, scoped key generation, config shape, public API surface). No server required.
Integration — end-to-end flows against a real Typesense server (collections, documents, filtered search, synonyms, overrides, aliases, presets, stopwords). These are skipped automatically when no server is reachable. Point them at a server via environment variables:
```
TYPESENSE_HOST=localhost TYPESENSE_PORT=8108 \
TYPESENSE_PROTOCOL=http TYPESENSE_API_KEY=xyz \
vendor/bin/phpunit --testsuite Integration
```

Authors

Anonymous

Other key contributors include:

License

The MIT License (MIT). Please see the License File for more information.

siberfx / typesense-scout

Maintainers

Package info

Statistics

Security

README

Contents

Installation

Usage

Adding via Query

Multi Search

Generate Scoped Search Key

Usage

Filtering

Vector / Hybrid Search

Synonyms, Curation, Aliases & Analytics

Presets, Stopwords, Stemming, Conversation & NL Models

Migrating from siberfx/laravel-typesense

Testing

Authors

License