README

A modern, type-safe PHP SDK for the Ecolet Courier API

🚀 Framework-agnostic, OAuth-powered, fully typed with DTOs, and production-ready.

Features
Requirements
Installation
Quick Start
Configuration
Authentication
Supported Resources
Framework Support
Testing
Documentation

Features

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

🎯 Laravel applications or any PHP framework
🎯 Microservices and standalone PHP projects
🎯 Type-safe courier management workflows
🎯 Production deployments with full test coverage

Requirements

PHP 8.3+
PSR-7 / PSR-17 / PSR-18 compatible environment

Installation

Via Composer

composer require daika7ana/ecolet-php-sdk

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

Base URL & Environment

By default, the client runs against production. For tests, you can switch the default to staging with a global flag:

use Daika7ana\Ecolet\Config\ClientConfig;

ClientConfig::setTestMode(true);  // staging for every client created afterwards; tests only

setTestMode() changes a static flag, so every client created later in the same process uses staging. Application code should use the explicit base URL below instead.

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);

Request Timeouts

Set a default timeout via new ClientConfig(timeout: 30.0) or withTimeout(), or override it per request with $client->send($request, 2.5).

Authentication

OAuth 2.0 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

Tokens refresh automatically when expired. Or refresh manually:

$client->refreshToken();

Access Current Token

$token = $client->getToken();
$accessToken = $token?->accessToken;

Token Restoration

Already have a cached token? Restore it directly:

use Daika7ana\Ecolet\Auth\Token;

$token = Token::fromArray($cachedTokenData);
$client->setToken($token);

Supported Resources

v1 Resources (General API)

users()->getMe() — Get authenticated user info
addressBook()->getAddresses() — List saved addresses (paginated, optional search)
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
mapPoints()->streamMapPoints() — Stream pickup points one at a time
mapPoints()->getMapPointsRaw() — Get the undecoded map-points response

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

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

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

Using Laravel or Symfony? Our optional HttpFoundationBridge provides seamless integration without breaking the PSR-based core API. It needs Symfony's HttpFoundation, which this package does not install: composer require symfony/http-foundation.

Custom HTTP Client

Need a custom HTTP client? Pass a client implementing HttpClientInterface (the bundled GuzzleHttpClient or your own):

use Daika7ana\Ecolet\Client;
use Daika7ana\Ecolet\Http\HttpClientInterface;

/** @var HttpClientInterface $customClient */
$client = Client::create(httpClient: $customClient);

HttpClientInterface::sendRequest() takes an optional timeout argument, so custom clients can honour per-request timeouts.

Custom Token Storage

By default the token lives in memory only. Under PHP-FPM a new Client is built for each request, so the token is lost and the password grant runs again. Pass a store that outlives the request (session, cache, database) to avoid one login per request:

use Daika7ana\Ecolet\Client;
use Daika7ana\Ecolet\Auth\TokenStoreInterface;

/** @var TokenStoreInterface $tokenStore */
$client = Client::create(tokenStore: $tokenStore);

Testing

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

composer test
# or
php vendor/bin/phpunit

Pass PHPUnit arguments through Composer with --:

composer test -- --filter=AuthSmokeTest
composer test -- tests/Unit/Resources/LocationsResourceTest.php

Run Specific Tests

# Run only auth smoke test
php vendor/bin/phpunit --filter=AuthSmokeTest

# Run the combined add-parcel workflow + waybill smoke test
php vendor/bin/phpunit --filter=AddParcelWorkflowSmokeTest

# Run negative staging smoke tests
php vendor/bin/phpunit --filter=AddParcelFailureSmokeTest

# Run all smoke tests
php vendor/bin/phpunit --group=smoke

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. Run cp phpunit.xml.dist phpunit.xml first, then fill in the values.

Test Environment Variables

Configure these in phpunit.xml to enable smoke tests:

Variable	Purpose
`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 →

Documentation

Complete guides and references:

Guide	Purpose
📖 Quickstart	Jump right in with working examples
🔧 Installation	Detailed setup instructions
⚙️ Configuration	Environment setup and options
🔐 Authentication	OAuth flow and token management
🔗 Resources	Complete resource reference
📦 DTOs	Data Transfer Objects and enums
✅ Testing	Unit and smoke test coverage
❌ Errors	Exception handling guide
📚 All Docs	Documentation index

Made with ❤️

Questions? Check the docs or open an issue

daika7ana / ecolet-php-sdk

Package info

Security

Statistics