Typesense PHP Client

https://github.com/typesense/typesense-php
Admin
An official PHP client library for interacting with the Typesense API, providing methods for...
Tokens:48,760
Snippets:489
Trust Score:9.9
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run a Specific PHP Example

Source: https://github.com/typesense/typesense-php/blob/master/examples/README.md

After starting the Typesense server, navigate to the examples directory and execute a specific PHP example script using this command.

```shell
cd examples
php <example_name>.php
```

--------------------------------

### Quick Start: Initialize Client, Create Collection, Add Document, and Search

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/README.md

This snippet demonstrates the basic usage of the Typesense PHP client, including client initialization, collection creation, document insertion, and performing a search query. Ensure you have the necessary dependencies installed and Typesense server running.

```php
use Typesense\Client;

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

// Create a collection
$client->collections->create([
    'name' => 'books',
    'fields' => [
        ['name' => 'id', 'type' => 'string'],
        ['name' => 'title', 'type' => 'string'],
        ['name' => 'author', 'type' => 'string'],
        ['name' => 'rating', 'type' => 'float'],
    ],
]);

// Create a document
$client->collections['books']->documents->create([
    'id' => '1',
    'title' => 'The Great Gatsby',
    'author' => 'F. Scott Fitzgerald',
    'rating' => 3.9,
]);

// Search
$results = $client->collections['books']->documents->search([
    'q' => 'gatsby',
    'query_by' => 'title,author',
]);
```

--------------------------------

### Start Typesense Server

Source: https://github.com/typesense/typesense-php/blob/master/README.md

Start a Typesense server instance using the provided Composer script.

```shell
composer run-script typesenseServer
```

--------------------------------

### Usage Example: Daily Backup and Schema Monitoring

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/operations.md

This example demonstrates how to create a daily backup using the perform method and how to monitor ongoing schema changes. It includes basic error handling for the backup operation.

```php
// Create a daily backup
try {
    $timestamp = date('Y-m-d_H-i-s');
    $backupPath = "/backups/typesense_$timestamp";
    
    $result = $client->operations->perform('snapshot', [
        'snapshot_path' => $backupPath,
    ]);
    
    echo "Backup created at: $backupPath";
} catch (Exception $e) {
    echo "Backup failed: " . $e->getMessage();
}

// Monitor schema changes
$changes = $client->operations->getSchemaChangeStatus();
if (!empty($changes['schema_changes'])) {
    foreach ($changes['schema_changes'] as $change) {
        echo "Field: " . $change['name'];
        echo " - Status: " . $change['status'];
    }
}
```

--------------------------------

### Install Typesense PHP Client

Source: https://github.com/typesense/typesense-php/blob/master/README.md

Install the Typesense PHP client and the curl HTTP client adapter using Composer.

```shell
composer require php-http/curl-client typesense/typesense-php
```

--------------------------------

### Install cURL HTTP Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Installs the recommended cURL-based HTTP client for the Typesense PHP library using Composer.

```bash
# Using cURL client (recommended)
composer require php-http/curl-client
```

--------------------------------

### Full Synonym Management Example

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/synonyms.md

Demonstrates the complete lifecycle of creating and using synonym groups, including setting a root term for expansion. This example shows how to configure synonyms and then utilize them in a search query.

```php
// Create synonym groups for product variations
$client->collections['products']->synonyms->upsert('car', [
    'synonyms' => ['car', 'vehicle', 'automobile', 'auto'],
]);

$client->collections['products']->synonyms->upsert('phone', [
    'synonyms' => ['phone', 'smartphone', 'mobile', 'device'],
]);

$client->collections['products']->synonyms->upsert('tv', [
    'synonyms' => ['tv', 'television', 'screen', 'display'],
]);

// With root for expansion
$client->collections['products']->synonyms->upsert('clothing_sizes', [
    'root' => 'medium',
    'synonyms' => ['M', 'medium', 'med', 'size 10'],
]);

// Now searching for "phone" will also match "smartphone", "mobile", "device"
$results = $client->collections['products']->documents->search([
    'q' => 'phone',
    'query_by' => 'product_name',
]);
```

--------------------------------

### Install Symfony HTTP Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Installs the Symfony HTTP client adapter for the Typesense PHP library using Composer.

```bash
# Using Symfony HTTP client
composer require symfony/http-client
```

--------------------------------

### Comprehensive Usage Example for Typesense PHP Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/health-debug-metrics.md

This example demonstrates how to perform a health check, retrieve debug information, and get server metrics using the Typesense PHP client. It includes basic error handling for the health check.

```php
// Health check
try {
    $health = $client->health->retrieve();
    echo "Server is healthy: " . ($health['ok'] ? 'yes' : 'no');
} catch (Exception $e) {
    echo "Server is down";
}

// Debug info for troubleshooting
$debug = $client->debug->retrieve();
echo "Server version: " . $debug['version'];

// Get metrics for monitoring
$metrics = $client->metrics->retrieve();
// Send to monitoring system (Prometheus, DataDog, etc.)
```

--------------------------------

### Install Guzzle HTTP Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Installs the Guzzle 7 HTTP client adapter for the Typesense PHP library using Composer.

```bash
# Using Guzzle
composer require php-http/guzzle7-adapter
```

--------------------------------

