{"id":21602830,"url":"https://github.com/revotale/php-nova-poshta","last_synced_at":"2026-01-11T11:02:02.610Z","repository":{"id":62495035,"uuid":"349731186","full_name":"RevoTale/php-nova-poshta","owner":"RevoTale","description":"PHP implementation of Ukrainian delivery service Nova Poshta API v2","archived":false,"fork":false,"pushed_at":"2025-11-27T14:07:51.000Z","size":345,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-30T06:59:27.765Z","etag":null,"topics":["client-library","novaposhta-client","php","php-library"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RevoTale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-03-20T13:22:26.000Z","updated_at":"2025-11-27T14:07:53.000Z","dependencies_parsed_at":"2023-12-10T21:31:12.901Z","dependency_job_id":"1ffac909-c7fc-491c-bd11-12064d0010ae","html_url":"https://github.com/RevoTale/php-nova-poshta","commit_stats":null,"previous_names":["rustedlabs/php-nova-poshta","rusted-love/php-nova-poshta-api","revotale/php-nova-poshta"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/RevoTale/php-nova-poshta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RevoTale%2Fphp-nova-poshta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RevoTale%2Fphp-nova-poshta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RevoTale%2Fphp-nova-poshta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RevoTale%2Fphp-nova-poshta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RevoTale","download_url":"https://codeload.github.com/RevoTale/php-nova-poshta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RevoTale%2Fphp-nova-poshta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28301302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T08:21:30.231Z","status":"ssl_error","status_checked_at":"2026-01-11T08:21:26.882Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-library","novaposhta-client","php","php-library"],"created_at":"2024-11-24T19:14:29.425Z","updated_at":"2026-01-11T11:02:02.605Z","avatar_url":"https://github.com/RevoTale.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Nova Poshta API Client\n\n[![PHP Version](https://img.shields.io/badge/php-^8.3-blue.svg)](https://www.php.net)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Composer Package](https://img.shields.io/badge/composer-grisaia%2Fnova--poshta-orange.svg)](https://packagist.org/packages/grisaia/nova-poshta)\n\nA 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.\n\n## 🚀 Features\n\n- **Full API 2.0 Coverage**: Complete implementation of Nova Poshta API 2.0\n- **Type Safety**: Built with PHP 8.3+ features including strict types and readonly classes\n- **Service-Oriented Architecture**: Clean separation of concerns with dedicated service classes\n- **Exception Handling**: Comprehensive error handling with specific exception types\n- **PSR-4 Compatible**: Follows PSR-4 autoloading standards\n- **Logging Support**: PSR-3 compatible logging interface\n- **Modern PHP**: Leverages enums, readonly properties, and other modern PHP features\n\n## 📋 Requirements\n\n- PHP 8.3 or higher\n- cURL extension\n- JSON extension\n\n## 📦 Installation\n\nInstall via Composer:\n\n```bash\ncomposer require grisaia/nova-poshta\n```\n\n## 🔧 Configuration\n\n### Basic Setup\n\n```php\n\u003c?php\n\nuse Grisaia\\NovaPoshta\\NovaPoshtaAPI;\nuse Grisaia\\NovaPoshta\\Services\\SettlementService;\n\n// Initialize the API client with your API key\n$api = new NovaPoshtaAPI('your-api-key-here');\n\n// Optional: Set custom timeout (default is 4 seconds)\n$api-\u003esetTimeoutInSeconds(10);\n\n// Optional: Add PSR-3 compatible logger\n$api-\u003esetLogger($yourLogger);\n\n// Get a service instance\n$settlementService = $api-\u003egetService(SettlementService::class);\n```\n\n## 🛠️ Usage Examples\n\n### Settlement Operations\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\SettlementService;\nuse Grisaia\\NovaPoshta\\MethodProperties\\Address\\SettlementSearchProperties;\n\n$settlementService = $api-\u003egetService(SettlementService::class);\n\n// Get settlements list with pagination\n$settlements = $settlementService-\u003egetSettlementList(\n    page: 1,\n    limit: 20,\n    regionRef: 'some-region-ref', // optional\n    areaRef: 'some-area-ref',     // optional\n    hasWarehouse: true            // optional\n);\n\n// Search for settlements\n$searchProps = new SettlementSearchProperties();\n$searchProps-\u003esetCityName('Київ');\n$searchProps-\u003esetLimit(10);\n\n$searchResults = $settlementService-\u003esearchSettlements($searchProps);\n\n// Search settlement streets\n$streets = $settlementService-\u003esearchSettlementStreets(\n    streetName: 'Хрещатик',\n    settlementRef: 'settlement-ref',\n    limit: 10,\n    page: 1\n);\n```\n\n### Warehouse Operations\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\WarehouseService;\nuse Grisaia\\NovaPoshta\\MethodProperties\\Address\\WarehouseListProperties;\n\n$warehouseService = $api-\u003egetService(WarehouseService::class);\n\n// Get warehouses with filters\n$warehouseProps = new WarehouseListProperties();\n$warehouseProps-\u003esetCityName('Київ');\n$warehouseProps-\u003esetPage(1);\n$warehouseProps-\u003esetLimit(50);\n$warehouseProps-\u003esetHasPostFinance(true);\n$warehouseProps-\u003esatHasBicycleParking(false);\n\n$warehouses = $warehouseService-\u003egetWarehouseList($warehouseProps);\n\n// Get warehouse types\n$warehouseTypes = $warehouseService-\u003egetWarehouseTypeList();\n```\n\n### Counterparty Management\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\CounterpartyService;\nuse Grisaia\\NovaPoshta\\MethodProperties\\Counterparty\\CounterpartySaveProperties;\nuse Grisaia\\NovaPoshta\\MethodProperties\\Counterparty\\CounterpartyListProperties;\nuse Grisaia\\NovaPoshta\\DataAdapters\\Enums\\CounterpartyPersonType;\nuse Grisaia\\NovaPoshta\\DataAdapters\\Enums\\CounterpartyType;\n\n$counterpartyService = $api-\u003egetService(CounterpartyService::class);\n\n// Create a new counterparty\n$saveProps = new CounterpartySaveProperties();\n$saveProps-\u003esetFirstName('Іван');\n$saveProps-\u003esetLastName('Петренко');\n$saveProps-\u003esetPhone('0501234567');\n$saveProps-\u003esetCounterpartyType(CounterpartyType::PrivatePerson);\n\n$result = $counterpartyService-\u003esaveCounterparty($saveProps);\n\n// Get counterparties list\n$listProps = new CounterpartyListProperties(CounterpartyPersonType::Sender);\n$listProps-\u003esetPage(1);\n$listProps-\u003esetLimit(20);\n$listProps-\u003efindByString('Петренко');\n\n$counterparties = $counterpartyService-\u003egetCounterpartyList($listProps);\n\n// Get contact persons for a counterparty\n$contacts = $counterpartyService-\u003egetCounterpartyContactPerson('counterparty-ref', 1);\n```\n\n### Document Operations\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\DocumentService;\n\n$documentService = $api-\u003egetService(DocumentService::class);\n\n// Get document information\ntry {\n    $document = $documentService-\u003egetDocument('20450123456789');\n    echo \"Document status: \" . $document-\u003egetStateName();\n} catch (DocumentNotFoundException $e) {\n    echo \"Document not found\";\n}\n\n// Track multiple documents\n$trackingNumbers = ['20450123456789', '20450987654321'];\n$trackingResults = $documentService-\u003egetDocumentTrackingStatus($trackingNumbers);\n\nforeach ($trackingResults-\u003egetTrackingItems() as $tracking) {\n    echo \"Number: \" . $tracking-\u003egetNumber() . \" - Status: \" . $tracking-\u003egetStatus() . \"\\n\";\n}\n```\n\n### Document Files\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\DocumentFileService;\nuse Grisaia\\NovaPoshta\\DataAdapters\\Enums\\DocumentPrintType;\n\n$fileService = $api-\u003egetService(DocumentFileService::class);\n\n// Save document labels to file\ntry {\n    $fileService-\u003esaveDocumentsFile(\n        destination: '/path/to/labels.pdf',\n        documents: ['20450123456789', '20450987654321'],\n        type: DocumentPrintType::Sticker,\n        timeout: 10\n    );\n    echo \"Labels saved successfully\";\n} catch (FileSaveException $e) {\n    echo \"Failed to save file: \" . $e-\u003egetMessage();\n}\n```\n\n### Additional Services\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\AdditionalService;\nuse Grisaia\\NovaPoshta\\MethodProperties\\AdditionalService\\Save\\OrderRedirectingProperties;\n\n$additionalService = $api-\u003egetService(AdditionalService::class);\n\n// Request package redirection\n$redirectProps = new OrderRedirectingProperties();\n$redirectProps-\u003esetDocumentNumber('20450123456789');\n$redirectProps-\u003esetRecipientPhone('0501234567');\n$redirectProps-\u003esetRecipientContactName('Нове Ім\\'я');\n$redirectProps-\u003esetNoteAddressRecipient('Нова адреса');\n\n$result = $additionalService-\u003erequestAdditionalService($redirectProps);\n```\n\n### City Operations\n\n```php\nuse Grisaia\\NovaPoshta\\Services\\CityService;\nuse Grisaia\\NovaPoshta\\MethodProperties\\Address\\CityListProperties;\n\n$cityService = $api-\u003egetService(CityService::class);\n\n// Get cities list\n$cityProps = new CityListProperties();\n$cityProps-\u003esetPage(1);\n$cityProps-\u003esetLimit(50);\n$cityProps-\u003efindByString('Київ');\n\n$cities = $cityService-\u003egetCityList($cityProps);\n\n// Convert settlement to city (Nova Poshta specific requirement)\ntry {\n    $city = $cityService-\u003egetCityBySettlement('settlement-ref');\n} catch (CityBySettlementException $e) {\n    echo \"Settlement not found or cannot be converted to city\";\n}\n```\n\n## 🏗️ Available Services\n\n| Service | Description |\n|---------|-------------|\n| `SettlementService` | Manage settlements, areas, regions, and street search |\n| `WarehouseService` | Handle warehouse listings and types |\n| `CounterpartyService` | Manage counterparties and contact persons |\n| `DocumentService` | Document operations and tracking |\n| `DocumentFileService` | Generate and save document files (labels, invoices) |\n| `CityService` | City management and settlement conversion |\n| `AdditionalService` | Additional services (redirections, changes, returns) |\n| `ScanSheetService` | Scan sheet operations |\n\n## 🔧 Advanced Configuration\n\n### Custom Logging\n\n```php\nuse Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\n\n$logger = new Logger('nova-poshta');\n$logger-\u003epushHandler(new StreamHandler('path/to/logfile.log', Logger::INFO));\n\n$api = new NovaPoshtaAPI('your-api-key');\n$api-\u003esetLogger($logger);\n```\n\n### Error Handling\n\nThe library provides specific exception types for different error scenarios:\n\n```php\nuse Grisaia\\NovaPoshta\\Exception\\QueryFailed\\QueryFailedException;\nuse Grisaia\\NovaPoshta\\Exception\\QueryFailed\\CurlException;\nuse Grisaia\\NovaPoshta\\Exception\\DocumentNotFoundException;\nuse Grisaia\\NovaPoshta\\Exception\\BadValueException;\n\ntry {\n    $result = $settlementService-\u003egetSettlementList(1, 10);\n} catch (CurlException $e) {\n    // Handle network errors\n    echo \"Network error: \" . $e-\u003egetMessage();\n} catch (QueryFailedException $e) {\n    // Handle API errors\n    echo \"API error: \" . $e-\u003egetMessage();\n} catch (BadValueException $e) {\n    // Handle data validation errors\n    echo \"Data error: \" . $e-\u003egetMessage();\n}\n```\n\n## 🧪 Development\n\n### Running Tests\n\n```bash\n# Run all tests\ncomposer test\n\n# Run individual test suites\ncomposer phpunit\ncomposer phpstan\ncomposer phpmd\n\n# Fix code style\ncomposer fix\n```\n\n### Code Quality Tools\n\nThis package uses several tools to maintain code quality:\n\n- **PHPStan**: Static analysis (level max)\n- **PHPMD**: Mess detection\n- **PHPUnit**: Unit testing\n\n## 🏗️ Architecture\n\nThe package follows a clean architecture pattern:\n\n```\nsrc/\n├── NovaPoshtaAPI.php           # Main entry point\n├── Services/                   # Service layer\n├── DataAdapters/              # Data transformation layer\n│   ├── Entities/              # Entity classes\n│   ├── Enums/                 # Enumeration classes\n│   └── Result/                # Result wrapper classes\n├── MethodProperties/          # Request parameter classes\n├── Exception/                 # Exception hierarchy\n└── Normalizer/               # Data normalization utilities\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. Make sure to:\n\n1. Follow the existing code style\n2. Add tests for new functionality\n3. Update documentation as needed\n4. Run the test suite before submitting\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [Packagist Package](https://packagist.org/packages/grisaia/nova-poshta)\n- [Issues \u0026 Support](https://github.com/RevoTale/php-nova-poshta/issues)\n\n## 📞 Support\n\nIf you encounter any issues or have questions, please:\n\n1. Check the [API documentation](https://developers.novaposhta.ua/)\n2. Review existing [issues](https://github.com/your-username/php-nova-poshta/issues)\n3. Create a new issue with detailed information\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevotale%2Fphp-nova-poshta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frevotale%2Fphp-nova-poshta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frevotale%2Fphp-nova-poshta/lists"}