Download the PHP package bradsearch/search-sync-sdk without Composer

Brad Search Synchronization PHP SDK

A comprehensive PHP SDK for synchronizing data with the Brad Search API. This SDK provides type-safe field configuration, strict data validation, and robust error handling.

Requirements

• PHP 8.4 or higher
• cURL extension
• JSON extension
• BCMath extension (required for ShopifyAdapter price comparisons)

Installation

Basic Usage

1. Configuration

2. Index Management

3. Product Synchronization

Single Product

Bulk Synchronization

Field Types

The SDK supports the following field types:

• TEXT_KEYWORD: Full-text search with keyword matching
• TEXT: Full-text search only
• KEYWORD: Exact keyword matching
• HIERARCHY: Hierarchical categories
• VARIANTS: Product variants with attributes
• IMAGE_URL: Image URLs object with size keys (e.g., {"small": "url", "medium": "url"})
• URL: Regular URLs with validation

Custom Field Configuration

Data Validation

The SDK provides strict data validation:

Error Handling

The SDK uses typed exceptions for different error scenarios:

TransportException (a subclass of ApiException) means no HTTP response arrived at all: connection refused, connect or read timeout, DNS or TLS failure. Its statusCode is 0 and responseBody is null.

Timeouts and retries

Every request carries two timeouts from the config: connectTimeout (default 10s) bounds the TCP/TLS handshake, timeout (default 30s) bounds the whole request. Raise timeout for large bulk payloads; keep connectTimeout short so a stalled network fails fast.

Idempotent requests are retried automatically on connection failures (refused, DNS, TLS, connect timeout), HTTP 5xx and 429 with jittered exponential backoff (1s doubling to an 8s cap, 3 attempts by default). Idempotent means GET, PUT, DELETE, PATCH and the bulk-style POSTs (bulk-operations, V1 sync/ and delete-products, normalize). Configuration POSTs (configuration, configuration/refresh, synonyms, index, index/activate, V1 reindex) and the V1 create-index PUT (the server answers 409 on a repeat) are never retried by the SDK. After the last attempt the exception from the final response is thrown, with its status code and body intact.

A read timeout is not retried either: the request reached the engine, which may still be processing it, so re-sending immediately only adds load. TransportException::$connectionFailed tells the two apart, and $curlErrno carries the raw cURL error code. Leave read-timeout retries to a slower layer (a queue job's backoff, for example).

Tune or disable the budget per config:

For tests, pass an implementation of BradSearch\SyncSdk\Client\Transport\Transport as the second constructor argument of SyncV2Sdk or AdminSdk to script responses without touching the network.

Advanced Usage

Field Filtering

The SDK automatically filters product data to only include fields defined in the configuration. This ensures clean data and prevents sending unnecessary fields to the API.

Batch Processing

Large datasets are automatically processed in batches to avoid memory issues and API limits:

Getting Field Configuration

Testing

The SDK includes comprehensive validation and error handling. For testing:

1. Use the validation methods to check data before syncing.
2. Start with small batches to verify configuration
3. Monitor API responses for any issues.

License

MIT License

Support

For support and bug reports, please create an issue in the repository.