PHP

حزمة PHP اسمها seekgist/seekgist-php. تحتاج إلى PHP 8.1 أو أحدث مع ext-curl وext-json، ولا شيء غيرهما. دوال الواجهة البرمجية مولّدة من ملف OpenAPI، مع وصف لأشكال المصفوفات بصيغة PHPStan، أما الدوال المساعدة فمكتوبة يدويًا. ويمكن لإضافات المتاجر استخدامها.

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

بداية سريعة

$client = new SeekGist\Client(['api_key' => getenv('SEEKGIST_API_KEY')]);
 
$res = $client->find('فستان سهرة تحت 100', ['lang' => 'ar', 'per_page' => 12]);
$res->data['ids'];          // أرقام المنتجات بترتيب الصلة
$res->data['hits'];         // بطاقات المنتجات
$res->usage?->searches;     // من X-SeekGist-Usage (وأيضًا ->limit و->billed و->period)
$res->requestId;            // اذكره عند التواصل مع الدعم

الخيارات: api_key (أو متغير البيئة SEEKGIST_API_KEY)، وbase_url (الافتراضي https://api.seekgist.com، أو SEEKGIST_BASE_URL)، وtimeout (بالثواني لكل محاولة، 10)، وmax_retries (2)، وheaders، وtransport.

صفحة بحث في متجر مع رجوع آمن

في صفحة البحث في متجر، انتظر 300 ملّي ثانية على الأكثر ولا تُعد المحاولة. وعند أي SeekGistException اعرض بحث متجرك.

$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; // استخدم بحث المتجر نفسه لهذا الطلب
}

مزامنة الكتالوج

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

دفعات حتى 1,000 منتج، وIdempotency-Key واحد لكل دفعة، و5 محاولات إعادة. وتشغيلها مرة أخرى بقيمة key_prefix نفسها استئناف آمن.

كل دوال الواجهة البرمجية

$client->search وevents وcatalog وimports وconnectors وjobs وsynonyms وrules وexperiments وtranslation وassistant وanalytics وwebhooks وaccount وbilling وhealth وfiles: دالة لكل نقطة نهاية. تُمرَّر المعاملات في مصفوفة واحدة (قيم المسار والاستعلام والترويسات بأسمائها، وbody)، والخيارات في الآخر.

$client->synonyms->create(['body' => ['kind' => 'equivalent', 'terms' => ['laptop', 'لابتوب']]]);
$client->catalog->productsGet(['product_id' => '42']);
$client->translation->approved(['locale' => 'ar', 'since' => $cursor]); // مصدر الترجمات المعتمدة لإضافات المتاجر

الدوال المساعدة

الأخطاء وإعادة المحاولة

• ApiException (status، errorCode، requestId، fieldErrors()، retryAfterS)، وTimeoutException، وConnectionException، وWebhookVerificationException. وكلها مشتقة من SeekGistException.
• تعمل إعادة المحاولة كما في حزمة JavaScript: تُعاد طلبات GET والبحث وعمليات الكتابة التي تحمل Idempotency-Key، ولا تُعاد النقرات والأحداث والمحادثة بعد خطأ شبكة أو خطأ 5xx.
• كائنات JSON الفارغة: تُرسَل [] في PHP على أنها قائمة JSON. استخدم new \stdClass() حيث تنتظر الواجهة {}.

أمثلة

في المستودع: packages/sdk-php/examples/search.php، وstore-search.php (رجوع بعد 300 ملّي ثانية)، وsync-catalog.php، وwebhook.php.