README

A PHP library for Typesense with attribute-based document mapping, a fluent search API, and optional Doctrine/Symfony integrations.

Installation

composer require enabel/typesense

Quick Start

1. Define a Document

Map your PHP class to a Typesense collection using attributes:

use Enabel\Typesense\Mapping as Typesense;
use Enabel\Typesense\Type\StringType;

#[Typesense\Document(collection: 'products', defaultSortingField: 'popularity')]
class Product
{
    #[Typesense\Id]
    public int $id;

    #[Typesense\Field(facet: true, infix: true)]
    public string $title;

    #[Typesense\Field(sort: true)]
    public float $price;

    #[Typesense\Field]
    public bool $inStock;

    #[Typesense\Field(type: new StringType(array: true), facet: true)]
    public array $tags;

    #[Typesense\Field(sort: true, index: false)]
    public int $popularity;

    #[Typesense\Field]
    public \DateTimeImmutable $createdAt;

    #[Typesense\Field(optional: true)]
    public ?string $description;

    // Computed field — indexed but not written back on denormalization
    #[Typesense\Field]
    public function searchLabel(): string
    {
        return "{$this->title} ({$this->price})";
    }
}

2. Search

use Enabel\Typesense\Search\{Query, Filter, Sort};

$response = $collection->search(
    Query::create('wireless headphones')
        ->queryBy('title', 'description')
        ->filterBy(Filter::all(
            Filter::equals('inStock', true),
            Filter::between('price', 10, 500),
        ))
        ->sortBy('price', Sort::Asc)
        ->facetBy('tags')
        ->perPage(20)
);

foreach ($response->documents as $product) {
    echo "{$product->title} - \${$product->price}\n";
}

echo "Found {$response->found} results across {$response->totalPages} pages\n";

Symfony Bundle

Installation

composer require enabel/typesense symfony/framework-bundle symfony/console

Register the bundle (if not using Symfony Flex):

// config/bundles.php
return [
    // ...
    Enabel\Typesense\Bundle\EnabelTypesenseBundle::class => ['all' => true],
];

Configuration

# config/packages/enabel_typesense.yaml
enabel_typesense:
    client:
        url: '%env(TYPESENSE_URL)%'
        api_key: '%env(TYPESENSE_API_KEY)%'

    collections:
        App\Entity\Product: ~
        App\Entity\Article: ~

When doctrine/orm is installed, the bundle automatically:

• Uses DoctrineDenormalizer as the default denormalizer (search results are fully hydrated Doctrine entities)
• Uses DoctrineDataProvider as the default data provider (for the import command)
• Registers IndexListener to sync entities on persist, update, and remove

No additional configuration is required for the standard Doctrine workflow.

To override the defaults globally or per collection:

enabel_typesense:
    client:
        url: '%env(TYPESENSE_URL)%'
        api_key: '%env(TYPESENSE_API_KEY)%'

    default_denormalizer: app.my_denormalizer     # override global default
    default_data_provider: app.my_data_provider   # override global default

    collections:
        App\Entity\Product: ~
        App\Entity\Article:
            denormalizer: app.article_denormalizer  # override per collection
            data_provider: app.article_provider

Console Commands

# Create all configured collections
php bin/console enabel:typesense:create

# Create a specific collection
php bin/console enabel:typesense:create --class='App\Entity\Product'

# Drop collections (requires --force)
php bin/console enabel:typesense:drop --force
php bin/console enabel:typesense:drop --class='App\Entity\Product' --force

# Import documents (batched in chunks of 100)
php bin/console enabel:typesense:import
php bin/console enabel:typesense:import --class='App\Entity\Product'

# Search a collection
php bin/console enabel:typesense:search 'App\Entity\Product' \
    --query='headphones' \
    --query-by='title,description' \
    --filter='price:<500' \
    --per-page=10

Usage in Services

use Enabel\Typesense\ClientInterface;
use Enabel\Typesense\Search\{Query, Filter, Sort};

class ProductSearchService
{
    public function __construct(
        private ClientInterface $client,
    ) {}

    public function search(string $term, int $page = 1): array
    {
        $response = $this->client->collection(Product::class)->search(
            Query::create($term)
                ->queryBy('title', 'description')
                ->filterBy(Filter::equals('inStock', true))
                ->sortBy('popularity', Sort::Desc)
                ->page($page)
                ->perPage(20)
        );

        return $response->documents;
    }
}

Registered Services

Standalone Usage

Set Up the Client

use Enabel\Typesense\Client;
use Enabel\Typesense\Document\{DocumentNormalizer, ObjectDenormalizer};
use Enabel\Typesense\Metadata\{MetadataReader, MetadataRegistry};
use Enabel\Typesense\Schema\SchemaBuilder;

$typesense = new \Typesense\Client([
    'api_key' => 'your-api-key',
    'nodes' => [['host' => 'localhost', 'port' => '8108', 'protocol' => 'http']],
]);

$registry   = new MetadataRegistry(new MetadataReader());
$normalizer = new DocumentNormalizer($registry);

$client = new Client(
    typesenseClient: $typesense,
    registry: $registry,
    normalizer: $normalizer,
    schemaBuilder: new SchemaBuilder(),
    denormalizers: [
        Product::class => new ObjectDenormalizer($registry),
    ],
);

Create Collection & Index Documents

$client->create(Product::class);

$collection = $client->collection(Product::class);
$collection->upsert($product);
$collection->import([$product1, $product2, $product3]);

