daika7ana / fancourier-php-sdk
Typed PHP SDK for the FAN Courier API.
Requires
- php: >=8.3
- ext-json: *
- daika7ana/simple-collections: ^1.0
- guzzlehttp/guzzle: ^7.0 || ^8.0
- guzzlehttp/psr7: ^2.0 || ^3.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0 || ^2.0
Requires (Dev)
- laravel/pint: ^1.29
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.0 || ^13.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
FAN Courier PHP SDK
A modern, type-safe PHP SDK for the FAN Courier API
🚀 Framework-agnostic, PSR-18 native, fully typed with DTOs, and ready for domestic and export shipments.
Table of Contents
- Features
- Requirements
- Installation
- Quick Start
- Configuration
- Authentication
- Supported Resources
- Framework Support
- Testing
- Documentation
Features
Core Strengths
- ✅ Bearer Authentication —
POST /login, with automatic re-authentication of expired tokens - ✅ PSR-18 HTTP Client — Guzzle adapter by default, bring your own client if you prefer
- ✅ Fully Typed DTOs — AWB creation, tariffs, locations, PUDO points, orders and reports
- ✅ Enums for API Values — Services, AWB options, payment types, delivery modes and label formats
- ✅ Binary Response Helpers — AWB labels, ZIP confirmations and other non-JSON responses
- ✅ Paginated Results —
PaginatedResultwith aCollectionof DTOs - ✅ Static Analysis with PHPStan — Level 8 across
src/ - ✅ No Framework Coupling — No framework in
requireand no framework imports insrc/
Perfect For
- 🎯 Domestic and export shipments
- 🎯 Type-safe AWB, tariff, tracking and label workflows
- 🎯 PHP applications of any framework, microservices and standalone projects
Requirements
- PHP 8.3+ with
ext-json - PSR-7 / PSR-17 / PSR-18 compatible environment
- A FAN Courier client id and account credentials
Installation
Via Composer
composer require daika7ana/fancourier-php-sdk
Quick Start
Working with the FAN Courier API is straightforward:
use Daika7ana\FanCourier\Client; use Daika7ana\FanCourier\Config\ClientConfig; $client = Client::create(config: new ClientConfig(clientId: 7032158)); $client->authenticate(username: 'your-username', password: 'your-password'); $services = $client->services()->all(); foreach ($services as $service) { echo $service->id . ' ' . $service->name . PHP_EOL; }
Create a domestic AWB:
use Daika7ana\FanCourier\DTOs\Awb\InternalAwbRequest; use Daika7ana\FanCourier\DTOs\Awb\InternalShipment; use Daika7ana\FanCourier\DTOs\Awb\ShipmentInfo; use Daika7ana\FanCourier\DTOs\Common\Address; use Daika7ana\FanCourier\DTOs\Common\Contact; use Daika7ana\FanCourier\DTOs\Common\Dimensions; use Daika7ana\FanCourier\DTOs\Common\Packages; use Daika7ana\FanCourier\Enums\AwbOption; use Daika7ana\FanCourier\Enums\PaymentType; use Daika7ana\FanCourier\Enums\ServiceType; $result = $client->awb()->createInternal(new InternalAwbRequest(shipments: [ new InternalShipment( info: new ShipmentInfo( service: ServiceType::Standard, packages: new Packages(parcel: 1), weight: 1, payment: PaymentType::Recipient, dimensions: new Dimensions(10, 10, 10), options: [AwbOption::EPod], content: 'Books', ), recipient: new Contact( name: 'Alex Popescu', phone: '0723456789', address: new Address( county: 'Bucuresti', locality: 'Bucuresti', street: 'Splaiul Independentei', streetNo: '1', zipCode: '050091', ), ), ), ])); echo $result->first()?->awbNumber;
That's it! You have an authenticated client, typed services, and an AWB number.
Configuration
use Daika7ana\FanCourier\Client; use Daika7ana\FanCourier\Config\ClientConfig; $config = new ClientConfig( clientId: 7032158, language: 'ro', timeout: 30.0, ); $client = Client::create(config: $config);
Base URL
The client targets production at https://api.fancourier.ro by default. Only production is documented by FAN Courier; for a proxy or a local stub, pass a different baseUrl:
$config = new ClientConfig(baseUrl: 'http://localhost:8080');
Environment Variables
ClientConfig::fromEnvironment() is used by Client::create() and reads:
| Variable | Maps to |
|---|---|
FANCOURIER_CLIENT_ID |
clientId |
FANCOURIER_BASE_URL |
baseUrl |
FANCOURIER_USERNAME |
username |
FANCOURIER_PASSWORD |
password |
FANCOURIER_LANGUAGE |
language |
FANCOURIER_TIMEOUT |
timeout |
Client Id
Every account-scoped endpoint — AWB, tariffs, orders, service options and most reports — needs the client id. The SDK appends it automatically; calling one of those methods without a configured id raises ValidationException. Reference-data calls (services()->all(), locations(), pickupPoints(), branches() and the event catalogues) do not send it.
Timeouts
timeout sets the request timeout in seconds, including the login call. It defaults to null: the bundled GuzzleHttpClient then applies its own 30 s request / 10 s connect defaults, while a bare PSR-18 client keeps its own. 0 disables the cURL timeout.
ClientConfig::timeout is null by default. Precedence: the per-call argument → ClientConfig::timeout → the transport's own default (GuzzleHttpClient uses 30 s to respond and 10 s to connect unless you pass timeout:/connectTimeout:; an injected GuzzleClient keeps its own configuration). A bare PSR-18 client keeps its own timeout and cannot receive the per-call argument — passing one throws InvalidArgumentException; combining a bare client with a non-null ClientConfig::timeout also throws. Client::send() is @internal, so resource methods expose no timeout parameter.
Authentication
Bearer Tokens
$client->authenticate(username: 'your-username', password: 'your-password');
The API returns a Bearer token valid for 24 hours. The SDK stores it in memory and sends it on every request. When username and password are configured it also re-authenticates automatically when the token expires (60 second safety margin) or when the API answers 401, and retries a 403 only when it is not a business failure; without credentials a rejected token surfaces as UnexpectedStatusException.
Token Persistence
Persist and restore a token yourself:
use Daika7ana\FanCourier\Auth\Token; $token = $client->getToken(); // Token|null if ($token !== null) { $client->setToken(Token::fromArray([ // restore 'access_token' => $token->accessToken, 'expires_at' => $token->expiresAt?->format(DATE_ATOM), ])); }
Supported Resources
| Accessor | Methods |
|---|---|
services() |
all(), options(ServiceType|string) |
awb() |
createInternal(), createExternal(), delete(), label(), internalTariff(), externalTariff() |
locations() |
counties(), localities(), streets(), countries(), externalCounties(), externalLocalities() |
pickupPoints() |
all(PickupPointType|string), get(string $id) |
branches() |
all(?county, ?locality) |
orders() |
create(), delete(), report(), events(), tracking() |
reports() |
shippingSlip(), awbEvents(), trackAwbs(), bankTransfers(), confirmations() |
See docs/RESOURCES.md for endpoint-by-endpoint details.
Error Handling
use Daika7ana\FanCourier\Exceptions\ApiException; use Daika7ana\FanCourier\Exceptions\ValidationException; try { $client->awb()->createInternal($request); } catch (ApiException $e) { // HTTP 200 {"status":"fail"} — business rejection from FAN Courier echo $e->getMessage(); } catch (ValidationException $e) { // HTTP 422 — Laravel validation errors print_r($e->errors); }
All exceptions extend Daika7ana\FanCourier\Exceptions\FanCourierException.
Framework Support
Zero Framework Dependencies
The package keeps no framework in require and no framework imports in src/, so it works equally well in:
- 🌐 Laravel applications
- 🌐 Symfony projects
- 🌐 Standalone PHP applications
- 🌐 Microservices
- 🌐 Any PHP 8.3+ environment
Custom HTTP Client
Pass any PSR-18 client (auto-wrapped), or the bundled GuzzleHttpClient with your own Guzzle instance:
use Daika7ana\FanCourier\Client; use GuzzleHttp\Psr7\HttpFactory; $factory = new HttpFactory(); /** @var \Psr\Http\Client\ClientInterface $psr18 */ $client = Client::create( httpClient: $psr18, requestFactory: $factory, streamFactory: $factory, );
GuzzleHttpClient is the default when no client is supplied. A bare PSR-18 client keeps its own timeout, so a non-null ClientConfig::timeout alongside one throws InvalidArgumentException.
Testing
Run Static Analysis
composer stan
# or
vendor/bin/phpstan --no-progress
PHPStan is configured via phpstan.neon and analyzes the src/ directory at level 8.
Run Full Test Suite
composer test # or php vendor/bin/phpunit
Pass PHPUnit arguments through Composer with --:
composer test -- --filter=AwbResourceTest composer test -- tests/Unit/Resources
Run The Same Checks As CI
composer ci
Available Composer scripts:
composer pintruns Pint in test modecomposer stanruns PHPStan againstsrc/composer test:unitruns the unit test suitecomposer ciruns the same local checks as CI
Test Environment Variables
None. The suite is fully offline — no credentials, no network, no smoke suite, and no documented live sandbox. See docs/TESTING.md for the fake HTTP client and fixtures.
Documentation
Complete guides and references:
| Guide | Purpose |
|---|---|
| 📖 Quickstart | Jump right in with working examples |
| 🔧 Installation | Detailed setup instructions |
| ⚙️ Configuration | Environment setup and options |
| 🔐 Authentication | Bearer flow and token management |
| 🔗 Resources | Complete resource reference |
| 📦 DTOs | Data Transfer Objects and enums |
| ✅ Testing | Offline test suite and fixtures |
| ❌ Errors | Exception handling guide |
| 📚 All Docs | Everything under docs/ |
Third-party material
docs/RO_FANCourier_API_090126.pdf is FAN Courier's own API documentation,
included unmodified as a reference. It is not covered by this project's
license: FAN Courier owns the document, its content, and the sample credentials
in its examples. Those credentials come from FAN Courier, not from this
project. They do not grant API access, and nothing here authorizes their use —
use them only if you are entitled to, and only against systems you are
authorized to test. This project is not affiliated with or endorsed by FAN
Courier.
Made with ❤️
Questions? Check the docs or open an issue