PHPackages daika7ana/ecolet-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. [HTTP & Networking](/categories/http) 4. / 5. daika7ana/ecolet-php-sdk ActiveLibrary[HTTP & Networking](/categories/http) daika7ana/ecolet-php-sdk ======================== Typed PHP SDK for the Ecolet Courier API. v1.0.5(1mo ago)234GPL-3.0-or-laterPHPPHP >=8.3CI passing Since Apr 9Pushed 1mo agoCompare [ Source](https://github.com/daika7ana/ecolet-php-sdk)[ Packagist](https://packagist.org/packages/daika7ana/ecolet-php-sdk)[ Docs](https://github.com/daika7ana/ecolet-php-sdk)[ RSS](/packages/daika7ana-ecolet-php-sdk/feed)WikiDiscussions master Synced 1w ago READMEChangelog (6)Dependencies (16)Versions (8)Used By (0) Ecolet PHP SDK ============== [](#ecolet-php-sdk) [![CI](https://github.com/daika7ana/ecolet-php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/daika7ana/ecolet-php-sdk/actions/workflows/ci.yml)[![PHP 8.3+](https://camo.githubusercontent.com/c55b9100c1ce5e9fbbfffdfe87d57ea6bfbae24b094fb12a25236b89411fd99b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://www.php.net/)[![PHPUnit](https://camo.githubusercontent.com/8e2629b3de4beefd470f82be6adc3212fa1957a144c66814fac234ed46bbd82e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d31322e782d3041374242423f7374796c653d666c61742d737175617265)](docs/TESTING.md)[![Smoke Tests](https://camo.githubusercontent.com/fee9224a9d7e9f0be26fa528f7b2d8d38147ced8da8abe92b11bba97d1a90e1c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f536d6f6b6525323054657374732d4c6976652532304150492d6f72616e67653f7374796c653d666c61742d737175617265)](docs/TESTING.md)[![PSR Standards](https://camo.githubusercontent.com/6fc0261a04d0e205fb94da2b6f36731b4a760d541422d8891fb01d1e6533a955/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d37253246313725324631382d626c75653f7374796c653d666c61742d737175617265)](https://www.php-fig.org/)[![License](https://camo.githubusercontent.com/2be05c1ee647f7bcb4f547df19cc78f192a840670c62767563f0e2b3b6e52c0c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d332e302d2d6f722d2d6c617465722d677265656e3f7374796c653d666c61742d737175617265)](LICENSE) A modern, type-safe PHP SDK for the **Ecolet Courier API** > ๐Ÿš€ Framework-agnostic, OAuth-powered, fully typed with DTOs, and production-ready. Table of Contents ----------------- [](#table-of-contents) - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Quick Start](#quick-start) - [Configuration](#configuration) - [Authentication](#authentication) - [Supported Resources](#supported-resources) - [Framework Support](#framework-support) - [Testing](#testing) - [Documentation](#documentation) Features -------- [](#features) ### Core Strengths [](#core-strengths) - โœ… **OAuth 2.0 Password Grant** โ€” Industry-standard authentication - โœ… **Automatic Token Refresh** โ€” No manual token management needed - โœ… **Token Inspection & Restore** โ€” Read the current token or inject a cached one - โœ… **PSR-18 HTTP Client** โ€” Pluggable, with Guzzle adapter by default - โœ… **Explicit Environment Selection** โ€” Production by default, staging via `ClientConfig` when needed - โœ… **Fully Typed DTOs** โ€” Type-safe request/response handling - โœ… **Static Analysis with PHPStan** โ€” Strict type checks for the `src/` codebase - โœ… **Iterable Collections** โ€” `count`, `first`, `last`, `get`, `keys`, `values`, `has`, `filter`, `map`, `mapWithKeys`, `pluck` - โœ… **Waybill Helpers** โ€” Filename, contents, and download headers on `WaybillDocument` - โœ… **Symfony/Laravel Bridge** โ€” Optional `HttpFoundationBridge` for seamless integration - โœ… **Comprehensive Tests** โ€” Unit and smoke test suites included ### Perfect For [](#perfect-for) - ๐ŸŽฏ Laravel applications or any PHP framework - ๐ŸŽฏ Microservices and standalone PHP projects - ๐ŸŽฏ Type-safe courier management workflows - ๐ŸŽฏ Production deployments with full test coverage Requirements ------------ [](#requirements) - **PHP 8.3+** with `json` and `curl` extensions - PSR-7 / PSR-17 / PSR-18 compatible environment Installation ------------ [](#installation) ### Via Composer [](#via-composer) ``` composer require daika7ana/ecolet-php-sdk ``` Quick Start ----------- [](#quick-start) Working with the Ecolet API is straightforward: ``` use Daika7ana\Ecolet\Client; $client = Client::create(); $client->authenticate( username: 'user@example.com', password: 'your-password', clientId: 'your-client-id', clientSecret: 'your-client-secret', scope: '' ); $user = $client->users()->getMe(); echo $user->email; ``` That's it! You've got a fully authenticated client ready to fetch courier data. Configuration ------------- [](#configuration) ### Base URL & Environment [](#base-url--environment) By default, the client runs against **production**. To enable staging globally: ``` use Daika7ana\Ecolet\Config\ClientConfig; ClientConfig::setTestMode(true); // Enable staging ``` ### Explicit Base URL [](#explicit-base-url) For explicit control without global state: ``` use Daika7ana\Ecolet\Client; use Daika7ana\Ecolet\Config\ClientConfig; // Staging $config = new ClientConfig(baseUrl: ClientConfig::BASE_URL_STAGING); $client = Client::create(config: $config); // Or production (the default) $config = new ClientConfig(baseUrl: ClientConfig::BASE_URL_PRODUCTION); $client = Client::create(config: $config); ``` Authentication -------------- [](#authentication) ### OAuth 2.0 Password Grant [](#oauth-20-password-grant) The package uses industry-standard OAuth 2.0 password grant flow. You'll need: - Ecolet account email - Ecolet account password - OAuth `client_id` - OAuth `client_secret` ### Automatic Token Refresh [](#automatic-token-refresh) Tokens refresh automatically when expired. Or refresh manually: ``` $client->refreshToken(); ``` ### Access Current Token [](#access-current-token) ``` $token = $client->getToken(); $accessToken = $token?->accessToken; ``` ### Token Restoration [](#token-restoration) Already have a cached token? Restore it directly: ``` use Daika7ana\Ecolet\Auth\Token; $token = Token::fromArray($cachedTokenData); $client->setToken($token); ``` Supported Resources ------------------- [](#supported-resources) ### v1 Resources (General API) [](#v1-resources-general-api) - `users()->getMe()` โ€” Get authenticated user info - `services()->getServices()` โ€” List available services - `locations()->getCountries()` โ€” Get countries - `locations()->getCounties()` โ€” Get counties for country - `locations()->searchLocalities()` โ€” Search localities - `locations()->searchStreets()` โ€” Search streets - `locations()->searchStreetPostalCodes()` โ€” Get postal codes - `locations()->searchStreetsByPostalCode()` โ€” Search streets by postal code with validation metadata - `orders()->getOrder()` โ€” Retrieve order details - `orders()->deleteOrder()` โ€” Cancel an order - `orders()->downloadWaybill()` โ€” Get waybill document - `orders()->getStatusesForManyOrders()` โ€” Batch status check - `ordersToSend()->getOrderToSend()` โ€” Get order ready to send - `mapPoints()->getMapPoints()` โ€” Get pickup points ### v2 Resources (Add Parcel Operations) [](#v2-resources-add-parcel-operations) - `addParcel()->reloadForm()` โ€” Reload form with defaults - `addParcel()->sendOrder()` โ€” Submit and send order - `addParcel()->saveOrderToSend()` โ€” Save order for later ### API Versioning [](#api-versioning) - General resources and authentication use `/api/v1` - Add Parcel operations use `/api/v2` exclusively - v1 Add Parcel endpoints are intentionally excluded - Authorization-code OAuth flow is out of scope Framework Support ----------------- [](#framework-support) ### Zero Framework Dependencies [](#zero-framework-dependencies) This package works equally well everywhere: - ๐ŸŒ **Laravel** applications - ๐ŸŒ **Symfony** projects - ๐ŸŒ **Standalone PHP** applications - ๐ŸŒ **Microservices** - ๐ŸŒ Any **PHP 8.3+** environment ### Optional: HttpFoundation Bridge [](#optional-httpfoundation-bridge) Using Laravel or Symfony? Our optional `HttpFoundationBridge` provides seamless integration without breaking the PSR-based core API. ### Custom HTTP Client [](#custom-http-client) Need a custom HTTP client? Pass any PSR-18 implementation: ``` use Daika7ana\Ecolet\Client; use Daika7ana\Ecolet\Http\HttpClientInterface; /** @var HttpClientInterface $customClient */ $client = Client::create(httpClient: $customClient); ``` ### Custom Token Storage [](#custom-token-storage) Implement the `TokenStoreInterface` to persist tokens: ``` use Daika7ana\Ecolet\Client; use Daika7ana\Ecolet\Auth\TokenStoreInterface; /** @var TokenStoreInterface $tokenStore */ $client = Client::create(tokenStore: $tokenStore); ``` Testing ------- [](#testing) ### Run Static Analysis [](#run-static-analysis) ``` composer stan # or vendor/bin/phpstan --no-progress ``` PHPStan is configured via `phpstan.neon` and analyzes the `src/` directory at a strict level. ### Run Full Test Suite [](#run-full-test-suite) ``` composer test # or php vendor/bin/phpunit -c phpunit.xml ``` Pass PHPUnit arguments through Composer with `--`: ``` composer test -- --filter=AuthSmokeTest composer test -- tests/Unit/Resources/LocationsResourceTest.php ``` ### Run Specific Tests [](#run-specific-tests) ``` # Run only auth smoke test php vendor/bin/phpunit --filter=AuthSmokeTest -c phpunit.xml # Run the combined add-parcel workflow + waybill smoke test php vendor/bin/phpunit --filter=AddParcelWorkflowSmokeTest -c phpunit.xml # Run negative staging smoke tests php vendor/bin/phpunit --filter=AddParcelFailureSmokeTest -c phpunit.xml # Run all smoke tests php vendor/bin/phpunit --group=smoke -c phpunit.xml ``` ### Run The Same Checks As CI [](#run-the-same-checks-as-ci) ``` composer ci ``` Available Composer scripts: - `composer pint` runs Pint in test mode - `composer stan` runs PHPStan against `src/` - `composer test:unit` runs the unit test suite - `composer ci` runs the same local checks as CI Smoke tests hit the live staging API and require valid credentials in `phpunit.xml`. ### Test Environment Variables [](#test-environment-variables) Configure these in `phpunit.xml` to enable smoke tests: VariablePurpose`ECOLET_TEST_USERNAME`Test account email`ECOLET_TEST_PASSWORD`Test account password`ECOLET_TEST_CLIENT_ID`OAuth client ID`ECOLET_TEST_CLIENT_SECRET`OAuth client secret[See detailed testing docs โ†’](docs/TESTING.md) Documentation ------------- [](#documentation) Complete guides and references: GuidePurpose๐Ÿ“– [Quickstart](docs/QUICKSTART.md)Jump right in with working examples๐Ÿ”ง [Installation](docs/INSTALLATION.md)Detailed setup instructionsโš™๏ธ [Configuration](docs/CONFIGURATION.md)Environment setup and options๐Ÿ” [Authentication](docs/AUTHENTICATION.md)OAuth flow and token management๐Ÿ”— [Resources](docs/RESOURCES.md)Complete resource reference๐Ÿ“ฆ [DTOs](docs/DTOS.md)Data Transfer Objects and enumsโœ… [Testing](docs/TESTING.md)Unit and smoke test coverageโŒ [Errors](docs/ERRORS.md)Exception handling guide๐Ÿ“š [All Docs](docs/USAGE.md)Documentation index--- Made with โค๏ธ **Questions?** [Check the docs](docs/USAGE.md) or [open an issue](../../issues) ### Health Score 44 โ€” FairBetter than 90% of packages Maintenance93 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~14 days Total 6 Last Release 36d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/11703528?v=4)[Dan-Radu Pana](/maintainers/daika7ana)[@daika7ana](https://github.com/daika7ana) --- Top Contributors [![daika7ana](https://avatars.githubusercontent.com/u/11703528?v=4)](https://github.com/daika7ana "daika7ana (23 commits)") --- Tags apisdkpsr-18shippingcourierecolet ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/daika7ana-ecolet-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/daika7ana-ecolet-php-sdk/health.svg)](https://phpackages.com/packages/daika7ana-ecolet-php-sdk) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k16](/packages/tempest-framework)[aws/aws-sdk-php AWS SDK for PHP - Use Amazon Web Services in your PHP project 6.2k543.5M2.7k](/packages/aws-aws-sdk-php)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6942.5M425](/packages/drupal-core-recommended)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 585.6M600](/packages/shopware-core) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)