### Document Operations Example

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/document.md

This example demonstrates the common operations of retrieving, updating, and deleting a document using the Typesense PHP client.

```php
// Retrieve
$doc = $client->collections['products']->documents['123']->retrieve();

// Update
$doc = $client->collections['products']->documents['123']->update([
    'title' => 'Updated Title',
    'price' => 199.99,
]);

// Delete
$client->collections['products']->documents['123']->delete();
```

--------------------------------

### Full Usage Example: Create and Scope Keys

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/keys.md

Demonstrates creating a frontend search key and then generating a user-specific scoped key from it for secure frontend usage.

```php
// Create an API key with restricted access
$keyResp = $client->keys->create([
    'description' => 'Frontend search key',
    'actions' => ['search'],
    'collections' => ['products'],
    'expires_at' => time() + (30 * 24 * 60 * 60), // 30 days
]);

$searchKey = $keyResp['value'];

// Generate user-specific scoped key
$userId = 12345;
$userKey = $client->keys->generateScopedSearchKey(
    $searchKey,
    [
        'filter_by' => "user_id:$userId",
        'expires_at' => time() + 3600,
    ]
);

// Send userKey to frontend for secure searching
echo $userKey;
```

--------------------------------

### Retrieve All Presets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Call this method to get a list of all defined preset configurations.

```php
$presets = $client->presets->retrieve();
```

--------------------------------

### Full Usage Example: Managing and Using Presets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Illustrates the complete workflow of creating, using, and updating search presets for different scenarios like popular products and new arrivals.

```php
// Create a preset for popular products
$client->presets->upsert('popular', [
    'value' => [
        'collection' => 'products',
        'query_by' => 'title,description',
        'sort_by' => 'popularity:desc',
        'facet_by' => 'category,brand',
        'limit' => 20,
        'highlight_fields' => 'title',
    ],
]);

// Create a preset for new products
$client->presets->upsert('new_arrivals', [
    'value' => [
        'collection' => 'products',
        'query_by' => 'title',
        'filter_by' => 'added_date:>=' . strtotime('-7 days'),
        'sort_by' => 'added_date:desc',
        'limit' => 15,
    ],
]);

// Use presets in searches
$popularResults = $client->presets->searchWithPreset('popular');
$newResults = $client->presets->searchWithPreset('new_arrivals');

// Update a preset
$client->presets->upsert('popular', [
    'value' => [
        'collection' => 'products',
        'query_by' => 'title,description,tags',
        'sort_by' => 'popularity:desc',
        'limit' => 25,
    ],
]);
```

--------------------------------

### Get Presets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a list of all search presets.

```APIDOC
## Get Presets

### Description
Retrieves a list of all search presets.

### Method
GET

### Endpoint
/presets

### Response
#### Success Response (200 OK)
- Array of presets

### PHP
```php
$client->presets->retrieve()
```
```

--------------------------------

### Alias Management and Usage Example

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/aliases.md

Demonstrates the lifecycle of an alias, from creation and switching to a new collection, to searching using the alias. This highlights how aliases decouple client code from collection changes.

```php
// Create or switch an alias to a new collection
$client->aliases->upsert('products_active', [
    'collection_name' => 'products_v2',
]);

// Search using the alias
$results = $client->collections['products_active']->documents->search([
    'q' => 'laptop',
    'query_by' => 'title',
]);

// Switch to a different collection without changing client code
$client->aliases->upsert('products_active', [
    'collection_name' => 'products_v3',
]);

// All searches now hit products_v3
```

--------------------------------

### Get All Synonyms

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a list of all synonyms configured for a collection. Use this to view all synonym mappings.

```php
$client->collections['{name}']->synonyms->retrieve()
```

--------------------------------

### Get Preset

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific search preset by its name.

```APIDOC
## Get Preset

### Description
Retrieves a specific search preset by its name.

### Method
GET

### Endpoint
/presets/{preset_name}

### Response
#### Success Response (200 OK)
- Preset

### Error Handling
- 404 Not Found

### PHP
```php
$client->presets['{name}']->retrieve()
```
```

--------------------------------

### Full Conversation Lifecycle Example

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/conversations.md

Illustrates the complete workflow of using the Conversations API, from creating an LLM model and a conversation to updating, retrieving, and finally deleting it.

```php
// Create a conversation model
$client->conversations->getModels()->create([
    'model_name' => 'openai',
    'model_id' => 'gpt-4',
]);

// Create a conversation
$conv = $client->conversations['user_123_session_1']->update([
    'messages' => [
        [
            'role' => 'user',
            'content' => 'Show me red shoes under $100',
        ],
    ],
]);

// Continue conversation
$updated = $client->conversations['user_123_session_1']->update([
    'messages' => [
        [
            'role' => 'user',
            'content' => 'What about Nike brand?',
        ],
    ],
]);

// Retrieve full conversation
$fullConv = $client->conversations['user_123_session_1']->retrieve();

// Delete conversation
$client->conversations['user_123_session_1']->delete();
```

--------------------------------

### Get Synonyms

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a list of all synonyms for a given collection.

```APIDOC
## Get Synonyms

### Description
Retrieves a list of all synonyms for a given collection.

### Method
GET

### Endpoint
/collections/{collection_name}/synonyms

### Response
#### Success Response (200 OK)
- Array of synonyms

### PHP
```php
$client->collections['{name}']->synonyms->retrieve()
```
```

