التثبيت

المتطلبات#

هذا كل شيء. لا تحتاج إلى ext-mbstring ولا ext-calendar ولا ext-intl ولا إلى أي قاعدة بيانات: التقاويم الثلاثة مكتوبة بـ PHP الخالص، وجدول أم القرى مضمَّن داخل الحزمة.

التثبيت عبر Composer#

composer require enaxon/rtly-kit

تأكد من أن سكربت الدخول لديك يحمّل المحمّل التلقائي لـ Composer مرة واحدة:

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

يربط المحمّل التلقائي النطاق RtlyKit\ بالمجلد src/ في الحزمة، ويحمّل أيضًا ملف مساعدة واحدًا يعرّف الدوال المساعدة ذات النطاق (RtlyKit\jdate() وغيرها). لا يعرّف هذا الملف أي دالة عامة؛ راجع الدوال المساعدة والعامة لمعرفة الأسماء القصيرة الاختيارية.

الحزم الاختيارية#

composer require nesbot/carbon          # ماكروات Carbon: toJalali() وcreateFromJalali() وغيرهما
composer require illuminate/support     # فقط في المشاريع غير المبنية على Laravel التي تريد مكوّنات Laravel

يعمل كلا التكاملين من تلقاء نفسه. تُسجَّل ماكروات Carbon عندما يعثر المحمّل التلقائي على Carbon. أما في تطبيق Laravel فيُعثر على مزوّد الخدمة (Service Provider) والاسم المستعار للواجهة Jalali عبر الاكتشاف التلقائي للحزم، فلا يُضاف شيء إلى config/app.php. بعد التثبيت في مشروع Laravel قائم، نفّذ php artisan package:discover إذا كان نشرك يخزّن الاكتشاف مؤقتًا.

التثبيت دون PHP على جهازك (Docker)#

إذا لم يكن PHP وComposer مثبّتين محليًا، فشغّلهما من الصور الرسمية. من مجلد مشروعك:

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

يثبّت الأمر الأول الحزمة في vendor/؛ ويشغّل الثاني سكربتًا مثل الموجود في البدء السريع على PHP 8.3. وللعمل على المكتبة نفسها، استنسخ المستودع واستخدم الملف docker-compose.yml فيه:

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");'

الإصدارات المدعومة#

• PHP 8.2 و8.3 و8.4 و8.5 (مصفوفة CI).
• Laravel 11 و12 و13 (يتطلب Laravel 13 نفسه PHP 8.3 أو أحدث).
• Carbon 3.
• الإصدارات. قبل 1.0.0 قد يتضمن الإصدار الفرعي (minor) تغييرات غير متوافقة مع السابق. يرد كل تغيير منها في دليل الترقية مع خطوات الانتقال (الترقية)، ويرد وعد التوافق وقائمة الفئات الداخلية في استقرار واجهة API. حتى 1.0.0، ثبّت الإصدار الفرعي في قيد composer.json (قيد tilde مثل ~0.x.y مع الإصدار الذي اختبرته)، واقرأ دليل الترقية قبل رفعه.

التحقق من التثبيت#

أنشئ الملف verify.php في جذر مشروعك:

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

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

شغّل php verify.php. يجب أن يطبع السطر الأخير 1405/01/01؛ أما إصدار PHP أقل من 8.2 فيعني أن البيئة لا تستوفي المتطلبات. ويفيد أيضًا أمران من Composer:

composer show enaxon/rtly-kit            # الإصدار المثبّت والبيانات الوصفية
composer check-platform-reqs          # يفحص PHP والامتدادات مقابل كل حزمة مثبّتة

إذا فشل شيء ما#

• Class "RtlyKit\..." not found أو Call to undefined function RtlyKit\jdate(): لم يُحمَّل vendor/autoload.php، أو أن المحمّل التلقائي في Composer قديم؛ نفّذ composer dump-autoload.
• Call to undefined function jdate() (دون النطاق): الأسماء العامة القصيرة اختيارية. استخدم use function RtlyKit\jdate; أو استدعِ \RtlyKit\Globals::register().
• يرفض Composer التثبيت ويذكر إصدار PHP: ثبّت PHP 8.2 أو أحدث.
• حالات أخرى: استكشاف الأخطاء والأسئلة الشائعة.

إلغاء التثبيت#

1. أزل الحزمة: composer remove enaxon/rtly-kit. وهذا يعيد إنشاء المحمّل التلقائي أيضًا.
2. احذف استخداماتك الخاصة: أسطر use RtlyKit\... وuse function RtlyKit\...، واستدعاءات \RtlyKit\Globals::register()، وأي كتل catch لـ RtlyKit\Exceptions\*. ابحث في شيفرتك عن RtlyKit للعثور عليها كلها.
3. مشاريع Carbon: تختفي الماكروات (toJalali وjformat وtoHijri وtoHebrew وcreateFromJalali وcreateFromHijri وcreateFromHebrew) مع الحزمة؛ فاستبدل استدعاءاتها أولًا.
4. مشاريع Laravel: أزل قواعد التحقق national_code وsheba وbank_card وiran_mobile وmobile وpostal_code وvehicle_plate من طلبات النماذج (form requests)، وأزل JalaliCast من نماذجك، وأي استخدام للواجهة Jalali، وأي ملفات ترجمة نسختها من الحزمة. ثم نفّذ php artisan optimize:clear. إن إزالة الحزمة لا تمسّ البيانات التي كتبها تطبيقك في قاعدة البيانات، فتحقق من طريقة تخزين التحويل (Cast) لها قبل أن تحذفه.

لا تثبّت الحزمة شيئًا خارج vendor/ (سوى ملف القفل وبيانات التحميل التلقائي الخاصة بـ Composer)، فلا يوجد ما يلزم تنظيفه بعد ذلك.