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 / shipbridge-mng / …

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
MNG Kargo	`mohamedhekal/shipbridge-mng`	Turkey	ApiZone REST (DHL eCommerce TR)
HepsiJet	`mohamedhekal/shipbridge-hepsijet`	Turkey	Integration REST
Yurtiçi Kargo	`mohamedhekal/shipbridge-yurtici`	Turkey	ShippingOrder SOAP
Aras Kargo	`mohamedhekal/shipbridge-aras`	Turkey	CustomerWS SOAP
Sürat Kargo	`mohamedhekal/shipbridge-surat`	Turkey	WebServices SOAP
PTT Kargo	`mohamedhekal/shipbridge-ptt`	Turkey	PttVeriYukleme SOAP

composer require mohamedhekal/shipbridge-bosta:^0.2
# Turkey example:
composer require mohamedhekal/shipbridge-mng:^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

mohamedmohamedhekal / shipbridge

Maintainers

Package info

Statistics

Security