PHP

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

التثبيت

composer require seekgist/seekgist-php

الإصدار الحالي: 1.0.0. الترخيص: MIT. الحزمة: packagist.org/packages/seekgist/seekgist-php. الكود المصدري: github.com/seekgist/seekgist-php.

بداية سريعة

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

أرسل session مع كل عملية بحث: رقم عشوائي لزيارة المتسوق، لا اسم ولا بريد إلكتروني. تُعدّ المرادفات المقترحة من عمليات البحث التي تحمله فقط.

الخيارات: 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', 'session' => $shopperSessionId])->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 وanalytics وwebhooks وaccount وbilling وhealth وfiles: دالة لكل نقطة نهاية. تُمرَّر المعاملات في مصفوفة واحدة (قيم المسار والاستعلام والترويسات بأسمائها، وbody)، والخيارات في الآخر. أما دوال المحادثة ($client->assistant) فترد بـ404 feature_unavailable على هذه المنصة.

$client->synonyms->create(['body' => ['kind' => 'equivalent', 'terms' => ['sneakers', 'trainers', 'سنيكرز']]]);
$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() حيث تنتظر الواجهة {}.

أمثلة

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