PHPackages tibezh/ukrposhta-php-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. tibezh/ukrposhta-php-sdk ActiveLibrary[API Development](/categories/api) tibezh/ukrposhta-php-sdk ======================== Contains integration with Ukrposhta service. 0.1.2(4mo ago)329MITPHPPHP >=8.3.0CI passing Since Nov 30Pushed 4mo ago2 watchersCompare [ Source](https://github.com/tibezh/ukrposhta-php-sdk)[ Packagist](https://packagist.org/packages/tibezh/ukrposhta-php-sdk)[ RSS](/packages/tibezh-ukrposhta-php-sdk/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (3)Dependencies (5)Versions (5)Used By (0) Ukrpostha PHP SDK ================= [](#ukrpostha-php-sdk) [![Ukrposhta PHP SDK logo](https://raw.githubusercontent.com/tibezh/ukrposhta-php-sdk/master/doc/assets/ukrpostha_logo.svg "Ukrposhta PHP SDK")](https://raw.githubusercontent.com/tibezh/ukrposhta-php-sdk/master/doc/assets/ukrpostha_logo.svg) An Ukrposhta PHP SDK based on the official [Ukrposhta API](https://dev.ukrposhta.ua/documentation "Ukrposhta API"). [![Minimum PHP Version](https://camo.githubusercontent.com/c2dfe3b59a8595179c61864d0d943acb0497fe3c82c65e4753bb306d629a448d/687474703a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e332d3838393242462e737667)](https://php.net/)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tibezh/ukrposhta-php-sdk/blob/master/LICENSE)[![CI](https://github.com/tibezh/ukrposhta-php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/tibezh/ukrposhta-php-sdk/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/270d5ffcf2adb253b83a838d20c7c04c68d132339db91e2aeda24c7eed29f1be/68747470733a2f2f636f6465636f762e696f2f67682f746962657a682f756b72706f736874612d7068702d73646b2f67726170682f62616467652e7376673f746f6b656e3d50505243524239364c5a)](https://codecov.io/gh/tibezh/ukrposhta-php-sdk)[![Latest Stable Version](https://camo.githubusercontent.com/86ec658ed776e31acf65985aac046a809baa2aee7e9acc87d8cab61232cffc16/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746962657a682f756b72706f736874612d7068702d73646b2e737667)](https://packagist.org/packages/tibezh/ukrposhta-php-sdk) Table of Contents ----------------- [](#table-of-contents) - [Requirements](#requirements) - [Available Features](#available-features) - [Installation](#installation) - [Configuration](#configuration) - [Retry Configuration](#retry-configuration) - [Logging](#logging) - [Examples](#examples) - [Status Tracking](#status-tracking) - [Address Classifier](#address-classifier) - [Working with Collections](#working-with-collections) ### Requirements [](#requirements) This library uses PHP 8.3+. To use the Ukrposhta API, you need to have Bearer and Token for each API sub-portal (eCom, StatusTracking and AddressClassifier). After signing the contract, the bearer and token are issued by your manager. You can find more information [here](https://dev.ukrposhta.ua/for-business). ### Available Features [](#available-features) - Status Tracking - available. - Address Classifier (counterparty) - available. - Shipments - *planned*. ### Installation [](#installation) To get started, simply require the project using [Composer](https://getcomposer.org/). ``` composer require tibezh/ukrposhta-php-sdk ``` ### Configuration [](#configuration) #### Retry Configuration [](#retry-configuration) The SDK includes automatic retry logic for transient network errors (connection timeouts, DNS failures, etc.) with exponential backoff and jitter. Default settings: - **Max retries:** 3 attempts - **Base delay:** 100ms (with exponential backoff: 100ms, 200ms, 400ms...) You can customize retry behavior when creating a custom Request object: ``` use Ukrposhta\Request\Request; use Ukrposhta\Tracking\Tracking; // Create a custom request with retry settings. $request = new Request( logger: null, // Optional PSR-3 logger maxRetries: 5, // Max retry attempts (default: 3) retryDelayMs: 200 // Base delay in milliseconds (default: 100) ); // Use the custom request with Tracking. $tracking = new Tracking( bearerStatusTracking: '[BEARER-TOKEN]', request: $request ); ``` To disable retries, set `maxRetries` to 0: ``` $request = new Request(logger: null, maxRetries: 0); ``` #### Logging [](#logging) The SDK supports PSR-3 logging. Pass any PSR-3 compatible logger to track API requests and responses: ``` use Monolog\Logger; use Monolog\Handler\StreamHandler; use Ukrposhta\Tracking\Tracking; $logger = new Logger('ukrposhta'); $logger->pushHandler(new StreamHandler('path/to/ukrposhta.log', Logger::DEBUG)); $tracking = new Tracking( bearerStatusTracking: '[BEARER-TOKEN]', logger: $logger ); ``` ### Examples [](#examples) #### Status Tracking [](#status-tracking) Request last status by barcode: ``` /** @var \Ukrposhta\Tracking\Entities\TrackingStatusInterface $barcodeLastStatus */ $barcodeLastStatus = (new \Ukrposhta\Tracking\Tracking()) ->setAccessToken('[BEARER-STATUS-TRACKING-ACCESS-TOKEN]') // To get results in English: // ->setRequestLang('EN') ->requestBarcodeLastStatus('[BARCODE]'); // Prints event name value of the last status for the given barcode. print $barcodeLastStatus->getEventName(); ``` Request all statuses by barcode: ``` /** @var \Ukrposhta\Tracking\Entities\TrackingStatusCollectionInterface $barcodeStatuses */ $barcodeStatuses = (new \Ukrposhta\Tracking\Tracking()) ->setAccessToken('[BEARER-STATUS-TRACKING-ACCESS-TOKEN]') // To get results in English: // ->setRequestLang('EN') ->requestBarcodeStatuses('[BARCODE]'); // Prints "[date]: [eventName]" of each status for the given barcode. foreach ($barcodeStatuses as $status) { print $status->getDate()->format('c') . ': ' . $status->getEventName(); print ''; } ``` Request route by barcode: ``` /** @var \Ukrposhta\Tracking\Entities\TrackingRouteInterface $barcodeRoute */ $barcodeRoute = (new \Ukrposhta\Tracking\Tracking()) ->setAccessToken('[BEARER-STATUS-TRACKING-ACCESS-TOKEN]') // To get results in English: // ->setRequestLang('EN') ->requestBarcodeRoute('[BARCODE]'); // Prints "[from] -> [to]" information for the given barcode. print $barcodeRoute->getFrom() . ' -> ' . $barcodeRoute->getTo(); ``` #### Address Classifier [](#address-classifier) The Address Classifier API allows you to search regions, districts, cities, streets, post offices and more. Request regions: ``` use Ukrposhta\AddressClassifier\AddressClassifier; use Ukrposhta\Utilities\Languages\LanguagesEnum; $classifier = new AddressClassifier( bearerCounterparty: '[BEARER-COUNTERPARTY-ACCESS-TOKEN]' ); /** @var \Ukrposhta\AddressClassifier\Entities\Region\RegionCollectionInterface $regions */ $regions = $classifier->requestRegions('Київ'); foreach ($regions->all() as $region) { print $region->getId() . ': ' . $region->getName(); print ''; } ``` Request districts by region ID: ``` /** @var \Ukrposhta\AddressClassifier\Entities\District\DistrictCollectionInterface $districts */ $districts = $classifier->requestDistrictsByRegionId(regionId: 1); foreach ($districts->all() as $district) { print $district->getId() . ': ' . $district->getName(); print ''; } ``` Request cities by region ID and district ID: ``` /** @var \Ukrposhta\AddressClassifier\Entities\City\CityCollectionInterface $cities */ $cities = $classifier->requestCityByRegionIdAndDistrictId( regionId: 1, districtId: 5, nameUa: 'Бориспіль' ); foreach ($cities->all() as $city) { print $city->getId() . ': ' . $city->getName()->getByLanguage(LanguagesEnum::UA); print ''; } ``` Request streets by city ID: ``` /** @var \Ukrposhta\AddressClassifier\Entities\Street\StreetCollectionInterface $streets */ $streets = $classifier->requestStreetByRegionIdAndDistrictIdAndCityId( regionId: 1, districtId: 5, cityId: 100, nameUa: 'Головна' ); foreach ($streets->all() as $street) { print $street->getId() . ': ' . $street->getName()->getByLanguage(LanguagesEnum::UA); print ''; } ``` Request post offices by city ID: ``` /** @var \Ukrposhta\AddressClassifier\Entities\PostOffice\PostOfficeCollectionInterface $postOffices */ $postOffices = $classifier->requestPostOfficeByCityId(cityId: 100); foreach ($postOffices->all() as $postOffice) { print $postOffice->getPostIndex() . ': ' . $postOffice->getName()->getByLanguage(LanguagesEnum::UA); print ''; } ``` Request nearest post offices by geolocation: ``` /** @var \Ukrposhta\AddressClassifier\Entities\NearestPostOffice\NearestPostOfficeCollectionInterface $nearestPostOffices */ $nearestPostOffices = $classifier->requestNearestPostOffices( latitude: 50.4501, longitude: 30.5234, maxDistance: 1000 // meters ); foreach ($nearestPostOffices->all() as $postOffice) { print $postOffice->getFilialName() . ' - ' . $postOffice->getDistance() . ' m'; print ''; } ``` Fuzzy search for cities: ``` /** @var \Ukrposhta\AddressClassifier\Entities\CitySearchItem\CitySearchItemCollectionInterface $cities */ $cities = $classifier->requestSearchCity( regionId: 1, districtId: 5, cityName: 'Борис', // partial name language: LanguagesEnum::UA, fuzzy: true ); foreach ($cities->all() as $city) { print $city->getName() . ' (' . $city->getTypeName() . ')'; print ''; } ``` ### Working with Collections [](#working-with-collections) All collection classes implement `Countable` and `IteratorAggregate`/`Iterator` interfaces, allowing you to: ``` // Get count of items. $count = count($regions); // Or use the count() method. $count = $regions->count(); // Check if collection is empty. if ($regions->isEmpty()) { echo 'No regions found'; } // Iterate directly with foreach. foreach ($regions as $region) { echo $region->getName(); } // Get all items as array. $allRegions = $regions->all(); ``` ### Health Score 38 — LowBetter than 85% of packages Maintenance75 Regular maintenance activity Popularity10 Limited adoption so far Community10 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 89.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~251 days Total 4 Last Release 139d ago PHP version history (2 changes)0.0.1PHP >=8.1.0 0.1.0PHP >=8.3.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/6b11330a453f35f0682c5597495bf365486a6c72550997ce92fbd5bded925aaf?d=identicon)[Ivan Tibezh](/maintainers/Ivan%20Tibezh) --- Top Contributors [![tibezh](https://avatars.githubusercontent.com/u/1250633?v=4)](https://github.com/tibezh "tibezh (58 commits)")[![ivantibezh](https://avatars.githubusercontent.com/u/117276906?v=4)](https://github.com/ivantibezh "ivantibezh (7 commits)") --- Tags sdksdk-phpukrposhtaukrposhta-apiukrposhta-php-sdkUkrposthaUkrpostha PHPUkrpostha PHP SDKUkrpostha SDKUkrpostha PHP APIUkrpostha API ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/tibezh-ukrposhta-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/tibezh-ukrposhta-php-sdk/health.svg)](https://phpackages.com/packages/tibezh-ukrposhta-php-sdk) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M650](/packages/sylius-sylius)[theodo-group/llphant LLPhant is a library to help you build Generative AI applications. 1.5k311.5k5](/packages/theodo-group-llphant)[wheelpros/fitment-platform-api Magento 2 (Open Source) 12.1k1.2k](/packages/wheelpros-fitment-platform-api)[alexacrm/dynamics-webapi-toolkit Web API toolkit for Microsoft Dynamics 365 and Dynamics CRM 81324.1k1](/packages/alexacrm-dynamics-webapi-toolkit)[commercetools/commercetools-sdk The official PHP SDK for the commercetools Composable Commerce APIs 19281.5k](/packages/commercetools-commercetools-sdk)[keboola/storage-api-client Keboola Storage API PHP Client 10387.5k25](/packages/keboola-storage-api-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)