--------------------------------

### Get Aliases

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a list of all aliases.

```APIDOC
## Get Aliases

### Description
Retrieves a list of all aliases.

### Method
GET

### Endpoint
/aliases

### Response
#### Success Response (200 OK)
- Array of aliases

### PHP
```php
$client->aliases->retrieve()
```
```

--------------------------------

### Usage Examples for Search Result Overrides

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/overrides.md

Demonstrates various use cases for the upsert method, including promoting premium items, excluding discontinued products, and featuring branded products with token removal.

```php
// Promote premium items in search results
$client->collections['products']->overrides->upsert('premium_first', [
    'rule' => [
        'query' => '',
        'match' => 'contains',
    ],
    'includes' => [
        ['id' => 'premium_1', 'position' => 1],
        ['id' => 'premium_2', 'position' => 2],
    ],
]);

// Exclude discontinued products from specific searches
$client->collections['products']->overrides->upsert('no_discontinued', [
    'rule' => [
        'query' => 'old edition',
        'match' => 'contains',
    ],
    'excludes' => ['discontinued_001', 'discontinued_002'],
]);

// Feature search results for branded products
$client->collections['products']->overrides->upsert('featured_brand', [
    'rule' => [
        'query' => 'brand:xyz',
        'match' => 'exact',
    ],
    'includes' => [
        ['id' => 'xyz_premium', 'position' => 1],
    ],
    'remove_matched_tokens' => true,
]);
```

--------------------------------

### Full Stopwords Management Example

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/stopwords.md

Demonstrates the complete workflow of creating custom stopwords for English and French, listing all sets, retrieving a specific set, and deleting a set.

```php
// Create custom stopwords for English
$client->stopwords->put([
    'name' => 'en_custom',
    'stopwords' => [
        'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by',
        'for', 'from', 'has', 'he', 'in', 'is', 'it',
        'its', 'of', 'on', 'or', 'that', 'the', 'to', 'was', 'will',
    ],
]);

// Create stopwords for French
$client->stopwords->put([
    'name' => 'fr_custom',
    'stopwords' => [
        'un', 'une', 'de', 'la', 'le', 'et', 'ou', 'est',
    ],
]);

// List all stopword sets
$all = $client->stopwords->getAll();

// Get specific set
$frStopwords = $client->stopwords->get('fr_custom');

// Delete a set
$client->stopwords->delete('en_custom');
```

--------------------------------

### Get SynonymSets Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Obtain the SynonymSets manager for managing synonym sets.

```php
$synonymSets = $client->getSynonymSets();
```

--------------------------------

### Sort By Expression Examples

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/types.md

Demonstrates various sort by expressions used in Typesense searches, including ascending/descending order, multiple fields, and sorting by geo distance or text match score.

```php
// Ascending order (default)
'sort_by' => 'price:asc'

// Descending order
'sort_by' => 'popularity:desc'

// Multiple fields
'sort_by' => 'category:asc,price:desc'

// Numeric id field
'sort_by' => '_id:asc'

// Text relevance (search score)
'sort_by' => '_text_match:desc'

// Geo distance
'sort_by' => 'location(12.5, 40.7):asc'
```

--------------------------------

### Get All Stopwords Sets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/stopwords.md

Retrieve all available stopwords sets. This provides an overview of all configured stopwords.

```php
$allStopwords = $client->stopwords->getAll();
```

--------------------------------

### Get Specific Preset Definition

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Retrieves the definition of a single, specific preset by its name.

```php
$preset = $client->presets['popular_products']->retrieve();
```

--------------------------------

### Get Presets Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the Presets manager for managing search presets.

```php
$presets = $client->getPresets();
```

--------------------------------

### Retrieve Metrics

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Gets server metrics in JSON format. Useful for monitoring server performance. The client must be initialized.

```php
$client->metrics->retrieve()
```

--------------------------------

### Get a Specific Synonym

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a single synonym configuration by its ID. This is useful for verifying or inspecting a specific synonym.

```php
$client->collections['{name}']->synonyms['{id}']->retrieve()
```

--------------------------------

### Get Keys Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the Keys manager for managing API keys.

```php
$keys = $client->getKeys();
```

--------------------------------

### Handling ConfigError

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/errors.md

This exception is thrown when the Typesense client configuration is invalid, such as missing required keys or improperly defined nodes. It helps diagnose setup issues.

```php
use Typesense\Exceptions\ConfigError;
use Typesense\Client;

try {
    $client = new Client([
        'api_key' => 'xyz',
        // Missing 'nodes'
    ]);
} catch (ConfigError $e) {
    echo "Invalid configuration: " . $e->getMessage();
}
```

--------------------------------

### Get a Specific Preset

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a single preset configuration by its name. Useful for inspecting the parameters of a saved preset.

```php
$client->presets['{name}']->retrieve()
```

--------------------------------

### Client Configuration with Path Prefix

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Sets up the Typesense client when the Typesense instance is hosted behind a URL path prefix.

```php
$client = new Client([
    'api_key' => 'xyz',
    'nodes' => [
        [
            'host' => 'api.example.com',
            'port' => '443',
            'protocol' => 'https',
            'path' => '/typesense',
        ],
    ],
]);
```

