Download the PHP package daika7ana/ecolet-php-sdk without Composer

Ecolet PHP SDK

🚀 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

Quick Start

Working with the Ecolet API is straightforward:

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:

Explicit Base URL

For explicit control without global state:

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:

Access Current Token

Token Restoration

Already have a cached token? Restore it directly:

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:

Custom Token Storage

Implement the TokenStoreInterface to persist tokens:

Testing

Run Static Analysis

PHPStan is configured via phpstan.neon and analyzes the src/ directory at a strict level.

Run Full Test Suite

Pass PHPUnit arguments through Composer with --:

Run Specific Tests

Run The Same Checks As 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: