daika7ana / dragonstar-php-sdk
Typed PHP SDK for the Dragon Star 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
This package is auto-updated.
Last update: 2026-11-20 15:22:21 UTC
README
Dragon Star PHP SDK
A modern, type-safe PHP SDK for the Dragon Star courier API
🚀 Framework-agnostic, API-key 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
- ✅ API Key Authentication — Sent as
X-Api-Keywhen a key is configured - ✅ PSR-18 HTTP Client — Pluggable, with a Guzzle adapter by default
- ✅ Fully Typed DTOs — Requests and responses, no vague arrays required
- ✅ Every v1 Endpoint — AWB creation, quotes, tracking, labels, pickups, manifests, nomenclature
- ✅ RFC 9457 Errors — One
ApiExceptionexposing the stablecode, field errors andRetry-After - ✅ Typed Tracking — Status enum, events, locations and return legs
- ✅ Binary Documents — PDF/ZPL labels and manifest PDFs with filename helpers
- ✅ Iterable Collections —
count,first,last,get,filter,map,pluck, … - ✅ Static Analysis with PHPStan — Level 8 over
src/ - ✅ Comprehensive Tests — Unit suite plus an opt-in live smoke test
Perfect For
- 🎯 Laravel applications or any PHP framework
- 🎯 Microservices and standalone PHP projects
- 🎯 Order fulfilment and AWB printing 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/dragonstar-php-sdk
Quick Start
Working with the Dragon Star API is straightforward:
use Daika7ana\DragonStar\Client; use Daika7ana\DragonStar\DTOs\Awb\AwbQuoteRequest; use Daika7ana\DragonStar\Enums\ShipmentType; $client = Client::create(apiKey: 'your-api-key'); $quote = $client->awb()->quote(new AwbQuoteRequest( shipmentType: ShipmentType::Parcel, recipientCounty: 'Cluj', recipientCity: 'Cluj-Napoca', weight: 5, )); echo $quote->totalAmount; // RON, VAT included
Create the shipment and download its label:
use Daika7ana\DragonStar\DTOs\Awb\AwbCreateRequest; $created = $client->awb()->create(new AwbCreateRequest( shipmentType: ShipmentType::Parcel, recipientName: 'Ion Popescu', recipientAddress: 'Str. Memorandumului nr. 28', recipientCounty: 'Cluj', recipientCity: 'Cluj-Napoca', weight: 5, pieces: 1, codAmount: 150, notes: 'Fragil', )); $label = $client->awb()->label($created->awb); file_put_contents($label->getFilename('awb.pdf'), $label->getContents());
That's it! You've got a client ready to quote, create and label shipments.
Configuration
Base URL
The client targets production by default:
use Daika7ana\DragonStar\Config\ClientConfig; ClientConfig::BASE_URL_PRODUCTION; // https://api.curierdragonstar.ro
For a proxy or a local mock, set the URL explicitly:
$config = new ClientConfig(baseUrl: 'https://proxy.example.com'); $client = Client::create(config: $config);
API Key
$client = Client::create(apiKey: 'your-api-key'); // or, later $client->setApiKey('another-key');
Keep the key out of source control and read it from the environment instead, for example getenv('DRAGONSTAR_API_KEY') — see Authentication.
Request Timeouts
Requests time out after 30 seconds by default with the bundled transport (10
seconds to connect); an injected GuzzleClient keeps its own timeout
configuration. Override the default with new ClientConfig(timeout: 60.0) or
withTimeout(), and leave timeout at null to defer to the HTTP client.
Precedence, highest first: a per-call override, then ClientConfig::timeout,
then the transport constructor arguments, then the bundled 30.0/10.0 defaults. A
per-call override always wins:
$client->send($request, 2.5);
Authentication
Each request carries the API key in the X-Api-Key header. Keys are issued in
the Dragon Star account under Settings → Access API, and each key is bound
to the public IP addresses it may be used from — a request from anywhere else
returns 403 with code: ip_not_allowed.
$client = Client::create(apiKey: getenv('DRAGONSTAR_API_KEY'));
The API also accepts the key as Authorization: Bearer <key>; this SDK always
uses X-Api-Key.
Rate Limits
Limits apply per API key and per route:
| Method | Per second | Per minute |
|---|---|---|
GET |
40 | 1200 |
| Everything else | 20 | 600 |
Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. On
exceeding a limit the API answers 429 with code: rate_limit_exceeded and a
Retry-After header, exposed as $exception->retryAfter.
Supported Resources
awb() — Shipments
create()— Create an AWBcreateForBranch()— Create an AWB for a branch (pcId)quote()— Estimate a shipment's costquoteForBranch()— Estimate for a branchtrack()— Track one AWBtrackMany()— Track up to 100 AWBs, withnotFounddelete()— Delete an AWB while still deletablereturnLegs()— Return legs linked to an AWBlabel()— Label in the account's configured formatlabelAs()— Label asA4orA6zplLabel()— Raw ZPL for one piece
pickups() — Pickups
create()— Order a pickupcreateForBranch()— Order a pickup for a branchcancel()— Cancel a pickup
manifests() — Manifests
create()— Close shipments into a new manifestpdf()— Download the manifest PDF
directory() — Nomenclature
counties()— Counties keyed by codelocalities()— Localities of a countylocalitiesWithDistances()— Localities with distance in kmbranches()— Branches the master account may ship for
Framework Support
Zero Framework Dependencies
This package works equally well everywhere:
- 🌐 Laravel applications
- 🌐 Symfony projects
- 🌐 Standalone PHP applications
- 🌐 Microservices
No framework is required by require.
Custom HTTP Client
Pass any PSR-18 client (auto-wrapped), or an HttpClientInterface
implementation if you need per-request timeouts. PSR-17 factories may be
injected alongside the client:
use Daika7ana\DragonStar\Client; /** @var \Psr\Http\Client\ClientInterface $psr18 */ /** @var \Psr\Http\Message\RequestFactoryInterface $requestFactory */ /** @var \Psr\Http\Message\StreamFactoryInterface $streamFactory */ $client = Client::create( httpClient: $psr18, requestFactory: $requestFactory, streamFactory: $streamFactory, apiKey: 'your-api-key', );
HttpClientInterface::sendRequest() takes an optional timeout argument, so
implementations can honour per-request timeouts. A bare PSR-18 client keeps its
own timeout: combining it with a non-null ClientConfig::timeout or a per-call
timeout throws InvalidArgumentException.
Testing
Run Static Analysis
composer stan # PHPStan level 8 over src/
PHPStan is configured to analyze the src/ directory at level 8.
Run Full Test Suite
composer test # every test, smoke included composer test:unit # tests/Unit only
Run The Same Checks As CI
composer ci # validate -> pint -> stan -> test:unit (exactly what CI runs) composer pint # style check only — never fixes
Test Environment Variables
The live smoke test (tests/Smoke/ClientSmokeTest.php) skips itself unless
DRAGONSTAR_TEST_API_KEY is set. Copy phpunit.xml.dist to phpunit.xml and
fill it in to run it; the key's IP allowlist must include the machine.
| Variable | Purpose |
|---|---|
DRAGONSTAR_TEST_API_KEY |
Live API key for the smoke test |
Documentation
Complete guides and references:
| Guide | Purpose |
|---|---|
| 📖 Quickstart | Jump right in with working examples |
| 🔧 Installation | Detailed setup instructions |
| ⚙️ Configuration | Environment setup and options |
| 🔐 Authentication | API keys, IP allowlists and rate limits |
| 🔗 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