پکیج PHP

پکیج رسمی nestapi/nestapi یک کلاینت پویا و سبک است: هر فراخوانی متد به مسیر همان سرویس تبدیل می‌شود، پس سرویس‌های جدید بدون به‌روزرسانی پکیج در دسترس هستند.

نصب

composer require nestapi/nestapi

نیازمندی‌ها: PHP 8.1 به بالا و Composer.

شروع سریع

use NestApi\NestApi;

$api = new NestApi();

$ip = $api->ipInfo(ip: '8.8.8.8');

echo $ip->get('location.country'); // United States

نام متد به kebab-case تبدیل می‌شود؛ برای مثال ipInfo به مسیر ip-info می‌رسد.

ارسال پارامترها

پارامترها را به شکل نام‌دار یا به‌صورت یک آرایهٔ انجمنی بفرستید. پارامتر موقعیتی پذیرفته نمی‌شود.

$api->bmi(age: 30, weight: 70, height: 175);

$api->bmi(['age' => 30, 'weight' => 70, 'height' => 175]);

مقدارهای boolean به true و false تبدیل می‌شوند، لیست‌ها به کلیدهای تکراری (a=1&a=2) و مقدارهای null ارسال نمی‌شوند.

فراخوانی با نام دقیق مسیر

برای مسیرهایی که با نام متد PHP قابل نوشتن نیستند، مثل 4jok، یا سرویس‌هایی که نامشان call، request یا version است، از call() استفاده کنید. این متد نام مسیر را بدون تغییر می‌فرستد.

$joke = $api->call('4jok');

برای ارسال متد HTTP دیگر، request() را صدا بزنید. پارامترها در این حالت هم در Query String قرار می‌گیرند.

$api->request('POST', 'service-name', ['id' => 1]);

خواندن پاسخ

هر فراخوانی موفق یک شیء فقط‌خواندنی NestApi\Http\Response برمی‌گرداند.

عضو	توضیح
`$response->data`	مقدار فیلد `data`
`$response->meta`	مقدار فیلد `meta` یا `null`
`$response->source`	مقدار فیلد `source`
`$response->get('a.b', $default)`	خواندن از داخل `data` با مسیر نقطه‌ای
`$response['key']`	خواندن کلیدهای سطح اول `data`

مسیر get() از داخل data شروع می‌شود، پس کلمهٔ data را در آن ننویسید.

$ip = $api->ipInfo(ip: '8.8.8.8');

$ip['ip'];                              // 8.8.8.8
$ip->get('location.city');              // San Jose
$ip->get('location.zip', 'unknown');    // unknown

مدیریت خطا

پاسخ‌های ناموفق به Exception تبدیل می‌شوند و همهٔ خطاهای API از ApiException ارث‌بری می‌کنند.

کلاس	زمان رخ دادن
`ValidationException`	کدهای `PARAM_NOT_FOUND` و `VALIDATION_ERROR`
`ServiceNotFoundException`	کد `NOT_FOUND`
`RateLimitException`	کدهای `RATE_LIMITED` و `RATE_LIMIT_EXCEEDED`
`ServerException`	خطاهای با وضعیت ۵۰۰ و بالاتر
`ApiException`	سایر خطاهای برگشتی از API
`TransportException`	خطای شبکه یا پاسخ نامعتبر (از `ApiException` مستقل است)

use NestApi\Exception\ApiException;
use NestApi\Exception\TransportException;
use NestApi\Exception\ValidationException;

try {
    $api->ipInfo(ip: 'not-an-ip');
} catch (ValidationException $e) {
    // خطای پارامتر یا اعتبارسنجی
} catch (ApiException $e) {
    // سایر خطاهای گزارش‌شده توسط API
} catch (TransportException $e) {
    // خطای شبکه یا پاسخ غیرقابل استفاده
}

پیکربندی

همهٔ گزینه‌ها در سازنده تنظیم می‌شوند.

گزینه	پیش‌فرض	توضیح
`version`	`1`	نسخهٔ API؛ مقدار `N` مسیر `apis-N` را می‌سازد. نسخهٔ هر سرویس در مستندات همان سرویس آمده است
`baseUrl`	`https://open.nestapi.ir`	آدرس پایه
`timeout`	`30.0`	زمان انتظار به ثانیه، فقط برای کلاینت پیش‌فرض
`client`	Guzzle	هر کلاینت سازگار با PSR-18
`requestFactory`	Guzzle	هر Factory سازگار با PSR-17

$api = new NestApi(version: 2, timeout: 10.0);

متد version() یک نمونهٔ جدید برمی‌گرداند و نمونهٔ اصلی تغییر نمی‌کند.

$v3 = $api->version(3); // $api همچنان روی نسخهٔ 2 می‌ماند

عیب‌یابی

خطای cURL 60

این خطا یعنی PHP فایل گواهی CA را پیدا نمی‌کند. مقدار curl.cainfo را در php.ini روی یک CA bundle معتبر تنظیم کنید. بررسی SSL قابل غیرفعال کردن نیست.

نصب​

شروع سریع​

ارسال پارامترها​

فراخوانی با نام دقیق مسیر​

خواندن پاسخ​

مدیریت خطا​

پیکربندی​

عیب‌یابی​

لینک‌های بیشتر​

نصب