### Initialize client and perform basic operations

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/README.md

This example shows how to create a SearchClient, save an object, wait for indexing, and perform a search with typo tolerance.

```php
use Algolia\AlgoliaSearch\Api\SearchClient;

$client = SearchClient::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');

// Add a new record to your Algolia index
$response = $client->saveObject(
    '<YOUR_INDEX_NAME>',
    ['objectID' => 'id',
        'test' => 'val',
    ],
);

// play with the response
var_dump($response);

// Poll the task status to know when it has been indexed
$client->waitForTask('<YOUR_INDEX_NAME>', $response['taskID']);

// Fetch search results, with typo tolerance
$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'hitsPerPage' => 50,
        ],
    ],
    ],
);

// play with the response
var_dump($response);
```

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

### Configuration Class Example

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Shows the base Configuration class with typed properties and a region-aware SearchConfig subclass that inherits region handling.

```php
// lib/Configuration/
class Configuration {
    private string $appId;
    private string $apiKey;
    private array $hosts;
    private int $readTimeout;
    private int $writeTimeout;
}

// Region-aware configuration
class SearchConfig extends ConfigWithRegion {
    // Inherits region handling
}
```

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

### Install Algolia PHP API Client with Composer

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/README.md

Use this command to install the Algolia PHP API Client version ^4.0 via Composer.

```bash
composer require algolia/algoliasearch-client-php "^4.0"
```

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

### Check Generated File Patterns in generation.config.mjs

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Inspect config/generation.config.mjs to identify generated patterns (without '!') that should not be edited. The comment shows examples of generated paths.

```javascript
// In generation.config.mjs - patterns WITHOUT '!' are GENERATED (do not edit)
'clients/algoliasearch-client-php/lib/Api/*',         // Generated
'clients/algoliasearch-client-php/lib/Model/**',      // Generated
// Most of lib/ is hand-written by default
```

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

### Build and Test Commands

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Commands for building the PHP client, generating/running CTS tests, playground, formatting, and running tests from the client directory.

```bash
# From repo root (api-clients-automation)
yarn cli build clients php                     # Build PHP client
yarn cli cts generate php                      # Generate CTS tests
yarn cli cts run php                           # Run CTS tests
yarn cli playground php search                 # Interactive playground
yarn cli format php clients/algoliasearch-client-php

# From client directory
cd clients/algoliasearch-client-php
composer install                               # Install dependencies
composer test                                  # Run tests
composer cs-fix                                # Fix code style
```

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

### Composer Autoload and Namespace Usage

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Shows how to set up Composer autoloading with proper namespace and use statements for the SearchClient.

```php
// Composer autoload - ensure proper namespace
namespace Algolia\AlgoliaSearch;

// Use statements at top
use Algolia\AlgoliaSearch\Api\SearchClient;
```

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

### HTTP Client Wrapper

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Shows the HttpClient class in lib/Http that wraps Guzzle and handles request/response serialization.

```php
// lib/Http/
class HttpClient {
    // Wraps Guzzle
    // Handles request/response serialization
}
```

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

### Retry Strategy Classes

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Illustrates the ApiWrapper class handling retry logic with host failover and the Host class defining host state constants.

```php
// lib/RetryStrategy/
class ApiWrapper {
    // Handles retry logic with host failover
    // Tracks host states (up, down, timed_out)
}

class Host {
    public const UP = 'up';
    public const DOWN = 'down';
    public const TIMED_OUT = 'timed_out';
}
```

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

### Check Git Remote for Correct Repository

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Run this command to verify you are in the correct repository before making changes. The expected remote is api-clients-automation.git; if it shows algoliasearch-client-php.git, stop and do not edit.

```bash
git remote -v
```

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

### Exception Handling with try-catch

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Catches ApiException for API errors (4xx, 5xx) and AlgoliaException for other Algolia errors. Shows how to access error code and message.

```php
use Algolia\AlgoliaSearch\Exceptions\AlgoliaException;
use Algolia\AlgoliaSearch\ApiException;

try {
    $response = $client->search($params);
} catch (ApiException $e) {
    // API error (4xx, 5xx)
    echo $e->getCode();
    echo $e->getMessage();
} catch (AlgoliaException $e) {
    // Other Algolia errors
}
```

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

### Strict Types Declaration and Type Hinting

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Requires declare(strict_types=1) at the top of every file. Type mismatches will throw TypeError.

```php
<?php
declare(strict_types=1); // Required at top of every file

// Type mismatch will throw TypeError
function search(string $query, int $page): array
```

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

### Array vs Object Access

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

API may return arrays or objects; prefer model methods when available, but array access may work for array responses.

```php
// API may return arrays or objects
// Use model methods when available
$response->getHits();  // Preferred
$response['hits'];     // May work for array responses
```

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

### Null Coalescing and Null Safe Operators

Source: https://github.com/algolia/algoliasearch-client-php/blob/main/AGENTS.md

Use null coalescing for defaults, null safe operator (PHP 8.0+) for method chains, and explicit null checks before access.

```php
// Use null coalescing
$value = $options['key'] ?? 'default';

// Use null safe operator (PHP 8.0+)
$hits = $response?->getHits();

// Check before access
if ($response !== null && $response->getHits() !== null) {
    // safe to use
}
```