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

این راهنما روش استفاده از 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، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.