PHPackages                             ux2dev/speedy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. ux2dev/speedy

ActiveLibrary[API Development](/categories/api)

ux2dev/speedy
=============

Framework-agnostic PHP SDK for Speedy courier (api.speedy.bg)

1.0.0(1mo ago)033MITPHPPHP ^8.2

Since Apr 30Pushed 1mo agoCompare

[ Source](https://github.com/ux2dev/speedy)[ Packagist](https://packagist.org/packages/ux2dev/speedy)[ RSS](/packages/ux2dev-speedy/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (10)Versions (3)Used By (0)

Speedy PHP SDK
==============

[](#speedy-php-sdk)

> **Warning:** Developer testing version of the library — use at your own risk.

Framework-agnostic PHP SDK for the [Speedy](https://api.speedy.bg/api/docs/) courier API at `https://api.speedy.bg/v1`. Covers all ten Speedy service groups (Shipment, Print, Track, Pickup, Location, Calculate, Client, Validation, Services, Payments) as resource methods that return typed Response DTOs. Works with plain PHP or Laravel.

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- JSON extension
- A PSR-18 HTTP client and PSR-17 request/stream factories (Guzzle provides both)

Installation
------------

[](#installation)

```
composer require ux2dev/speedy
```

Quick start — plain PHP
-----------------------

[](#quick-start--plain-php)

```
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Ux2Dev\Speedy\Config\SpeedyConfig;
use Ux2Dev\Speedy\Speedy;
use Ux2Dev\Speedy\Dto\Request\Shipment\CreateShipmentRequest;

$config = new SpeedyConfig(
    userName: 'your-username',
    password: 'your-password',
    language: 'EN',
);

$factory = new HttpFactory();
$speedy  = new Speedy($config, new Client(), $factory, $factory);

$response = $speedy->shipment()->create(new CreateShipmentRequest(
    ref1: 'ORDER-1234',
));

echo $response->id;
```

Quick start — Laravel
---------------------

[](#quick-start--laravel)

The package auto-registers `SpeedyServiceProvider` and a `Speedy` facade.

Publish the config:

```
php artisan vendor:publish --tag=speedy-config
```

Set credentials in `.env`:

```
SPEEDY_USERNAME=demo
SPEEDY_PASSWORD=secret
SPEEDY_LANGUAGE=EN
```

Use the facade:

```
use Ux2Dev\Speedy\Laravel\Facades\Speedy;
use Ux2Dev\Speedy\Dto\Request\Shipment\CreateShipmentRequest;

$response = Speedy::shipment()->create(new CreateShipmentRequest(ref1: 'ORDER-1234'));
```

### Multiple accounts

[](#multiple-accounts)

```
return [
    'default'  => 'main',
    'accounts' => [
        'main'   => ['user_name' => env('SPEEDY_USERNAME'),   'password' => env('SPEEDY_PASSWORD'),   'language' => 'EN'],
        'second' => ['user_name' => env('SPEEDY_USERNAME_2'), 'password' => env('SPEEDY_PASSWORD_2'), 'language' => 'BG'],
    ],
];
```

```
Speedy::account('second')->shipment()->create($req);
```

`account()` returns an immutable clone — the default stays untouched.

How the SDK is organised
------------------------

[](#how-the-sdk-is-organised)

LayerLocationPurposeConfig`Ux2Dev\Speedy\Config\SpeedyConfig`Base URL + credentials, validated, password redactedTransport`Ux2Dev\Speedy\Http\SpeedyTransport`PSR-18 dispatch, auth auto-injection, error mappingRequest DTOs`Ux2Dev\Speedy\Dto\Request\{Group}\*Request`Generated, `toArray()`Response DTOs`Ux2Dev\Speedy\Dto\Response\{Group}\*Response`Generated, `fromArray()`Model DTOs`Ux2Dev\Speedy\Dto\Model\*`Shared entities (Address, Office, Site, ...)Resources`Ux2Dev\Speedy\Resources\{Group}`Generated, one method per operationRoot client`Ux2Dev\Speedy\Speedy`AggregatorLaravel`Ux2Dev\Speedy\Laravel\*`Service Provider + multi-account Manager + FacadeGenerated from `bin/endpoints.json` (a hand-curated catalog of 45 operations) plus `bin/schemas/` (a snapshot of `https://api.speedy.bg/v1/schema`) by `bin/generate.php`.

Resources
---------

[](#resources)

10 generated resource groups, mirroring Speedy's service organisation:

```
shipment      print        track       pickup
location      calculate    clients     validation
services      payments

```

Every resource method takes a Request DTO plus optional `$language` and `$clientSystemId` overrides, and returns a typed Response DTO:

```
$speedy->shipment()->create($createShipmentRequest);
$speedy->shipment()->cancel($cancelShipmentRequest);
$speedy->location()->findOffice($findOfficeRequest);
$speedy->track()->track($trackRequest);
$speedy->print()->voucher($printVoucherRequest);
```

Print Service
-------------

[](#print-service)

Print endpoints currently follow Speedy's documented JSON envelope (`PrintVoucherResponse` carries the PDF as a `pdf` byte-array). When you need the binary path directly, the SDK exposes `Ux2Dev\Speedy\Http\PrintResult` with `body`, `contentType`, `filename`, plus `bytes()`, `saveTo($path)`, `isPdf()`, and `isZpl()` helpers.

Errors
------

[](#errors)

Successful return paths always carry a "good" Response DTO. When the API responds with a populated `error` field, the transport throws `Ux2Dev\Speedy\Exception\ApiException` with structured fields (`apiCode`, `apiMessage`, `context`, `errorId`, `component`, `httpStatus`). The raw response body is intentionally not retained on the exception — the structured fields cover every documented error attribute, and dropping the body avoids leaking PII or credentials into logs and traces.

ExceptionWhen`ConfigurationException`Invalid `SpeedyConfig` input or unknown Laravel account`TransportException`PSR-18 client failure (network, timeout)`InvalidResponseException`Empty body, malformed JSON, or unexpected envelope`ApiException`Speedy returned a non-null `error` fieldAll extend `SpeedyException`.

Regenerating the SDK
--------------------

[](#regenerating-the-sdk)

```
composer speedy:fetch-schemas    # snapshots /v1/schema into bin/schemas
composer speedy:generate         # rewrites src/Resources, src/Dto, and the Speedy/Facade method blocks
vendor/bin/pest                  # snapshot test catches drift
```

Testing
-------

[](#testing)

```
composer install
vendor/bin/pest
XDEBUG_MODE=coverage vendor/bin/pest --coverage --min=100
```

The suite mocks a PSR-18 client to exercise every resource method end-to-end.

License
-------

[](#license)

MIT

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance90

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~35 days

Total

2

Last Release

49d ago

Major Versions

0.9.0alpha → 1.0.02026-06-05

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/181749481?v=4)[ux2dev](/maintainers/ux2dev)[@ux2dev](https://github.com/ux2dev)

---

Top Contributors

[![uxperience-hlaskov](https://avatars.githubusercontent.com/u/88424258?v=4)](https://github.com/uxperience-hlaskov "uxperience-hlaskov (23 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/ux2dev-speedy/health.svg)

```
[![Health](https://phpackages.com/badges/ux2dev-speedy/health.svg)](https://phpackages.com/packages/ux2dev-speedy)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60316.0M89](/packages/mollie-mollie-api-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.9M50](/packages/getbrevo-brevo-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M425](/packages/drupal-core-recommended)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36789.4k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)