شروع سریع

در این صفحه چه می‌کنید

بسته را نصب می‌کنید، یک تاریخ جلالی چاپ می‌کنید، یک اعتبارسنجی اجرا می‌کنید و یک خطای کتابخانه را می‌گیرید. همه‌چیز با PHP ساده کار می‌کند. فریم‌ورک، فایل تنظیمات و بستهٔ اضافه لازم نیست.

پیش‌نیاز. PHP نسخهٔ ۸٫۲ یا بالاتر و Composer (opens in a new tab). اگر هیچ‌کدام را ندارید، راه Docker را در نصب ببینید.

۱. نصب

composer require tsi/rtly-kit

Composer بسته را نصب می‌کند و فایل vendor/autoload.php را می‌سازد. RTLY-Kit بستهٔ اجباری دیگری نمی‌خواهد. اگر Carbon یا Laravel در پروژه باشد، بخش‌های مربوط به آن‌ها خودکار روشن می‌شوند. بیشتر در نصب.

۲. اولین تاریخ

فایل quick.php را کنار پوشهٔ vendor/ بسازید:

<?php
declare(strict_types=1);

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

use function RtlyKit\hdate;
use function RtlyKit\jdate;

echo jdate('2026-03-21')->format('l j F Y'), "\n";   // شنبه 1 فروردین 1405
echo hdate('2026-03-21')->format('j F Y', 'en'), "\n"; // 2 Shawwal 1447

با php quick.php اجرا کنید. خط اول تاریخ جلالی ۲۱ مارس ۲۰۲۶ را چاپ می‌کند. این روز نوروز ۱۴۰۵ است. خط دوم همان روز را در تقویم هجری نشان می‌دهد.

دو نکته:

• توابع کمکی در فضای‌نام RtlyKit هستند و با use function وارد می‌شوند. پس با تابع‌های خودتان یا بسته‌های دیگر تداخل ندارند.
• رشتهٔ '2026-03-21' میلادی خوانده می‌شود. رشته‌ای مثل '1405/01/01' (سال کمتر از ۱۷۰۰ با شکل Y/m/d ) جلالی خوانده می‌شود. جزئیات در رشته در make() .

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

تابع jdate() یک شیء Jalali می‌دهد. hdate() یک Hijri و hebrew_date() یک Hebrew می‌دهد. این شیءها تغییر نمی‌کنند. addDays()، startOfMonth() و بقیهٔ متدها شیء تازه برمی‌گردانند.

۳. اختیاری: نام‌های کوتاه سراسری

به‌طور پیش‌فرض هیچ تابع سراسری تعریف نمی‌شود. اگر jdate() و is_national_code() را بدون use function می‌خواهید، یک بار، مثلاً در فایل راه‌اندازی، روشنشان کنید:

$skipped = \RtlyKit\Globals::register();   // آرایهٔ نام‌هایی که تعریف نشد

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

register() از ۲۷ نام کمکی فقط آن‌هایی را که آزادند تعریف می‌کند. تابع موجود را عوض نمی‌کند و خطا نمی‌دهد. فهرست نام‌های ردشده را برمی‌گرداند (آرایهٔ خالی یعنی همه تعریف شدند). چند بار صدا زدنش مشکلی ندارد. برای نام‌های ردشده از شکل فضای‌نام‌دار استفاده کنید. جزئیات در توابع کمکی و سراسری.

۴. اولین اعتبارسنجی

use function RtlyKit\is_national_code;
use function RtlyKit\validate_national_code;
use function RtlyKit\to_persian_digits;
use function RtlyKit\number_to_words;

var_dump(is_national_code('0013542419'));       // bool(true)

$result = validate_national_code('0013542410');
var_dump($result->isValid());                  // bool(false)
print_r($result->errors());                    // [0] => invalid_checksum

echo to_persian_digits('1405/01/01'), "\n";    // ۱۴۰۵/۰۱/۰۱
echo number_to_words(1405), "\n";              // یک هزار و چهارصد و پنج

توابع is_*() فقط bool می‌دهند. توابع validate_*() یک Result می‌دهند که isValid()، کدهای خطای پایدار errors() و details() دارد. اعتبارسنج‌ها برای ورودی بد خطا پرتاب نمی‌کنند و فقط گزارش می‌دهند. بیشتر در مرور اعتبارسنج‌ها و کد ملی.

۵. اولین خطا

تقویم با اعتبارسنجی فرق دارد. ساختن تاریخ غیرممکن یا اشتباه برنامه است یا اشتباه داده، پس کلاس‌های تقویم خطا پرتاب می‌کنند. سال ۱۴۰۴ کبیسه نیست و ۳۰ اسفند ۱۴۰۴ وجود ندارد:

use RtlyKit\Exceptions\InvalidDateException;
use RtlyKit\Exceptions\RtlyKitThrowable;

try {
    jdate('1404/12/30');
} catch (InvalidDateException $e) {
    echo get_class($e), ': ', $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
}
// RtlyKit\Exceptions\InvalidDateException: Invalid Jalali date: 1404/12/30 [invalid_date]

try {
    jdate('not a date');
} catch (RtlyKitThrowable $e) {
    echo 'library error: ', $e->getMessage(), "\n";   // library error: Unable to parse date: not a date
}

همهٔ خطاهای کتابخانه RtlyKit\Exceptions\RtlyKitThrowable را پیاده می‌کنند و از \InvalidArgumentException ارث می‌برند. پس یک catch برای همه کافی است. با getErrorCode() یک مقدار پایدار می‌گیرید که می‌توانید روی آن شرط بگذارید. متن پیام را پردازش نکنید. ورودی بیرون از بازه همیشه InvalidDateException می‌دهد و هیچ‌وقت TypeError نمی‌دهد. بازهٔ سال‌ها: جلالی ‎-۶۲۰ تا ۹۳۷۷، هجری ۱ تا ۹۶۶۵، عبری ۳۷۶۲ تا ۱۳۷۵۹. بیشتر در مدیریت خطا.

چند نکتهٔ مهم

خوب است بدانید. تقویم جلالی با تقویم رسمی دانشگاه تهران برای همهٔ سال‌های ۱۲۰۶ تا ۱۴۹۷ برابر است. تقویم هجری ام‌القری آغاز ماه‌های ۱۳۱۸ تا ۱۵۰۰ هجری قمری را مطابق تقویم رسمی KACST می‌دهد (بررسی در 2026-10-08). برای ۱۳۰۰ تا ۱۳۱۷ از دادهٔ ICU/CLDR استفاده می‌شود. جزئیات در دقت و داده.

• منطقهٔ زمانی. اگر DateTimeZone ندهید، منطقهٔ پیش‌فرض PHP به کار می‌رود. وقتی روزِ تقویمی مهم است منطقه بدهید، مثلاً new DateTimeZone('Asia/Tehran') .
• روز هفته. در جلالی شماره‌گذاری از شنبه = ۰ شروع می‌شود. در هجری و عبری از یکشنبه = ۰.

گام بعد

• تاریخ: جلالی ، هجری ، عبری ، تبدیل و مقایسه .
• اعتبارسنجی: مرور اعتبارسنج‌ها .
• تعطیلات: تعطیلات و تقویم تعطیلات .
• پروژه‌های Laravel: راه‌اندازی Laravel .
• مشکل دارید؟ عیب‌یابی و پرسش‌های متداول .