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)

0.9.0alpha(1mo ago)01MITPHPPHP ^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 1w ago

READMEChangelogDependencies (5)Versions (2)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

34

—

LowBetter than 75% of packages

Maintenance92

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

40d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/68a857b4c6131eac0f6727f1ec3acd735423a431cbcd9404f5f52168da46bab1?d=identicon)[ux2dev](/maintainers/ux2dev)

---

Top Contributors

[![uxperience-hlaskov](https://avatars.githubusercontent.com/u/88424258?v=4)](https://github.com/uxperience-hlaskov "uxperience-hlaskov (22 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

[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/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.

61315.4M74](/packages/mollie-mollie-api-php)[kbsali/redmine-api

Redmine API client

4261.1M32](/packages/kbsali-redmine-api)[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.

35729.6k2](/packages/telnyx-telnyx-php)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.6M46](/packages/getbrevo-brevo-php)

PHPackages © 2026

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