Installation

Requirements#

That is all. You do not need ext-calendar, ext-intl, ext-mbstring or a database. The three calendars are plain PHP, and the Umm al-Qura table ships inside the package.

Install with Composer#

composer require enaxon/rtly-kit

Make sure your entry script loads Composer's autoloader once:

<?php
require __DIR__.'/vendor/autoload.php';

The autoloader maps the RtlyKit\ namespace to the package's src/ directory. It also loads one file that defines the namespaced helpers (RtlyKit\jdate() and the others). That file defines no global function. See Helpers and globals for the opt-in short names.

Optional packages#

composer require nesbot/carbon          # Carbon macros: toJalali(), createFromJalali(), ...
composer require illuminate/support     # only in non-Laravel projects that want the Laravel pieces

Both switch on by themselves. The Carbon macros register when the autoloader finds Carbon. In a Laravel app, package auto-discovery finds the service provider and the Jalali facade, so you add nothing to config/app.php. If your deployment caches discovery, run php artisan package:discover after installing.

Install without PHP on your machine (Docker)#

If PHP and Composer are not installed, run them from the official images. From your project folder:

docker run --rm -v "$PWD":/app -w /app composer:2 require enaxon/rtly-kit
docker run --rm -v "$PWD":/app -w /app php:8.3-cli php quick.php

The first command installs the package into vendor/. The second runs a script like the one in Quick start with PHP 8.3. To work on the library itself, clone the repository and use its compose file:

docker compose -f tools/docker-compose.yml run --rm php composer install
docker compose -f tools/docker-compose.yml run --rm php composer test
docker compose -f tools/docker-compose.yml run --rm php php -r 'require "vendor/autoload.php"; echo RtlyKit\jdate("2026-03-21")->format("Y/m/d");'

Supported versions#

• PHP 8.2, 8.3, 8.4 and 8.5 (the CI matrix).
• Laravel 11, 12 and 13. Laravel 13 itself needs PHP 8.3 or newer.
• Carbon 3.
• Versioning. Before 1.0.0, a minor release may contain breaking changes. Each one is listed with migration steps in Upgrade. The compatibility promise and the list of internal classes are in API stability. Until 1.0.0, pin the minor version in composer.json (a tilde constraint such as ~0.2.0) and read the upgrade guide before you raise it.

Check the installation#

Create verify.php in your project root:

<?php
require __DIR__.'/vendor/autoload.php';

echo PHP_VERSION, "\n";
echo \RtlyKit\jdate('2026-03-21')->format('Y/m/d'), "\n";   // 1405/01/01

Run php verify.php. The last line must print 1405/01/01. A PHP version below 8.2 means the environment is too old. Two Composer commands also help:

composer show enaxon/rtly-kit            # installed version and metadata
composer check-platform-reqs          # checks PHP and extensions against every installed package

If something fails#

• Class "RtlyKit\..." not found or Call to undefined function RtlyKit\jdate(): vendor/autoload.php was not loaded, or the autoloader is stale. Run composer dump-autoload.
• Call to undefined function jdate() (no namespace): the short global names are opt-in. Use use function RtlyKit\jdate; or call \RtlyKit\Globals::register().
• Composer refuses to install and mentions the PHP version: install PHP 8.2 or newer.
• More cases: Troubleshooting and FAQ.

Uninstall#

1. Remove the package with composer remove enaxon/rtly-kit. This also rebuilds the autoloader.
2. Delete your own usages: the use RtlyKit\... and use function RtlyKit\... lines, calls to \RtlyKit\Globals::register() and catch blocks for RtlyKit\Exceptions\*. Search your code for RtlyKit to find them.
3. Carbon projects: the macros (toJalali, jformat, toHijri, toHebrew, createFromJalali, createFromHijri, createFromHebrew) go away with the package. Replace calls to them first.
4. Laravel projects: remove the national_code, sheba, bank_card, iran_mobile, mobile, postal_code and vehicle_plate rules from your form requests. Remove the JalaliCast from your models, any use of the Jalali facade, the published config/rtly-kit.php and any translation files you copied from the package. Then run php artisan optimize:clear. Data your app already wrote to the database stays as it is, so check how a cast stored it before you drop the cast.

The package installs nothing outside vendor/ apart from the Composer lock and autoload files, so there is nothing else to clean up.