// 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
}

// 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';
}

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

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

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

// 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
}

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

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
}

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

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