README

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

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:

• English Documentation
• مستندات فارسی

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