README

The official PHP client for the SeekGist API: Arabic-first e-commerce search, suggest, catalog sync and webhooks. PHP 8.1+ with ext-curl and ext-json, no other dependency. PHPStan array shapes in the doc blocks.

composer require seekgist/seekgist-php

Documentation: https://seekgist.com/docs. Support: support@seekgist.com.

Quick start

require 'vendor/autoload.php';

$client = new SeekGist\Client(['api_key' => getenv('SEEKGIST_API_KEY')]); // secret key, on your server

$products = [['id' => '42', 'name' => ['en' => 'Desk lamp', 'ar' => 'مصباح مكتب'], 'price' => '12.500', 'currency' => 'JOD']];
$sum = $client->upsertProducts($products);   // batches, retries, one Idempotency-Key per batch
echo $sum['upserted'], "\n";                  // also batches, unchanged, deleted, errors

$res = $client->find('مصباح', ['lang' => 'ar', 'per_page' => 12]);
print_r($res->data['ids']);                    // product ids in rank order; $res->data['hits'] has the cards
echo $res->usage?->searches, ' ', $res->requestId, "\n"; // searches used this period; quote the id to support

Options: api_key (or env SEEKGIST_API_KEY), base_url (default https://api.seekgist.com, or SEEKGIST_BASE_URL), timeout (seconds per attempt, 10), max_retries (2), headers, transport (your own SeekGist\Http\Transport).

All API methods

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

Catalog translation works: translation->backfill, status, review*, glossary*, export, approved and ack. Not available on this platform: the chat methods. They answer 404 feature_unavailable.

$client->synonyms->create(['body' => ['kind' => 'equivalent', 'terms' => ['sneakers', 'trainers', 'سنيكرز']]]);
$client->catalog->productsGet(['product_id' => '42']);
$client->search->searchGet(['q' => 'sneakers'], ['query' => ['filter[brand]' => ['Nike', 'Adidas']]]);
$r = $client->request('search_post', ['body' => ['q' => 'dress']]);   // any operation, full Response
$client->translation->approved(['locale' => 'ar', 'since' => $cursor]);   // write-back feed for modules

Options per call: timeout, max_retries, idempotency_key, headers, query. Dashboard sign-in, admin and store-app callback endpoints are not in the SDK on purpose.

Helpers

Helper	What it does
`$client->find($q, $fields)`	POST /v1/search; full `Response` with `usage`
`$client->suggest($text, ['lang' => 'ar'], minChars: 1)`	For a server-side suggest proxy: 1.5 s timeout, no retries, a small cache; null for short text. Suggest is never billed. (Debounce key presses in the browser: JS SDK `@seekgist/sdk` or the widget)
`$client->upsertProducts($products, ['batch_size' => 500, 'replace_all' => true, 'key_prefix' => ...])`	Batches of up to 1,000 with one `Idempotency-Key` per batch and 5 retries; same `key_prefix` again = safe resume
`$client->waitForJob($id)`	Polls `GET /v1/jobs/{id}` until done
`$client->pages(fn ($c) => $client->synonyms->list(['cursor' => $c]))`	Generator over every item
`SeekGist\Webhook::verify($secret, getallheaders(), file_get_contents('php://input'))`	Standard Webhooks signature + 5-minute time check; returns the event
`SeekGist\Usage::parse($header)`	Reads `X-SeekGist-Usage`

Errors, retries and idempotency

SeekGist\Exception\ApiException (status, errorCode, requestId, fieldErrors(), retryAfterS); TimeoutException (extends ConnectionException); WebhookVerificationException. All extend SeekGistException.
Retries (default 2, backoff 0.5 s, 1 s, 2 s ... with jitter; Retry-After wins): GET calls, search, and writes that take an Idempotency-Key (added by the SDK, kept across retries). Click and event are never retried after a network error or 5xx; a 429 is always retried.
Empty JSON objects: PHP [] is sent as a JSON list. Use new \stdClass() where the API wants {}.
Store search pages: new Client(['timeout' => 0.3, 'max_retries' => 0]) and fall back on any SeekGistException (see examples/store-search.php).

Examples

examples/search.php, examples/store-search.php (300 ms fallback), examples/sync-catalog.php, examples/webhook.php (php -S 127.0.0.1:3001 examples/webhook.php). In a clone of the repository they run without Composer.

Development

From a clone of https://github.com/seekgist/seekgist-php (no PHPUnit needed):

composer test    # unit + recorded-answer tests (php tests/run.php)
composer lint    # php -l and the 500-line rule (php tests/lint.php)

Bugs and questions: https://github.com/seekgist/seekgist-php/issues or support@seekgist.com.

License

MIT. See LICENSE.

seekgist / seekgist-php

Package info

Security

Statistics