--------------------------------

### Run Tests

Source: https://github.com/typesense/typesense-php/blob/master/README.md

Set up the testing environment using Docker Compose, configure PHPUnit, and run the tests.

```shell
docker compose up
cp phpunit.xml.dist phpunit.xml
composer run-script test
```

--------------------------------

### Get Typesense Server Metrics

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/health-debug-metrics.md

Use the `Metrics` class's `retrieve()` method to obtain server metrics in Prometheus format, such as CPU, memory, and network usage, for monitoring purposes.

```php
$metrics = $client->metrics->retrieve();
// Returns metrics data for monitoring
```

--------------------------------

### Retry on Service Unavailable or HTTP Status 0 Errors

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/errors.md

Implement a retry mechanism for transient network errors like `ServiceUnavailable` or `HTTPStatus0Error`. This example retries up to 3 times with a 1-second delay between attempts.

```php
use Typesense\Exceptions\ServiceUnavailable;
use Typesense\Exceptions\HTTPStatus0Error;

$maxAttempts = 3;
$attempt = 0;

while ($attempt < $maxAttempts) {
    try {
        $results = $client->collections['products']->documents->search([
            'q' => 'laptop',
            'query_by' => 'title',
        ]);
        break;
    } catch (ServiceUnavailable | HTTPStatus0Error $e) {
        $attempt++;
        if ($attempt >= $maxAttempts) {
            throw $e;
        }
        sleep(1);
    }
}
```

--------------------------------

### Get All Stopwords Sets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/stopwords.md

Retrieves all available stopwords sets. This is useful for getting an overview of all configured stopwords across different languages or custom sets.

```APIDOC
## GET /stopwords

### Description
Retrieve all stopwords sets.

### Method
GET

### Endpoint
/stopwords

### Response
#### Success Response (200)
- Returns an array containing definitions of all stopwords sets.

### Response Example
```json
{
  "en": {
    "stopwords": [
      "a",
      "an",
      "and"
    ]
  },
  "fr": {
    "stopwords": [
      "un",
      "une",
      "de"
    ]
  }
}
```
```

--------------------------------

### Get Specific Synonym Definition

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/synonyms.md

Use the retrieve method on an individual synonym object (accessed via ArrayAccess) to get its specific definition. This is useful when you need details about a single synonym group.

```php
public function retrieve(): array
```

```php
$synonym = $client->collections['products']->synonyms['mobile_devices']->retrieve();
```

--------------------------------

### Initialize Typesense Client and Perform Operations

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

This snippet shows how to instantiate the Typesense client with API key and node configuration. It then demonstrates creating a collection, adding a document, searching for documents, and retrieving cluster health.

```php
use Typesense\Client;

$client = new Client([
    'api_key' => 'xyz',
    'nodes' => [
        [
            'host' => 'localhost',
            'port' => '8108',
            'protocol' => 'http',
        ],
    ],
]);

// Create a collection
$collection = $client->collections->create([
    'name' => 'books',
    'fields' => [
        ['name' => 'title', 'type' => 'string'],
        ['name' => 'author', 'type' => 'string'],
    ],
    'default_sorting_field' => 'title',
]);

// Create a document
$doc = $client->collections['books']->documents->create([
    'id' => '1',
    'title' => 'The Great Gatsby',
    'author' => 'F. Scott Fitzgerald',
]);

// Search documents
$results = $client->collections['books']->documents->search([
    'q' => 'gatsby',
    'query_by' => 'title',
]);

// Check cluster health
$health = $client->health->retrieve();

```

--------------------------------

### Client Initialization

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Initializes a new Client instance with the provided configuration. The configuration array must include nodes and an API key, and can optionally include various connection and retry settings.

```APIDOC
## Client Initialization

### Description
Initializes a new Client instance with the provided configuration. The configuration array must include nodes and an API key, and can optionally include various connection and retry settings.

### Method
`__construct(array $config)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (array) - Required - Configuration array containing nodes, api_key, and optional connection settings.
  - `nodes`: array of node definitions (each with `host`, `port`, `protocol`)
  - `api_key`: string API key for authentication
  - `nearest_node`: node configuration for preferred connection target (Optional)
  - `num_retries`: number of retries on failure (Optional, default: 3)
  - `retry_interval_seconds`: wait time between retries in seconds (Optional, default: 1.0)
  - `healthcheck_interval_seconds`: health check frequency in seconds (Optional, default: 60)
  - `randomize_nodes`: shuffle node list on initialization (Optional, default: true)
  - `logger`: custom PSR-3 LoggerInterface instance (Optional)
  - `log_level`: log level constant (Optional, only if no custom logger provided)
  - `client`: custom HTTP client (PSR-18 ClientInterface or Http\Client\HttpClient) (Optional)

### Request Example
```php
$client = new \Typesense\Client([
    'nodes' => [
        ['host' => 'localhost', 'port' => '8108', 'protocol' => 'http']
    ],
    'api_key' => 'YOUR_API_KEY'
]);
```

### Response
#### Success Response
Returns an instance of the `Client` class.

#### Response Example
```php
// Instance of \Typesense\Client
$client
```