With Doctrine ORM

Use DoctrineDenormalizer to return fully hydrated entities from search results, and DoctrineDataProvider for memory-efficient bulk import:

use Enabel\Typesense\Doctrine\{DoctrineDenormalizer, DoctrineDataProvider, IndexListener};

$client = new Client(
    typesenseClient: $typesense,
    registry: $registry,
    normalizer: $normalizer,
    schemaBuilder: new SchemaBuilder(),
    denormalizers: [
        Product::class => new DoctrineDenormalizer($entityManager, $registry),
    ],
);

// Bulk import via data provider
$provider = new DoctrineDataProvider($entityManager);
$collection->import($provider->provide(Product::class));

// Auto-sync on persist/update/remove
$listener = new IndexListener(
    client: $client,
    classNames: [Product::class],
    logger: $logger,      // optional
    registry: $registry,  // optional, used for ID extraction on preRemove
);

$entityManager->getEventManager()->addEventListener(
    [Events::postPersist, Events::postUpdate, Events::preRemove],
    $listener,
);

Mapping Attributes

Import the mapping namespace as Typesense for concise, readable attribute declarations:

use Enabel\Typesense\Mapping as Typesense;

#[Typesense\Document]

Applied to a class. Defines the Typesense collection name.

#[Typesense\Id]

Applied to exactly one property. Marks it as the document ID.

#[Typesense\Field]

Applied to properties or public methods that should be indexed in Typesense.

Computed Fields (Method Mapping)

#[Field] can be placed on a public method to index a computed value. The method's return value is called during normalization and stored in Typesense. By default, computed fields are not written back when denormalizing search results (denormalize: false).

#[Typesense\Document(collection: 'products')]
class Product
{
    #[Typesense\Id]
    public int $id;

    public string $firstName;
    public string $lastName;

    // Computed field — method is called during indexing
    #[Typesense\Field]
    public function fullName(): string
    {
        return "{$this->firstName} {$this->lastName}";
    }
}

The field name defaults to the method name. Use name: to override it. To write the computed value back on denormalization, set denormalize: true.

Type System

Types are inferred from PHP property types when possible. Use explicit types for arrays or custom conversions.

Available Types

use Enabel\Typesense\Type\{StringType, IntType, FloatType, BoolType, DateTimeType, BackedEnumType};

new StringType()                               // string
new StringType(array: true)                    // string[]
new IntType()                                  // int64
new IntType(int32: true)                       // int32
new IntType(array: true)                       // int64[]
new FloatType()                                // float
new BoolType()                                 // bool
new DateTimeType()                             // int64 (Unix timestamp)
new BackedEnumType(Status::class)              // string or int32
new BackedEnumType(Status::class, array: true) // string[] or int32[]

Casting Helpers

When building filters with datetime or enum values, use the static cast methods:

use Enabel\Typesense\Type\{DateTimeType, BackedEnumType};

Filter::greaterThan('createdAt', DateTimeType::cast(new \DateTimeImmutable('-7 days')));
Filter::equals('status', BackedEnumType::cast(Status::Active));

Search API

Query Builder

use Enabel\Typesense\Search\{Query, Sort};

$query = Query::create('search term')      // null or '*' for wildcard
    ->queryBy('title', 'description')      // Fields to search in
    ->filterBy($filter)                    // Filter or string expression
    ->sortBy('price', Sort::Asc)           // Primary sort (resets previous sorts)
    ->thenSortBy('rating', Sort::Desc)     // Additional sort
    ->facetBy('category', 'brand')         // Facet fields
    ->maxFacetValues(20)                   // Max facet values returned
    ->page(1)                              // Page number
    ->perPage(25);                         // Results per page

Filter Builder

use Enabel\Typesense\Search\Filter;

// Comparison
Filter::equals('status', 'active');
Filter::notEquals('status', 'draft');
Filter::greaterThan('price', 100);
Filter::greaterThanOrEqual('price', 100);
Filter::lessThan('price', 500);
Filter::lessThanOrEqual('price', 500);
Filter::between('price', 100, 500);

// String matching
Filter::matches('title', 'wire*');

// Set operations
Filter::in('category', ['electronics', 'computers']);
Filter::notIn('status', ['archived', 'deleted']);

// Logical operators
Filter::all($filter1, $filter2);  // AND
Filter::any($filter1, $filter2);  // OR

Response Objects

Response (standard search)

Hit

GroupedResponse (grouped search)

$response = $collection->searchGrouped(
    Query::create('laptop')->queryBy('title'),
    groupBy: 'category',   // Field must have facet: true
    groupLimit: 5,
);

foreach ($response->groupedHits as $group) {
    echo "Group: " . implode(', ', $group->groupKey) . "\n";
    foreach ($group->hits as $hit) {
        echo "  - {$hit->document->title}\n";
    }
}

Raw Search

Bypass the query builder and response DTOs entirely:

$raw = $collection->searchRaw([
    'q' => '*',
    'query_by' => 'title',
    'per_page' => 10,
]);

Collection Operations

$collection = $client->collection(Product::class);

// CRUD
$collection->upsert($product);
$collection->find('42');         // Returns Product or null
$collection->delete('42');

// Bulk import (throws ImportException on partial failure)
$collection->import([$p1, $p2, $p3]);

// Collection lifecycle
$client->create(Product::class);  // Idempotent
$client->drop(Product::class);

License

MIT