enaxon/rtly-kit

RTLY-Kit

The Persian and Arabic RTL toolkit for PHP

Jalali, Hijri and Hebrew calendars, Iranian validators, Persian and Arabic numbers and text, holidays and prayer times in one typed, immutable PHP library. Carbon and Laravel integrations are optional.

Quick start All guides Repository on GitHub ↗

Needs only PHP 8.2 or newer. MIT licensed.

Install

Install with Composer and use it right away. There is no config file and no publish step.

composer require enaxon/rtly-kit

The 30-second example

use function RtlyKit\{jdate, to_persian, is_national_code};

echo jdate('2026-03-21')->format('l j F Y');   // شنبه 1 فروردین 1405
echo to_persian(1405);                         // ۱۴۰۵
var_dump(is_national_code('0499370899'));      // bool(true)

What you can do

Each item links to its guide.

At a glance

These numbers are counted from the code when the site is built.

3calendars
6validators
27helper functions
6prayer-time methods
3validation message languages
29guides

What we checked

The Umm al-Qura table, the official holiday dates and the prayer times were compared with official sources, and the data tables were built from at least two sources each. The accuracy and data page says what was compared and when.

Accuracy and data →

Guides by topic

Start from any topic. Each list runs from the simple to the reference.

Getting started

Install and run your first example.

Quick start

Install RTLY-Kit with Composer. In about five minutes you will convert a Jalali date, check an Iranian national code and catch your first library exception.

Installation

Requirements, installation with Composer or Docker, optional Carbon and Laravel support, supported versions, how to check the install and how to remove the package.

Calendars

Jalali, Hijri and Hebrew: create, format, compare and convert.

Jalali calendar

The immutable Jalali (Persian, Solar Hijri) date class. Create and parse dates, format them with PHP date tokens, shift and snap them, compare them and measure the gap, with the exact year range and error behaviour.

Hijri calendar

The immutable Hijri (Islamic) date class with the Umm al-Qura month table and an arithmetic Tabular variant. Create, parse and format dates in Arabic, Persian or English, shift them, compare them and measure the gap.

Hebrew calendar

The immutable Hebrew (Jewish) date class with ordinal month numbers, Adar I and Adar II in leap years, and month names in English, Hebrew and Persian. Create, parse, format, shift and measure dates.

Convert and compare dates

The shared CalendarDate contract of Jalali, Hijri and Hebrew. How to convert a date between calendars, and how comparing and measuring works across calendars and time zones.

Carbon macros

Optional Carbon support. Turn any Carbon instance into a Jalali, Hijri or Hebrew date, and create Carbon dates from calendar parts. The page lists every macro with its return type and errors.

Validation

National code, Sheba, bank card, mobile, postal code and plate, with structured results.

Validators overview

How the six Iranian validators work. The shared Validator contract, the Result object, stable error keys, input cleaning and size limits.

National code

Validate Iranian national codes (کد ملی) with the mod-11 check digit, accept Persian and Arabic digits, and read the place-of-issue hint safely.

Sheba and bank card

Validate Sheba (IBAN) numbers with ISO 7064 mod-97-10 and bank card numbers with the Luhn checksum, and look up the issuing bank. The page says where the bank data comes from.

Mobile, postal code and plate

Validate Iranian mobile numbers in every common input form, postal codes and vehicle plates, with operator hints, an allocation flag and parsing.

Numbers and text

Digits, thousands separators, number to words, normalization and detection.

Digits and number formatting

Convert between English, Persian and Arabic-Indic digits, format numbers with Persian separators and build Persian ordinals. Every cap and edge case is listed.

Number to words

Spell integers out in Persian (up to 10^21) and Arabic (up to 10^27), and read Persian number words back into numbers with fromWords().

Arabic number words

Spell numbers in Modern Standard Arabic with the right gender, case and vowel marks, up to 10^27, and write the ordinals from 1 to 99. Every option is shown with real output.

Text tools

Normalize Persian and Arabic text, repair half-spaces, detect language and direction, and build URL-safe slugs. Each tool is described with its exact behavior and edge cases.

Holidays and prayer times

Iranian public holidays and prayer time calculation.

Iranian holidays

Look up official Iranian public holidays for any Jalali date, list a whole year, and find business days. Official dates are used for 1394 to 1405, and other years are estimated.

Holiday calendar

Use official Iranian holiday dates, see where each date comes from, and fix moon-sighting differences with your own offsets, month starts and extra or removed days.

Prayer times

Compute Fajr, sunrise, Dhuhr, Asr, Maghrib and Isha for any place with six calculation methods, high-latitude rules and manual tuning. The page lists what each method was checked against.

Laravel

Service provider, validation rules, facade and Eloquent cast.

Laravel setup

How RTLY-Kit plugs into Laravel. Package auto-discovery, what the service provider registers, the Jalali facade, the optional config file and the fa, en and ar validation messages.

Validation rules and Eloquent cast

Use the Iranian validation rules in Laravel forms, store Jalali dates in Eloquent models with JalaliCast, and show them in Blade.

Reference

Helpers, errors, API stability, data accuracy, limits and upgrading.