البدء السريع

ما الذي ستفعله

في هذه الصفحة ستثبّت الحزمة، وتطبع أول تاريخ جلالي، وتجري أول عملية تحقق، وتلتقط أول استثناء من المكتبة. كل شيء يعمل على PHP العادي: لا إطار عمل، ولا ملف إعدادات، ولا اعتماديات إضافية.

المتطلبات. PHP 8.2 أو أحدث (ولا شيء غيره)، وأداة Composer (opens in a new tab). إذا لم يكن PHP ولا Composer على جهازك، فاتبع طريقة Docker في التثبيت.

1. التثبيت

composer require tsi/rtly-kit

يثبّت Composer الحزمة وينشئ الملف vendor/autoload.php. لا تحتاج المكتبة إلى أي اعتمادية إلزامية. أما التكاملات الاختيارية (ماكروات Carbon وLaravel) فتعمل تلقائيًا إذا كان Carbon أو Laravel موجودًا. التفاصيل في التثبيت.

2. أول تاريخ

أنشئ ملفًا باسم 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. يطبع السطر الأول التاريخ الجلالي ليوم 21 مارس 2026، وهو عيد النوروز 1405. ويعرض السطر الثاني اليوم نفسه في التقويم الهجري.

لاحظ أمرين:

• دوال المساعدة موجودة في النطاق RtlyKit وتُستورد بالعبارة use function . لذلك لا تتعارض مع دالة من كتابتك أو من حزمة أخرى.
• تُقرأ السلسلة '2026-03-21' على أنها تاريخ ميلادي. أما سلسلة مثل '1405/01/01' (سنة أقل من 1700 بصيغة Y/m/d ) فتُقرأ على أنها تاريخ جلالي. التفاصيل في قراءة السلاسل في make() .

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

تُرجع الدالة كائنًا من Jalali، وتُرجع hdate() كائنًا من Hijri، وتُرجع hebrew_date() كائنًا من Hebrew. هذه الكائنات غير قابلة للتغيير: addDays() وstartOfMonth() وبقية المعدِّلات تُرجع كائنًا جديدًا.

3. اختياري: أسماء عامة قصيرة

لا تُعرَّف أي دالة عامة افتراضيًا. إذا فضّلت كتابة jdate() وis_national_code() مباشرة، فعِّل ذلك مرة واحدة، مثلًا في ملف الإقلاع:

$skipped = \RtlyKit\Globals::register();   // مصفوفة بالأسماء التي تعذّر تعريفها

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

تعرّف register() أسماء المساعدات الـ 27 التي ما زالت متاحة. هي لا تستبدل دالة موجودة ولا تُلقي استثناءً، وتُرجع قائمة الأسماء التي تخطّتها (مصفوفة فارغة إذا عُرّف كل شيء). ويمكن استدعاؤها أكثر من مرة بأمان. استخدم الصيغة ذات النطاق لأي اسم جرى تخطّيه. التفاصيل في الدوال المساعدة والعامة.

4. أول عملية تحقق

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(). لا تُلقي أدوات التحقق استثناءً بسبب إدخال خاطئ من المستخدم؛ بل تُبلغ عنه. انظر نظرة عامة على أدوات التحقق والرقم الوطني.

5. أول استثناء

التقويم يختلف عن التحقق: بناء تاريخ مستحيل خطأ في البرنامج أو في البيانات، ولذلك تُلقي فئات التقويم استثناءً. السنة 1404 ليست كبيسة، فلا وجود لـ 30 إسفند 1404:

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() قيمة ثابتة يمكنك التفرّع بحسبها (لا تحلّل نص الرسالة). وأي إدخال خارج النطاق، ومنه السنوات خارج النطاقات المدعومة (الجلالي من -620 إلى 9377، والهجري من 1 إلى 9665، والعبري من 3762 إلى 13759)، يُثير InvalidDateException دائمًا، ولا يُثير TypeError. المزيد في معالجة الأخطاء.

من المفيد أن تعرف

من المفيد أن تعرف. يعتمد التقويم الجلالي قاعدة حسابية ثابتة بدورة من 33 سنة. وقد قورنت بدايات السنوات بالتقويم الرسمي للسنوات 1206 إلى 1497 هـ ش، وبالتعريف الفلكي للسنوات 1178 إلى 1502، وجاءت مطابقة. وفي التقويم الهجري تطابق بدايات الأشهر في جدول أم القرى تقويمَ KACST الرسمي للسنوات 1318 إلى 1500 هـ (فُحصت في 2026-10-08)، أما السنوات 1300 إلى 1317 فمصدرها بيانات ICU/CLDR. التفاصيل في الدقة والبيانات.

• المناطق الزمنية. إذا لم تمرّر DateTimeZone صراحةً، تُستخدم المنطقة الافتراضية في PHP. مرّر منطقة زمنية (مثل new DateTimeZone('Asia/Tehran') ) عندما يكون يوم التقويم مهمًا.
• أيام الأسبوع. يرقّم التقويم الجلالي الأيام من السبت = 0، أما الهجري والعبري فمن الأحد = 0.

إلى أين تذهب بعد ذلك

• التواريخ: الجلالي ، الهجري ، العبري ، التحويل والمقارنة .
• التحقق: نظرة عامة على أدوات التحقق .
• مشاريع Laravel: إعداد Laravel .
• المشكلات: استكشاف الأخطاء والأسئلة الشائعة .