SDK для PHP

Novapost API SDK — це офіційний SDK (Software Development Kit) для PHP, призначений для інтеграції з API Nova Post. За допомогою цього пакета ви можете швидко та зручно підключити до свого PHP-застосунку такі можливості Nova Post, як створення відправлень, відстеження посилок та інші сервіси.

Можливості/Переваги:

• Офіційна підтримка Nova Post — гарантія актуальності, стабільності та підтримки від розробників.
• Відповідність сучасним стандартам PHP — сумісність із сучасними фреймворками та бібліотеками.
• Гнучкість і можливість розширення — можливість замінити логер, HTTP-клієнт, сховище токенів.
• Простота інтеграції — встановлення через Composer, приклади використання включені.

Корисні посилання:

• Packagist — Офіційний Пакет
• GitHub Repository
• Issue Tracker (підтримка та зворотний зв’язок)

Вимоги

• Requires — залежності середовища виконання (обов’язкові для використання в продуктивному середовищі):

  • php >= 8.0 — пакет потребує PHP 8.0 або новішої версії.
  • guzzlehttp/guzzle ^7.0 — HTTP-клієнт для виконання запитів.
  • psr/container ^2.0 — сумісність із контейнерами залежностей PSR.
  • psr/log ^3.0 — інтерфейси логування, сумісні з PSR.
• Requires (Dev) — залежності для розробки (потрібні лише для розробки та CI):

  • phpstan/phpstan ^2.1 — статичний аналіз коду.
  • phpunit/phpunit ^9.6 — модульне тестування.
  • squizlabs/php_codesniffer ^3.13 — перевірка стилю коду та відповідності стандартам кодування.
  • vlucas/phpdotenv ^5.6 — завантаження змінних середовища з файлу .env.
• Suggests: Немає
• Provides: Немає
• Conflicts: Немає
• Replaces: Немає

Встановлення

Щоб розпочати роботу, встановіть SDK через Composer виконавши таку команду:

composer require novadigital/novapost-api-sdk

Робота з SDK

Ініціалізація клієнта

Після встановлення SDK ініціалізуйте клієнт за допомогою NovaPostApiFactory. Це дозволяє швидко створити клієнт для взаємодії з API Nova Post. Використайте наведений нижче приклад коду:

 use NovaDigital\NovaPost\NovaPostApiFactory; use NovaDigital\NovaPost\Exception\ApiException; use NovaDigital\NovaPost\Resources\Division;
$apiKey = 'YOUR_API_KEY';
try {
  $novaPostApi = (new NovaPostApiFactory())($apiKey);
  $searchParams = [
    'textSearch' => 'berlin',
    'divisionCategories' => [Division::DIVISION_CATEGORY_POSTOMAT]
  ];
  $divisions = $novaPostApi->divisions()->get($searchParams);
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage();
} 

Приклад використання методу SDK

Методи SDK мають ті самі назви та параметри, що й відповідні методи клієнтського API. Для розрахунку вартості відправлення використовуйте наступний приклад:

 try {
  $shipmentData = [
    // shipment calculation data
]; $calculationResult = $novaPostApi->shipments()->calculate($shipmentData); } catch (ApiException $e) {
  echo "API Error: " . $e->getMessage();
} 

Розширені можливості

SDK дозволяє замінювати стандартні сервіси (логер, HTTP-клієнт, сховище токенів тощо) власними реалізаціями за допомогою контейнера залежностей ContainerBuilder.

Це корисно, якщо вам потрібно:

• Інтегрувати SDK із системою логування вашого фреймворку.
• Налаштувати HTTP-клієнт із власними параметрами або middleware.
• Використовувати власний механізм зберігання JWT-токенів.

Для цього передайте власні сервіси до фабрики клієнта через ContainerBuilder.

Використання ContainerBuilder

Для більш гнучкого налаштування можна використовувати NovaDigital\NovaPost\DI\ContainerBuilder для конфігурації різних аспектів клієнта.

 use NovaDigital\NovaPost\DI\ContainerBuilder; use NovaDigital\NovaPost\Exception\ApiException; use NovaDigital\NovaPost\NovaPostApiFactory; use NovaDigital\NovaPost\Storage\JwtTokenStorageInterface; use Psr\Log\LoggerInterface; use My\Awesome\MyLogger; use My\Awesome\DbJwtTokenStorageProvider;
$apiKey = 'YOUR_API_KEY';
try {
  $containerBuilder = (new ContainerBuilder())
    ->bind(LoggerInterface::class, MyLogger::class)
    ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);
$novaPostApi = (new NovaPostApiFactory())(
apiKey: $apiKey,
containerBuilder: $containerBuilder
);
$payload = [
// calculation parameters
];
$response = $novaPostApi->shipments()->calculate($payload);
} catch (ApiException $e) {
echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')';
} 

Доступні перевизначення сервісів

За допомогою ContainerBuilder можна перевизначати наступні сервіси:

Сервіс	Призначення
Psr\Log\LoggerInterface	Custom logging
Psr\Http\Client\ClientInterface	Custom HTTP client configuration
NovaDigital\NovaPost\Storage\JwtTokenStorageInterface	Custom JWT token storage
NovaDigital\NovaPost\Http\ResponseHandlerInterface	Custom response processing
NovaDigital\NovaPost\Http\RetryHandlerInterface	Custom retry logic

Відповідність стандартам PSR

Novapost API SDK відповідає таким стандартам PSR, що забезпечує сумісність, сучасний підхід до розробки та високу якість коду.

Стандарт	Призначення
PSR-4: Autoloader	For class autoloading
PSR-11: Container Interface	For a flexible dependency container
PSR-3: Logger Interface	Allows using any compatible logger
PSR-7: HTTP Message Interface	Used for all API requests and responses
PSR-18: HTTP Client	For sending HTTP requests
PSR-17: HTTP Factories	For creating PSR-7 messages
PSR-12: Extended Coding Standard	For coding style

Дотримання цих стандартів робить SDK надійним, передбачуваним і простим для інтеграції в будь-який сучасний PHP-застосунок.