README

A unified, type-safe PHP library for Iranian shipping and courier services.

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 extensions ext-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/ersal

Supported 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.

License

MIT

eram / ersal

Maintainers

Package info

Statistics

Security