README

A modern PHP library for interacting with the Ukrainian delivery service Nova Poshta via their API 2.0. This package provides a clean, type-safe interface for all Nova Poshta services including settlements, warehouses, counterparties, documents, and additional services.

???? Features

• Full API 2.0 Coverage: Complete implementation of Nova Poshta API 2.0
• Type Safety: Built with PHP 8.3+ features including strict types and readonly classes
• Service-Oriented Architecture: Clean separation of concerns with dedicated service classes
• Exception Handling: Comprehensive error handling with specific exception types
• PSR-4 Compatible: Follows PSR-4 autoloading standards
• Logging Support: PSR-3 compatible logging interface
• Modern PHP: Leverages enums, readonly properties, and other modern PHP features

???? Requirements

• PHP 8.3 or higher
• cURL extension
• JSON extension

???? Installation

Install via Composer:

composer require grisaia/nova-poshta

???? Configuration

Basic Setup

<?php use Grisaia\NovaPoshta\NovaPoshtaAPI; use Grisaia\NovaPoshta\Services\SettlementService; // Initialize the API client with your API key $api = new NovaPoshtaAPI('your-api-key-here'); // Optional: Set custom timeout (default is 4 seconds) $api->setTimeoutInSeconds(10); // Optional: Add PSR-3 compatible logger $api->setLogger($yourLogger); // Get a service instance $settlementService = $api->getService(SettlementService::class);

????️ Usage Examples

Settlement Operations

use Grisaia\NovaPoshta\Services\SettlementService; use Grisaia\NovaPoshta\MethodProperties\Address\SettlementSearchProperties; $settlementService = $api->getService(SettlementService::class); // Get settlements list with pagination $settlements = $settlementService->getSettlementList( page: 1, limit: 20, regionRef: 'some-region-ref', // optional areaRef: 'some-area-ref', // optional hasWarehouse: true // optional ); // Search for settlements $searchProps = new SettlementSearchProperties(); $searchProps->setCityName('Київ'); $searchProps->setLimit(10); $searchResults = $settlementService->searchSettlements($searchProps); // Search settlement streets $streets = $settlementService->searchSettlementStreets( streetName: 'Хрещатик', settlementRef: 'settlement-ref', limit: 10, page: 1 );

Warehouse Operations

use Grisaia\NovaPoshta\Services\WarehouseService; use Grisaia\NovaPoshta\MethodProperties\Address\WarehouseListProperties; $warehouseService = $api->getService(WarehouseService::class); // Get warehouses with filters $warehouseProps = new WarehouseListProperties(); $warehouseProps->setCityName('Київ'); $warehouseProps->setPage(1); $warehouseProps->setLimit(50); $warehouseProps->setHasPostFinance(true); $warehouseProps->satHasBicycleParking(false); $warehouses = $warehouseService->getWarehouseList($warehouseProps); // Get warehouse types $warehouseTypes = $warehouseService->getWarehouseTypeList();

Counterparty Management

use Grisaia\NovaPoshta\Services\CounterpartyService; use Grisaia\NovaPoshta\MethodProperties\Counterparty\CounterpartySaveProperties; use Grisaia\NovaPoshta\MethodProperties\Counterparty\CounterpartyListProperties; use Grisaia\NovaPoshta\DataAdapters\Enums\CounterpartyPersonType; use Grisaia\NovaPoshta\DataAdapters\Enums\CounterpartyType; $counterpartyService = $api->getService(CounterpartyService::class); // Create a new counterparty $saveProps = new CounterpartySaveProperties(); $saveProps->setFirstName('Іван'); $saveProps->setLastName('Петренко'); $saveProps->setPhone('0501234567'); $saveProps->setCounterpartyType(CounterpartyType::PrivatePerson); $result = $counterpartyService->saveCounterparty($saveProps); // Get counterparties list $listProps = new CounterpartyListProperties(CounterpartyPersonType::Sender); $listProps->setPage(1); $listProps->setLimit(20); $listProps->findByString('Петренко'); $counterparties = $counterpartyService->getCounterpartyList($listProps); // Get contact persons for a counterparty $contacts = $counterpartyService->getCounterpartyContactPerson('counterparty-ref', 1);

Document Operations