### Throws
- `Typesense\Exceptions\ConfigError`: If the configuration is invalid.
```

--------------------------------

### Basic Client Configuration

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Instantiates the Typesense client with minimal required configuration: API key and a single node definition.

```php
use Typesense\Client;

$client = new Client([
    'api_key' => 'xyz',
    'nodes' => [
        [
            'host' => 'localhost',
            'port' => '8108',
            'protocol' => 'http',
        ],
    ],
]);
```

--------------------------------

### Initialize Client with Environment Variables

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Configure the Typesense client using environment variables for API key, host, port, and protocol. Defaults are provided for host, port, and protocol if environment variables are not set.

```php
$client = new Client([
    'api_key' => getenv('TYPESENSE_API_KEY'),
    'nodes' => [
        [
            'host' => getenv('TYPESENSE_HOST') ?: 'localhost',
            'port' => getenv('TYPESENSE_PORT') ?: '8108',
            'protocol' => getenv('TYPESENSE_PROTOCOL') ?: 'http',
        ],
    ],
]);
```

--------------------------------

### Get Alias

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific alias by its name.

```APIDOC
## Get Alias

### Description
Retrieves a specific alias by its name.

### Method
GET

### Endpoint
/aliases/{alias_name}

### Response
#### Success Response (200 OK)
- Alias

### Error Handling
- 404 Not Found

### PHP
```php
$client->aliases['{name}']->retrieve()
```
```

--------------------------------

### Initialize Typesense Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Instantiate the Typesense Client with a configuration array. The configuration must include nodes and an API key. Optional settings like retries, intervals, and custom loggers can also be provided.

```php
use Typesense\Client;

$client = new Client([
    'nodes' => [
        ['host' => 'localhost', 'port' => 8108, 'protocol' => 'http'],
    ],
    'api_key' => 'YOUR_API_KEY',
    'num_retries' => 3,
    'retry_interval_seconds' => 1.0,
    'healthcheck_interval_seconds' => 60,
    'randomize_nodes' => true,
]);
```

--------------------------------

### Get Keys

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a list of all API keys (without their values).

```APIDOC
## Get Keys

### Description
Retrieves a list of all API keys (without their values).

### Method
GET

### Endpoint
/keys

### Response
#### Success Response (200 OK)
- Array of keys (without values)

### PHP
```php
$client->keys->retrieve()
```
```

--------------------------------

### Get Synonym

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific synonym by its ID for a given collection.

```APIDOC
## Get Synonym

### Description
Retrieves a specific synonym by its ID for a given collection.

### Method
GET

### Endpoint
/collections/{collection_name}/synonyms/{synonym_id}

### Response
#### Success Response (200 OK)
- Synonym

### Error Handling
- 404 Not Found

### PHP
```php
$client->collections['{name}']->synonyms['{id}']->retrieve()
```
```

--------------------------------

### Get Override

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific override by its ID for a given collection.

```APIDOC
## Get Override

### Description
Retrieves a specific override by its ID for a given collection.

### Method
GET

### Endpoint
/collections/{collection_name}/overrides/{override_id}

### Response
#### Success Response (200 OK)
- Override

### Error Handling
- 404 Not Found

### PHP
```php
$client->collections['{name}']->overrides['{id}']->retrieve()
```
```

--------------------------------

### Access Individual Presets via ArrayAccess

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Demonstrates how to access, retrieve, or delete individual presets using array-like syntax.

```php
// Access a preset
$preset = $client->presets['popular_products'];

// Retrieve preset definition
$presetInfo = $client->presets['popular_products']->retrieve();

// Delete a preset
$client->presets['popular_products']->delete();
```

--------------------------------

### Get Conversations Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the Conversations manager for RAG conversations.

```php
$conversations = $client->getConversations();
```

--------------------------------

### Get Key

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific API key by its ID (without its value).

```APIDOC
## Get Key

### Description
Retrieves a specific API key by its ID (without its value).

### Method
GET

### Endpoint
/keys/{key_id}

### Response
#### Success Response (200 OK)
- Key (without value)

### Error Handling
- 404 Not Found

### PHP
```php
$client->keys['{id}']->retrieve()
```
```

--------------------------------

### Get CurationSets Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the CurationSets manager for managing curation sets.

```php
$curationSets = $client->getCurationSets();
```

--------------------------------

### Get Stemming Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Obtain the Stemming manager for managing stemming dictionaries.

```php
$stemming = $client->getStemming();
```

--------------------------------

### Multi-Search with Different Parameters

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/multisearch.md

Shows how to execute multi-search queries with distinct parameters for each search, while applying common parameters like 'query_by' and 'collection' at the top level.

```php
$results = $client->multiSearch->perform([
    'searches' => [
        [
            'q' => 'phone',
            'filter_by' => 'price:<500',
        ],
        [
            'q' => 'phone',
            'filter_by' => 'price:>=500',
        ],
    ]
], [
    'query_by' => 'product_name',
    'collection' => 'electronics',
]);
```

--------------------------------

### Keys.create() Configuration

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/types.md

Specifies the configuration object for the Keys.create() method, used to generate new API keys with defined permissions.

```APIDOC
## API Key Definition

Configuration for `Keys.create()`.

