Browse project documentation
Ersal
A unified, type-safe PHP library for Iranian shipping and courier services.
Documentation: English | فارسی
What is Ersal?
Ersal (ارسال, “shipping” in Farsi) is an omni-carrier PHP library that gives you a single, consistent API across major Iranian shipping providers — from national postal services to private couriers and on-demand urban delivery. Write your shipping logic once, swap the carrier with one line of config.
Why Ersal?
- Minimal dependencies — one internal Composer package (
eram/abzar, Persian/Iranian utilities) plus the standard PHP extensionsext-curl,ext-json,ext-openssl,ext-soap. No Guzzle, no framework coupling, no third-party supply-chain risk. - One interface, every carrier —
quote()→createShipment()→track()→cancel(). Same flow whether it’s Iran Post or Alopeyk. - Type-safe value objects —
Address,Parcel,ShipmentStatus,TrackingEvent— no stringly-typed dictionaries. - Integer units everywhere — grams for weight, millimeters for dimensions, Rials for money. Zero floating-point drift.
- Framework-agnostic — works with Laravel, Symfony, or plain PHP. Plug in your own HTTP client, logger, or event dispatcher.
- Fully tested — unit tests for every provider, PHPStan static analysis, PER-CS2 code style.
Install
composer require eram/ersalSupported Carriers
| Alias | Carrier | Protocol | Capabilities | Docs |
|---|---|---|---|---|
post | Iran Post (شرکت پست) | SOAP + REST | Label, Branches | Guide |
tipax | Tipax (تیپاکس) | REST | Label, Pickup, Branches, COD | Guide |
chapar | Chapar Express | REST | Label, Pickup, COD | Guide |
mahex | Mahex (ماهکس) | REST | Pickup, COD | Guide |
amadast | Amadast (آمادست) | REST | — | Guide |
paygan | Paygan (پایگان) | REST | COD | Guide |
alopeyk | Alopeyk (الوپیک) | REST | Pickup | Guide |
Quick Start
The flow is always: quote → book → track → (optionally) cancel.
See the Getting Started guide for a complete walkthrough with code examples.
Documentation
Full documentation with API reference, cookbook, per-carrier guides, and more:
About Eram
Eram is a small engineering team building open-source developer tools for the Persian ecosystem. Our projects — pardakht, ersal, daynum, persian-kit — solve the everyday problems that Iranian developers run into: payment integration, shipping, calendar conversion, and string/number localization. Everything we ship is MIT-licensed, zero-dependency where possible, and built to be boring infrastructure you never have to think about.