Skip to content
SeekGist
Language: العربية
Menu

PHP

The SeekGist SDK for PHP.

The PHP SDK is seekgist/seekgist-php. It needs PHP 8.1+ with ext-curl and ext-json, and nothing else. The API methods are generated from the OpenAPI file, with PHPStan array shapes in the doc blocks; the helpers are written by hand. Store modules can use it.

{
  "repositories": [{ "type": "path", "url": "../seekgist/packages/sdk-php" }],
  "require": { "seekgist/seekgist-php": "@dev" }
}

Quick start

$client = new SeekGist\Client(['api_key' => getenv('SEEKGIST_API_KEY')]);
 
$res = $client->find('لابتوب العاب تحت 1300', ['lang' => 'ar', 'per_page' => 12]);
$res->data['ids'];          // product ids in rank order
$res->data['hits'];         // product cards
$res->usage?->searches;     // from X-SeekGist-Usage (also ->limit, ->billed, ->period)
$res->requestId;            // quote it to support

Options: api_key (or the env variable SEEKGIST_API_KEY), base_url (default https://api.seekgist.com, or SEEKGIST_BASE_URL), timeout (seconds per attempt, 10), max_retries (2), headers, transport.

Store search page with a fallback

On a store search page, wait at most 300 ms and never retry. On any SeekGistException, show your own search.

$client = new SeekGist\Client(['api_key' => $publicKey, 'timeout' => 0.3, 'max_retries' => 0]);
try {
    $ids = $client->find($query, ['lang' => 'auto'])->data['ids'];
} catch (SeekGist\Exception\SeekGistException $e) {
    $ids = null; // use the store's own search for this request
}

Sync your catalog

$client->upsertProducts($products, ['batch_size' => 500, 'replace_all' => true, 'key_prefix' => 'nightly-' . date('Ymd')]);

Batches of up to 1,000, one Idempotency-Key per batch, 5 retries. The same key_prefix again is a safe resume.

Every API method

$client->search, events, catalog, imports, connectors, jobs, synonyms, rules, experiments, translation, assistant, analytics, webhooks, account, billing, health, files: one method per endpoint. Parameters go in one array (path, query and header values by name, plus body); options come last.

$client->synonyms->create(['body' => ['kind' => 'equivalent', 'terms' => ['laptop', 'لابتوب']]]);
$client->catalog->productsGet(['product_id' => '42']);
$client->translation->approved(['locale' => 'ar', 'since' => $cursor]); // write-back feed for modules

Helpers

HelperWhat it does
$client->find($q, $fields)POST /v1/search, with usage
$client->suggest($text, ['lang' => 'ar'])For a server-side suggest proxy: 1.5 s timeout, no retries, a small cache. Suggest is never billed
$client->upsertProducts($products, $options)Batched, safe catalog sync
$client->waitForJob($id)Waits for a job to finish
$client->pages(fn ($c) => ...)A generator over every item of a list
SeekGist\Webhook::verify($secret, getallheaders(), file_get_contents('php://input'))Checks a webhook signature and its time (5 minutes)
SeekGist\Usage::parse($header)Reads X-SeekGist-Usage

Errors and retries

  • ApiException (status, errorCode, requestId, fieldErrors(), retryAfterS), TimeoutException, ConnectionException, WebhookVerificationException. All extend SeekGistException.
  • Retries work like the JavaScript SDK: GET calls, search and writes with an Idempotency-Key are retried; clicks, events and chat are not retried after a network error or a 5xx.
  • Empty JSON objects: PHP [] is sent as a JSON list. Use new \stdClass() where the API wants {}.

Examples

In the repository: packages/sdk-php/examples/search.php, store-search.php (300 ms fallback), sync-catalog.php and webhook.php.