التثبيت

المتطلبات والتثبيت عبر Composer أو Docker، وتكامل Carbon وLaravel الاختياري، والإصدارات المدعومة، وكيفية التحقق من التثبيت وإزالة الحزمة بشكل نظيف.

المتطلبات

المتطلب	الحالة	ملاحظات
PHP `^8.2`	إلزامي	يُختبر في CI على PHP 8.2 و8.3 و8.4 و8.5. هذا هو المطلوب الوحيد، ولا يلزم أي امتداد إضافي (حتى mbstring)
Composer 2	مطلوب للتثبيت	يتولى التحميل التلقائي؛ ولا تعتمد الحزمة على أي اعتماد إلزامي في Composer
`nesbot/carbon` ^3.0	اختياري	يفعّل ماكروات Carbon
`illuminate/support` ^11 أو ^12 أو ^13	اختياري	الاكتشاف التلقائي في Laravel، والواجهة (Facade)، وقواعد التحقق، وتحويل Eloquent (إعداد Laravel)

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

التثبيت عبر Composer

Bash

composer require tsi/rtly-kit

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

PHP

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

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

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

Bash

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 مثبّتين محليًا، فشغّلهما من الصور الرسمية. من مجلد مشروعك:

Bash

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

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

Bash

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

<?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:

Bash

composer show tsi/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 أو أحدث.
حالات أخرى: استكشاف الأخطاء والأسئلة الشائعة .

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

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

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