ErsalPHP0.2 · Beta

Your order.
Its next stop.

Add Iranian shipping services to your PHP application. Quote, book and track through a shared API, with clear parcel data and carrier-specific capabilities.

Start with Ersal Follow a parcel

composer require eram/ersal:^0.2@beta

A SHIPMENT IN YOUR APPDEMO-1042

FromTehran

ToShiraz

One shared shipment modelShipmentInterface

BEFORE THE PARCEL LEAVES

Same weight. Different space.

Recorded PHP examples

Actual weight1,500 g

FROM THE PARCEL OBJECT

1,500grams

chargeableWeightGrams()

Here, the actual weight is greater than the volumetric weight.

Actual weight: 1,500 g
Volumetric weight: 1,200 g

See the PHP

use Eram\Ersal\Address\Parcel;

$parcel = new Parcel(
    weightGrams: 1500,
    lengthMm: 300,
    widthMm: 200,
    heightMm: 100,
);

$parcel->volumetricWeightGrams(); // 1200
$parcel->chargeableWeightGrams(); // 1500

FROM THE PARCEL OBJECT

7,200grams

chargeableWeightGrams()

The box is still 1.5 kg, but its volume produces a larger calculated weight.

Actual weight: 1,500 g
Volumetric weight: 7,200 g

See the PHP

use Eram\Ersal\Address\Parcel;

$parcel = new Parcel(
    weightGrams: 1500,
    lengthMm: 400,
    widthMm: 300,
    heightMm: 300,
);

$parcel->volumetricWeightGrams(); // 7200
$parcel->chargeableWeightGrams(); // 7200

Calculated by Ersal using its fixed volumetric divisor of 5000. This illustrates the Parcel helper, not a carrier price or guaranteed billing weight. Confirm your carrier’s rules. The buttons reveal recorded PHP output.

FROM CHECKOUT TO TRACKING

A shipment your app can follow.

Tipax adapter · simulated responses

Sample quote85,000 Toman

A simulated standard-service quote. This is not a current Tipax rate.

Code for this step

use Eram\Ersal\Request\QuoteRequest;

$quotes = $provider->quote(new QuoteRequest(
    origin: $origin,
    destination: $destination,
    parcel: $parcel,
));

$quotes[0]->cost->inToman(); // 85000 (fixture)

Sample tracking codeDEMO-1042

Store the shipment ID and provider with your order. Booking is confirmed; delivery is still ahead.

booked

Code for this step

use Eram\Ersal\Request\BookingRequest;

$shipment = $provider->createShipment(new BookingRequest(
    origin: $origin,
    destination: $destination,
    parcel: $parcel,
    orderId: 'DEMO-1042',
    serviceLevel: $quotes[0]->serviceLevel,
    quoteId: $quotes[0]->quoteId,
));

$shipment->getTrackingCode(); // 'DEMO-1042'

Sample tracking history

Bookedbooked
Picked uppicked_up
In transitin_transit

The response “on_the_way” becomes in_transit. Call track() to fetch a new snapshot; this is not a live tracking feed.

Code for this step

$tracked = $provider->track($shipment->getId());

$tracked->getStatus()->value; // 'in_transit'

foreach ($tracked->getHistory() as $event) {
    $event->at;
    $event->status->value;
    $event->raw; // original carrier event
}

Set up the provider and addresses

Configure your carrier account on the server. The steps above share these objects; real requests need valid recipient details and your own token.

use Eram\Ersal\Ersal;
use Eram\Ersal\Provider\Tipax\TipaxConfig;
use Eram\Ersal\Address\{Address, Parcel};

$provider = (new Ersal())->create('tipax',
    new TipaxConfig(token: $yourToken)
);

// Replace these sample addresses with real order details.
$origin = new Address(
    'Demo', 'Shop', '09000000000',
    'تهران', 'تهران', 'نشانی نمونه'
);
$destination = new Address(
    'Demo', 'Recipient', '09000000000',
    'فارس', 'شیراز', 'نشانی نمونه'
);
$parcel = new Parcel(
    weightGrams: 1500,
    lengthMm: 300, widthMm: 200, heightMm: 100,
);

Recorded with Ersal 0.2.0-beta.2 and an in-memory HTTP transport. Prices, addresses and tracking data are fixtures. No carrier is contacted and no shipment is booked on this page.

SEVEN ADAPTERS, DIFFERENT CAPABILITIES

Find the features your order needs.

Iran Post

post

Shipping label
Branches

Tipax

tipax

Shipping label
Pickup
Branches
Cash on delivery

Chapar

chapar

Shipping label
Pickup
Cash on delivery

Mahex

mahex

Pickup
Cash on delivery

Amadast

amadast

Core shipping methods

Paygan

paygan

Cash on delivery

Alopeyk

alopeyk

Pickup

Capabilities describe interfaces implemented in this library release, not a guarantee about a carrier account or current API access. Check the provider guide and test against your contracted service.

Units you can read in the code.

Use integer grams and millimeters for parcels, and Amount for money. Keep addresses and parcels in typed objects.

Addresses and parcels

Bring your own infrastructure.

Inject an HTTP client, logger or event dispatcher. Use the library in plain PHP or your existing framework.

HTTP and logging

Keep tracking on your schedule.

Your application stores shipments and schedules polling. Ersal returns the status and history; webhook parsing is not built in.

Tracking guide

Start with one parcel.

Install the beta, configure one carrier, and test a complete shipping flow with your account before using it for customer orders.

Read the guide GitHub

Runtime: PHP 8.1+
Extensions: curl · json · openssl · soap
Dependency: eram/abzar
License: MIT