```php
{
    "description": "string",            // Key description
    "actions": [
        "search",
        "documents:create",
        "documents:upsert",
        "documents:update",
        "documents:delete",
        "collections:create",
        "collections:update",
        "collections:delete",
    ],
    "collections": [
        "products",
        "reviews",
    ],
    "expires_at": 1234567890           // Optional: Unix timestamp
}
```
```

--------------------------------

### Create API Key

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Creates a new API key with specified configurations.

```APIDOC
## Create API Key

### Description
Creates a new API key with specified configurations.

### Method
POST

### Endpoint
/keys

### Request Body
- Key config (description, actions, collections, expires_at)

### Response
#### Success Response (201 Created)
- Key with value

### PHP
```php
$client->keys->create(schema)
```
```

--------------------------------

### Get Aliases Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Obtain the Aliases manager for managing collection aliases.

```php
$aliases = $client->getAliases();
```

--------------------------------

### PHP Imports for Typesense Client

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/README.md

Demonstrates the necessary 'use' statements for importing core classes from the Typesense PHP client library.

```php
use Typesense\Client;
use Typesense\Exceptions\ObjectNotFound;
use Typesense\Lib\Configuration;
```

--------------------------------

### Client Configuration with Custom Logger

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/configuration.md

Initializes the Typesense client with a custom PSR-3 logger implementation (Monolog) and sets the log level to DEBUG.

```php
use Typesense\Client;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('typesense');
$logger->pushHandler(new StreamHandler('php://stderr', Logger::DEBUG));

$client = new Client([
    'api_key' => 'xyz',
    'nodes' => [
        [
            'host' => 'localhost',
            'port' => '8108',
            'protocol' => 'http',
        ],
    ],
    'logger' => $logger,
]);
```

--------------------------------

### Get NLSearchModels Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Access the NLSearchModels manager for natural language search models.

```php
$nlSearchModels = $client->getNLSearchModels();
```

--------------------------------

### Get Operations Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Access the Operations manager for cluster operations such as creating snapshots.

```php
$operations = $client->getOperations();
```

--------------------------------

### Class Overview of Presets

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Provides a structural overview of the Presets class, including its constants and methods.

```php
class Presets implements ArrayAccess
{
    public const PRESETS_PATH = '/presets';
    
    public function __construct(ApiCall $apiCall)
    public function upsert(string $presetName, array $presetsData): array
    public function retrieve(): array
    public function searchWithPreset(string $presetName): array|string
    // ArrayAccess implementation
}
```

--------------------------------

### Get Health Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the Health manager for checking the cluster's status.

```php
$health = $client->getHealth();
```

--------------------------------

### Import Documents with Action Option

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/documents.md

Perform import operations with a specified action, such as 'upsert', to handle existing documents during import.

```php
// Upsert on import
$results = $client->collections['products']->documents->import(
    $documents,
    ['action' => 'upsert']
);
```

--------------------------------

### Get Metrics Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Obtain the Metrics manager to access the server metrics endpoint.

```php
$metrics = $client->getMetrics();
```

--------------------------------

### API Key Definition for Creation

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/types.md

Structure for creating a new API key using `Keys.create()`. It specifies the key's description, allowed actions, and accessible collections.

```php
[
    'description' => 'string',
    'actions' => [
        'search',
        'documents:create',
        'documents:upsert',
        'documents:update',
        'documents:delete',
        'collections:create',
        'collections:update',
        'collections:delete',
    ],
    'collections' => [
        'products',
        'reviews',
    ],
    'expires_at' => 1234567890,           // Optional: Unix timestamp
]
```

--------------------------------

### Preset Class Methods (via ArrayAccess)

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Operations on individual presets accessed via ArrayAccess.

```APIDOC
## retrieve() (via ArrayAccess)

### Description
Get a specific preset definition.

### Method
GET

### Endpoint
/presets/{presetName}

### Parameters
#### Path Parameters
- **presetName** (string) - Required - The name of the preset to retrieve

#### Query Parameters
None

### Response
#### Success Response (200)
- **preset definition** (array) - Description of the preset definition

#### Response Example
```json
{
  "name": "popular_products",
  "value": {
    "collection": "products",
    "query_by": "title,description",
    "sort_by": "popularity:desc",
    "facet_by": "category,brand",
    "limit": 20
  }
}
```
```

```APIDOC
## delete() (via ArrayAccess)

### Description
Delete a preset.

### Method
DELETE

### Endpoint
/presets/{presetName}

### Parameters
#### Path Parameters
- **presetName** (string) - Required - The name of the preset to delete

#### Query Parameters
None

### Response
#### Success Response (200)
- **deletion status** (array) - Description of the deletion status

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get Analytics Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Access the Analytics manager for managing analytics rules and events (v0.28+).

```php
$analytics = $client->getAnalytics();
```

--------------------------------

### Search Using a Preset

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/presets.md

Execute a multi-search request by specifying the name of the preset configuration to use.

```php
$results = $client->presets->searchWithPreset('popular_products');
```

--------------------------------

### Get Debug Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Access the Debug manager to retrieve endpoint information for cluster debugging.

```php
$debug = $client->getDebug();
```

--------------------------------

### Collections Class Overview

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/collections.md

Provides an overview of the Collections class, its constants, constructor, and primary methods like create and retrieve, along with its ArrayAccess implementation.

