README

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

• 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+ with json and curl extensions
• 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. To enable staging globally:

use Daika7ana\Ecolet\Config\ClientConfig;

ClientConfig::setTestMode(true);  // Enable staging

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

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

• 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.

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

Implement the TokenStoreInterface to persist tokens:

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 -c phpunit.xml

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

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

Configure these in phpunit.xml to enable smoke tests:

See detailed testing docs →

Documentation

Complete guides and references:

Made with ❤️

Questions? Check the docs or open an issue