Typesense Php Laravel Package

Getting Started

Install the package via Composer: composer require typesense/typesense-php. Initialize the client with your Typesense server URL, API key, and optional timeout settings:

$client = new Typesense\Client([
    'api_key' => 'your_api_key',
    'nodes' => [
        ['host' => 'localhost', 'port' => 8108, 'protocol' => 'http'],
    ],
    'connection_timeout_seconds' => 2,
]);

Start by creating a collection (schema) and indexing documents—this is the core day-to-day workflow. Check the official docs for schema structure and indexing examples. The client’s collections, documents, and search methods form the primary interface.

Implementation Patterns

• Singleton Client: Inject the Typesense\Client as a shared service (e.g., via Laravel’s app()->singleton() or custom service provider) to reuse connections across requests.
• Search Workflow: Typically chain calls—$client->collections['products']->documents->search($query, $params)—with query-time params like q, query_by, filter_by, sort_by, and facet_by.
• Bulk Indexing: Use documents->import() with a JSONL payload (array of document strings) for high-performance batch inserts or updates.
• Middleware Integration: Wrap search logic in repository or service classes (e.g., ProductSearchService) to decouple controllers from typesense-specific logic.
• Synonyms & Curations: Leverage collections['collection_name']->synonyms and collections['collection_name']->curations endpoints to manage search relevance, especially with the fix in v6.1.0-RC1 for nested item access. Always validate nested structures (e.g., replace_results, metadata) before importing to avoid silent errors.

Gotchas and Tips

• API Key Exposure: Never hardcode keys in code; use .env + config files with typesense.api_key masked in phpinfo() or logs.
• Document IDs: Typesense enforces string IDs by default; ensure numeric IDs (e.g., 123) are cast to strings ("123") before indexing to avoid silent failures.
• Multi-Node Failover: If using multiple nodes, always provide fallbacks (nodes array) with healthcheck_interval_seconds configured; the client auto-detects downed nodes.
• Facet Counts: facet_by returns arrays—ensure proper type handling (e.g., collect($result['facet_counts'] ?? [])) to avoid undefined array key errors.
• Debugging: Enable log_level via new Client([...], 'log_level' => 'debug') or patch Guzzle middleware to inspect HTTP requests/responses.
• Schema Evolution: Typesense does not auto-migrate schemas; use collections->update() cautiously (only for allowed changes), or create new collections + aliases for full migrations.
• Timeouts & Retries: Set connection_timeout_seconds and read_timeout_seconds explicitly—default HTTP behavior may cause hanging requests during high load. Consider Laravel’s retry + timeout strategies around critical operations.
• Synonyms/Curations Structure: With v6.1.0-RC1’s fix, ensure synonyms and curation documents strictly conform to the expected nested object/array shape in JSON payloads; malformed nested items (e.g., replace_results[0].product_id) previously caused silent failures and are now caught.