```php
class Collections implements ArrayAccess
{
    public const RESOURCE_PATH = '/collections';
    public function __construct(ApiCall $apiCall)
    public function create(array $schema, array $options = []): array
    public function retrieve(): array
    // ArrayAccess implementation for accessing individual collections
}
```

--------------------------------

### Get Collections Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Retrieve the Collections manager instance to perform CRUD operations on collections.

```php
$collections = $client->getCollections();
```

--------------------------------

### Run Linter

Source: https://github.com/typesense/typesense-php/blob/master/README.md

Execute the linter to check code style and fix issues.

```shell
composer run-script lint:fix
```

--------------------------------

### Get a Specific Alias

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a single alias configuration by its name. This is useful for verifying alias settings.

```php
$client->aliases['{name}']->retrieve()
```

--------------------------------

### Typesense Keys Class Overview

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/keys.md

Overview of the `Keys` class structure and its methods for API key management.

```php
class Keys implements ArrayAccess
{
    public const RESOURCE_PATH = '/keys';
    
    public function __construct(ApiCall $apiCall)
    public function create(array $schema): array
    public function retrieve(): array
    public function generateScopedSearchKey(string $searchKey, array $parameters): string
    // ArrayAccess implementation
}
```

--------------------------------

### Get Multi-Search Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Obtain the MultiSearch manager to execute multiple search queries in a single request.

```php
$multiSearch = $client->getMultiSearch();
```

--------------------------------

### Client Class

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/README.md

The `Client` class is the main entry point for interacting with the Typesense API. It provides access to all resources and manages configuration.

```APIDOC
## Client

### Description

The `Client` class serves as the primary entry point for all interactions with the Typesense API. It allows access to various resources like collections, documents, and management functionalities, and handles the underlying configuration.

### Class Signature

```php
use Typesense\Client;

$client = new Client(array $config = []);
```

### Parameters

#### Configuration (`$config`)
- **api_key** (string) - Required - Your Typesense API key.
- **nodes** (array) - Required - An array of node configurations. Each node should have:
  - **host** (string) - Required - The hostname of the Typesense node.
  - **port** (int) - Required - The port of the Typesense node.
  - **protocol** (string) - Required - The protocol to use (e.g., 'http' or 'https').
- **other_settings** (array) - Optional - Additional configuration settings like timeouts, retries, etc.
```

--------------------------------

### Import Documents from JSONL String

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/documents.md

Import documents by providing a JSONL-formatted string. Each line in the string represents a single document.

```php
// Import from JSONL string
$jsonl = "{\"id\":\"1\",\"title\":\"Item 1\"}\n{\"id\":\"2\",\"title\":\"Item 2\"}";
$results = $client->collections['products']->documents->import($jsonl);
```

--------------------------------

### Get Documents Manager

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Access the Documents manager for operations related to documents within a specific collection.

```php
$documents = $client->getDocuments();
```

--------------------------------

### Access Individual Collection

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/collections.md

Demonstrates how to access a specific collection using either array syntax (e.g., $client->collections['products']) or property syntax (e.g., $client->collections->products). You can then access its associated managers, like the documents manager.

```php
// Array syntax
$collection = $client->collections['products'];

// Property syntax
$collection = $client->collections->products;

// Get documents manager
$documents = $client->collections['products']->documents;
```

--------------------------------

### Retrieve a Specific Key Definition

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/keys.md

Get the definition details for a single API key using its ID.

```php
public function retrieve(): array
```

```php
$key = $client->keys['0']->retrieve();
```

--------------------------------

### Collection Class Overview

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/collection.md

Provides a structural overview of the Collection class, detailing its properties and methods.

```php
class Collection
{
    private string $name;
    private ApiCall $apiCall;
    public Documents $documents;
    public Overrides $overrides;
    public Synonyms $synonyms;
    
    public function __construct(string $name, ApiCall $apiCall)
    public function exists(): ?bool
    public function retrieve(): array
    public function update(array $schema): array
    public function delete(): array
}
```

--------------------------------

### Perform Cluster Operation

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/operations.md

Use the perform method to initiate cluster operations like creating snapshots, restoring from backups, or restarting the server. Ensure the correct operation name and required parameters are provided.

```php
public function perform(string $operationName, array $queryParameters = []): array
```

```php
// Create a snapshot
$result = $client->operations->perform('snapshot', [
    'snapshot_path' => '/tmp/typesense_backup',
]);

// Restore from snapshot
$result = $client->operations->perform('restore', [
    'snapshot_path' => '/tmp/typesense_backup',
]);

// Restart server
$result = $client->operations->perform('restart');
```

--------------------------------

### Retrieve All Collections in Typesense PHP

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Call this method to get a list of all existing collection schemas in your Typesense instance.

```php
$client->collections->retrieve()
```

--------------------------------

### Documents Class Overview

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/documents.md

Provides a structural overview of the Documents class, outlining its constructor and available methods for document management.

```php
class Documents implements ArrayAccess
{
    public const RESOURCE_PATH = 'documents';
    public function __construct(string $collectionName, ApiCall $apiCall)
    public function create(array $document, array $options = []): array
    public function upsert(array $document, array $options = []): array
    public function update(array $document, array $options = []): array
    public function import($documents, array $options = [])
    public function export(array $queryParams = []): string
    public function delete(array $queryParams = []): array
    public function search(array $searchParams): array
}
```

