mohamedhekal/shipbridge

Unified Laravel shipping abstraction for create, track, label, return, and exchange across carriers

v0.1.1 2026-07-16 15:37 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.18
• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Mohamed Hekal

• php
• ecommerce
• fulfillment
• laravel
• shipping
• tracking
• logistics
• courier
• labels
• returns
• laravel-package
• carriers
• shipping-api

Published on Packagist.org on 2026-07-16 15:37 UTC

README

Search terms: laravel, shipping, carriers, tracking, labels, returns, logistics, ecommerce, php, laravel-package, courier, fulfillment.

Unified Laravel shipping abstraction: create, track, label, return, and exchange across carrier drivers with normalized statuses.

شرح عربي بسيط جدًا: docs/GUIDE_AR.md

Installation

composer require mohamedhekal/shipbridge
php artisan vendor:publish --tag=shipbridge-config

Add the carrier you need (separate package per company):

composer require mohamedhekal/shipbridge-bosta
# or: shipbridge-aramex / shipbridge-fedex / …

Carrier packages

All carrier drivers below ship as ^0.2 with real vendor APIs (not scaffolds).

Carrier	Package	Region	Integration
Bosta	mohamedhekal/shipbridge-bosta	Egypt	Business API v2
Aramex	mohamedhekal/shipbridge-aramex	MENA / Global	Shipping SOAP V2
Mylerz	mohamedhekal/shipbridge-mylerz	Egypt / MENA	Integration API
Turbo	mohamedhekal/shipbridge-turbo	Egypt	External API
J&T Express	mohamedhekal/shipbridge-jtexpress	Egypt	Open Platform
SMSA	mohamedhekal/shipbridge-smsa	KSA / GCC	SECOM SOAP
FedEx	mohamedhekal/shipbridge-fedex	Global	REST Ship/Track
UPS	mohamedhekal/shipbridge-ups	Global	REST OAuth2
DHL Express	mohamedhekal/shipbridge-dhl	Global	MyDHL API
Egypt Post	mohamedhekal/shipbridge-egyptpost	Egypt	TrackTrace + partner gateway

composer require mohamedhekal/shipbridge-bosta:^0.2

Quick start

use Hekal\ShipBridge\Facades\ShipBridge;
use Hekal\ShipBridge\DTOs\Address;
use Hekal\ShipBridge\DTOs\CreateShipmentRequest;
use Hekal\ShipBridge\DTOs\Parcel;

$shipment = ShipBridge::driver('bosta')->createShipment(new CreateShipmentRequest(
    origin: new Address('Warehouse', '1 Industrial Rd', 'Cairo', 'EG'),
    destination: new Address('Customer', '12 Nile St', 'Giza', 'EG'),
    parcels: [new Parcel(weightKg: 1.2)],
    reference: 'ORD-42',
));

$label = ShipBridge::driver('bosta')->label($shipment->id);
$tracking = ShipBridge::driver('bosta')->track($shipment->trackingNumber);

Default built-in driver is fake (in-memory). Use http for a generic JSON carrier, or install a carrier package above.

Returns & exchanges

First-class methods—not afterthoughts:

ShipBridge::createReturn(new ReturnShipmentRequest(...));
ShipBridge::createExchange(new ExchangeShipmentRequest(...));

Status normalization

Carrier strings (OFD, shipped, …) map to ShipmentStatus via config/shipbridge.php (status_map + status_aliases). Unknown values become exception rather than throwing, so webhooks stay resilient.

Limitations

• Each carrier still needs live credentials from that company (sandbox vs production differs).
• Labels are opaque bytes/URLs from the driver; no PDF layout engine.
• Rate shopping and live pickup calendars are out of scope.
• Egypt Post has no public create API (Wassalha); create needs a contracted partner gateway — tracking works via official TrackTrace.

Testing

composer install && composer test

License

MIT