دسته‌ها را مشاهده کنید

استفاده از SDKهای PHP تولیدشده در Postman

مدت زمان مطالعه: : 3 دقیقه

این راهنما روش استفاده از SDKهای PHP تولیدشده با Postman SDK Generator را توضیح می‌دهد. خروجی PHP با Composer کار می‌کند و برای نصب محلی، انتشار در Packagist، authentication، error handling، environment، retry و optional/nullable fieldها آماده است.

ساختار SDK PHP #

  • src/: کد اصلی SDK.
  • Services/: service classها برای endpoint groupها.
  • Models/: modelهای request/response و exceptionهای typed.
  • Http/: HTTP client، middleware، retry و transport.
  • composer.json: metadata، autoload و dependencyهای package.

اجرای نمونه SDK #

هر SDK تولیدشده پوشه examples/ دارد. قبل از ورود به پروژه اصلی، نمونه را اجرا کنید.

cd examples
composer install
php index.php
<?php

use YourSdk\YourSdk;

$sdk = new YourSdk([
    'apiKey' => 'your-api-key',
    'baseUrl' => 'https://api.example.com',
]);

try {
    $user = $sdk->users()->getUser('123');
    print_r($user);
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Import کردن SDK PHP به صورت local #

روش local path #

در پروژه خود، مسیر SDK را به composer.json اضافه کنید.

{
  "repositories": [
    {
      "type": "path",
      "url": "../path/to/your-sdk"
    }
  ],
  "require": {
    "your-org/your-sdk": "*"
  }
}
composer update

روش Packagist #

اگر SDK در Packagist منتشر شده باشد، نصب ساده است:

composer require your-org/your-sdk

انتشار در Packagist #

برای انتشار SDK PHP به repository Git، حساب Packagist و composer.json درست نیاز دارید.

تنظیم composer.json #

{
  "name": "your-org/your-sdk",
  "description": "SDK for Your API",
  "version": "1.0.0",
  "type": "library",
  "autoload": {
    "psr-4": {
      "YourSdk\": "src/"
    }
  },
  "require": {
    "php": ">=8.1"
  },
  "license": "MIT"
}

انتشار package #

  1. کد را در repository Git قرار دهید.
  2. یک tag نسخه بسازید.
  3. repository را در Packagist submit کنید.
git tag v1.0.0
git push origin v1.0.0

برای انتشار نسخه جدید، version و tag را افزایش دهید و push کنید.

بهترین کارها برای PHP SDK #

  • از PSR-۴ autoloading استفاده کنید.
  • نام package را با vendor واقعی انتخاب کنید.
  • README و نمونه کد واضح داشته باشید.
  • از semantic versioning استفاده کنید.
  • قبل از انتشار، composer install و testها را اجرا کنید.

Authentication #

$sdk = new YourSdk(['apiKey' => 'your-api-key']);
$sdk = new YourSdk(['accessToken' => 'your-bearer-token']);
$sdk = new YourSdk([
    'username' => 'your-username',
    'password' => 'your-password',
]);
$sdk->setApiKey('new-api-key');
$sdk->setAccessToken('new-token');

Error handling #

SDK برای خطاهای API exceptionهای مشخص تولید می‌کند. این exceptionها معمولا message، status code و response body را دارند.

try {
    $user = $sdk->users()->getUser('123');
} catch (ValidationException $e) {
    echo 'Validation failed: ' . $e->getMessage();
} catch (ApiException $e) {
    echo 'API error: ' . $e->getMessage();
    echo 'Status: ' . $e->getStatusCode();
    echo 'Response: ' . $e->getResponseBody();
} catch (Exception $e) {
    echo 'Unexpected error: ' . $e->getMessage();
}

Environment management #

$sdk = new YourSdk([
    'environment' => Environment::PRODUCTION,
    'apiKey' => 'your-api-key',
]);

$customSdk = new YourSdk([
    'baseUrl' => 'https://custom.api.example.com',
    'apiKey' => 'your-api-key',
]);

Hierarchical configuration #

تنظیمات می‌توانند در سطح SDK، service، method و request اعمال شوند. request config خاص‌ترین سطح است.

$requestConfig = new RequestConfig([
    'timeout' => 30,
    'baseUrl' => 'https://legacy-api.example.com',
]);

$user = $sdk->users()->getUser('123', $requestConfig);

Timeout و retry #

$sdk = new YourSdk([
    'apiKey' => 'your-api-key',
    'timeout' => 10,
    'retry' => [
        'attempts' => 3,
        'delay' => 1,
        'maxDelay' => 30,
        'backoffFactor' => 2,
    ],
]);

Optional و nullable fieldها #

در PHP، SDK باید تفاوت بین field ارسال‌نشده، مقدار null و مقدار واقعی را حفظ کند. این موضوع برای update و PATCH مهم است.

$request = new UpdateUserRequest([
    'name' => 'new name',
    'middleName' => null,
]);

منابع داخل SDK #

  • پوشه documentation/ برای مستندات serviceها و modelها.
  • پوشه examples/ برای نمونه اجرایی.
  • composer.json برای autoload و dependencyها.
  • exceptionهای typed برای خطاهای API و validation.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.

به‌روزرسانی شده در 1405-04-15

احساسات شما چیست؟

  • خوشحال
  • عادی
  • ناراحت

دیدگاهتان را بنویسید