use Grisaia\NovaPoshta\Services\DocumentService; $documentService = $api->getService(DocumentService::class); // Get document information try { $document = $documentService->getDocument('20450123456789'); echo "Document status: " . $document->getStateName(); } catch (DocumentNotFoundException $e) { echo "Document not found"; } // Track multiple documents $trackingNumbers = ['20450123456789', '20450987654321']; $trackingResults = $documentService->getDocumentTrackingStatus($trackingNumbers); foreach ($trackingResults->getTrackingItems() as $tracking) { echo "Number: " . $tracking->getNumber() . " - Status: " . $tracking->getStatus() . "\n"; }

Document Files

use Grisaia\NovaPoshta\Services\DocumentFileService; use Grisaia\NovaPoshta\DataAdapters\Enums\DocumentPrintType; $fileService = $api->getService(DocumentFileService::class); // Save document labels to file try { $fileService->saveDocumentsFile( destination: '/path/to/labels.pdf', documents: ['20450123456789', '20450987654321'], type: DocumentPrintType::Sticker, timeout: 10 ); echo "Labels saved successfully"; } catch (FileSaveException $e) { echo "Failed to save file: " . $e->getMessage(); }

Additional Services

use Grisaia\NovaPoshta\Services\AdditionalService; use Grisaia\NovaPoshta\MethodProperties\AdditionalService\Save\OrderRedirectingProperties; $additionalService = $api->getService(AdditionalService::class); // Request package redirection $redirectProps = new OrderRedirectingProperties(); $redirectProps->setDocumentNumber('20450123456789'); $redirectProps->setRecipientPhone('0501234567'); $redirectProps->setRecipientContactName('Нове Ім\'я'); $redirectProps->setNoteAddressRecipient('Нова адреса'); $result = $additionalService->requestAdditionalService($redirectProps);

City Operations

use Grisaia\NovaPoshta\Services\CityService; use Grisaia\NovaPoshta\MethodProperties\Address\CityListProperties; $cityService = $api->getService(CityService::class); // Get cities list $cityProps = new CityListProperties(); $cityProps->setPage(1); $cityProps->setLimit(50); $cityProps->findByString('Київ'); $cities = $cityService->getCityList($cityProps); // Convert settlement to city (Nova Poshta specific requirement) try { $city = $cityService->getCityBySettlement('settlement-ref'); } catch (CityBySettlementException $e) { echo "Settlement not found or cannot be converted to city"; }

????️ Available Services

???? Advanced Configuration

Custom Logging

use Monolog\Logger; use Monolog\Handler\StreamHandler; $logger = new Logger('nova-poshta'); $logger->pushHandler(new StreamHandler('path/to/logfile.log', Logger::INFO)); $api = new NovaPoshtaAPI('your-api-key'); $api->setLogger($logger);

Error Handling

The library provides specific exception types for different error scenarios:

use Grisaia\NovaPoshta\Exception\QueryFailed\QueryFailedException; use Grisaia\NovaPoshta\Exception\QueryFailed\CurlException; use Grisaia\NovaPoshta\Exception\DocumentNotFoundException; use Grisaia\NovaPoshta\Exception\BadValueException; try { $result = $settlementService->getSettlementList(1, 10); } catch (CurlException $e) { // Handle network errors echo "Network error: " . $e->getMessage(); } catch (QueryFailedException $e) { // Handle API errors echo "API error: " . $e->getMessage(); } catch (BadValueException $e) { // Handle data validation errors echo "Data error: " . $e->getMessage(); }

???? Development

Running Tests

# Run all tests composer test # Run individual test suites composer phpunit composer phpstan composer phpmd # Fix code style composer fix

Code Quality Tools

This package uses several tools to maintain code quality:

• PHPStan: Static analysis (level max)
• PHPMD: Mess detection
• PHPUnit: Unit testing

????️ Architecture

The package follows a clean architecture pattern:

src/ ├── NovaPoshtaAPI.php # Main entry point ├── Services/ # Service layer ├── DataAdapters/ # Data transformation layer │ ├── Entities/ # Entity classes │ ├── Enums/ # Enumeration classes │ └── Result/ # Result wrapper classes ├── MethodProperties/ # Request parameter classes ├── Exception/ # Exception hierarchy └── Normalizer/ # Data normalization utilities 

???? Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Follow the existing code style
2. Add tests for new functionality
3. Update documentation as needed
4. Run the test suite before submitting

???? License

This project is licensed under the MIT License - see the LICENSE file for details.

???? Links

• Packagist Package
• Issues & Support

???? Support

If you encounter any issues or have questions, please:

1. Check the API documentation
2. Review existing issues
3. Create a new issue with detailed information