--------------------------------

### Multi-Search with Different Collections

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/multisearch.md

Demonstrates performing multi-search queries against different collections within the same request. Each search definition specifies its own collection and query parameters.

```php
$results = $client->multiSearch->perform([
    'searches' => [
        [
            'q' => 'laptop',
            'collection' => 'products',
            'query_by' => 'title',
        ],
        [
            'q' => 'laptop',
            'collection' => 'reviews',
            'query_by' => 'content',
        ],
    ]
]);
```

--------------------------------

### Get Specific Override Definition

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/overrides.md

Use the retrieve method on an individual override object to fetch its specific definition.

```php
$override = $client->collections['products']->overrides['promo_featured']->retrieve();
```

--------------------------------

### Retrieve All Collections

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/collections.md

Call this method to get a list of all collections currently in the Typesense cluster, including their schemas and metadata.

```php
$allCollections = $client->collections->retrieve();
```

--------------------------------

### Import Documents from Array

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/documents.md

Import multiple documents by providing an array of document objects. Each object should have an 'id' and field values.

```php
// Import from array
$results = $client->collections['products']->documents->import([
    ['id' => '1', 'title' => 'Item 1'],
    ['id' => '2', 'title' => 'Item 2'],
]);
```

--------------------------------

### Perform an Operation

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Executes a named operation on the Typesense cluster, potentially with specific parameters. Examples include triggering a snapshot.

```php
$client->operations->perform(name, params)
```

--------------------------------

### Create API Key

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/keys.md

Creates a new API key with specified permissions and access. The key definition includes description, allowed actions, accessible collections, and an optional expiration time.

```APIDOC
## POST /keys

### Description
Create a new API key.

### Method
POST

### Endpoint
/keys

### Parameters
#### Request Body
- **schema** (array) - Required - Key definition with description, actions, collections, and optional expires_at.

### Request Example
```json
{
  "description": "Search-only key for mobile app",
  "actions": ["search"],
  "collections": ["products", "reviews"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created key.
- **value** (string) - The generated API key string.

#### Response Example
```json
{
  "id": "0",
  "value": "xxxx..."
}
```
```

--------------------------------

### Get Document

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves a specific document from a collection by its ID. Returns the document if found, otherwise returns a 404 error.

```APIDOC
## GET /collections/{collection_name}/documents/{document_id}

### Description
Retrieves a specific document.

### Method
GET

### Endpoint
/collections/{collection_name}/documents/{document_id}

### Response
#### Success Response (200 OK)
Document

#### Error Response
- 404 Not Found
```

--------------------------------

### Handling ObjectAlreadyExists Error (HTTP 409)

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/errors.md

Use this when creating a resource that already exists. This commonly occurs when trying to create a collection or document with an ID that is already in use.

```php
use Typesense\Exceptions\ObjectAlreadyExists;

try {
    $client->collections->create([
        'name' => 'existing_collection',
        'fields' => [...],
    ]);
} catch (ObjectAlreadyExists $e) {
    echo "Collection already exists";
}
```

--------------------------------

### Retrieve All Overrides for a Collection

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/overrides.md

Call the retrieve method on the Overrides instance to get a list of all defined overrides for the current collection.

```php
$overrides = $client->collections['products']->overrides->retrieve();
```

--------------------------------

### Retrieve Health Status

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Use this to check if the Typesense server is running and responsive. No setup is required beyond having an initialized client.

```php
$client->health->retrieve()
```

--------------------------------

### getPresets()

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/client.md

Returns the Presets manager for managing search presets.

```APIDOC
## getPresets()

### Description
Returns the Presets manager for managing search presets.

### Method
`getPresets(): Presets`

### Parameters
None

### Request Example
```php
$presets = $client->getPresets();
```

### Response
#### Success Response
Returns an instance of the `Presets` manager.

#### Response Example
```php
// Instance of Typesense\Presets
$presets
```
```

--------------------------------

### Create a New API Key

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/keys.md

Use this method to create a new API key. You can define its description, allowed actions, accessible collections, and expiration time.

```php
public function create(array $schema): array
```

```php
$keyResponse = $client->keys->create([
    'description' => 'Search-only key for mobile app',
    'actions' => ['search'],
    'collections' => ['products', 'reviews'],
]);
// Returns: ['id' => '0', 'value' => 'xxxx...', ...]
```

--------------------------------

### Get Collection

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/endpoints.md

Retrieves the schema for a specific collection by its name. Returns the collection schema if found, otherwise returns a 404 error.

```APIDOC
## GET /collections/{collection_name}

### Description
Retrieves a specific collection.

### Method
GET

### Endpoint
/collections/{collection_name}

### Response
#### Success Response (200 OK)
Collection schema

#### Error Response
- 404 Not Found
```

--------------------------------

### Get Specific Stopwords Set

Source: https://github.com/typesense/typesense-php/blob/master/_autodocs/api-reference/stopwords.md

Retrieve a specific stopwords set by its name. This is useful for inspecting the contents of a predefined or custom set.

```php
$stopwords = $client->stopwords->get('en');
```
Tokens:
Raw