إعداد Laravel

التثبيت والاكتشاف التلقائي#

لا حاجة إلى شيء غير Composer. تعلن الحزمة عن مزوّد الخدمة واسم الواجهة المستعار في composer.json تحت extra.laravel، فيسجّلهما الاكتشاف التلقائي للحزم في Laravel عند تنفيذ composer install أو composer update التالي.

composer require enaxon/rtly-kit

يستخدم التكامل مكوّنات Laravel التالية: illuminate/support وilluminate/translation وilluminate/validation وilluminate/database، وهي موجودة أصلًا في أي تطبيق Laravel. وتعمل مجموعة الاختبارات على هذه المكوّنات بالإصدارات 11 و12 و13 (ويتطلب Laravel 13 نفسه PHP 8.3 أو أحدث). أما المكتبة نفسها فتحتاج إلى PHP 8.2 فقط وتعمل بدون Laravel.

إذا عطّل تطبيقك الاكتشاف لهذه الحزمة ("dont-discover": ["enaxon/rtly-kit"]) فسجّل المزوّد بنفسك. في Laravel 11 وما بعده أضِفه إلى bootstrap/providers.php:

return [
    App\Providers\AppServiceProvider::class,
    RtlyKit\Laravel\RtlyKitServiceProvider::class,
];

وفي هياكل التطبيقات الأقدم أضِف الفئة نفسها إلى المصفوفة providers في config/app.php. ملف الإعداد اختياري (انظر الإعداد)، ولا يوجد ترحيل (migration).

ماذا يفعل مزوّد الخدمة#

لـ RtlyKit\Laravel\RtlyKitServiceProvider مهمة واحدة في كل مرحلة:

• register() تربط كائنًا وحيدًا (singleton) بمفتاح الحاوية rtly-kit.jalali، وهو RtlyKit\Laravel\JalaliFactory. وهذا هو الكائن الذي تقف خلفه الواجهة (Facade). وتدمج أيضًا إعدادات rtly-kit الافتراضية، وتربط RtlyKit\Holiday\HolidayCalendar ككائن وحيد يُبنى من rtly-kit.holidays عند أول طلب.
• boot() تثبّت ماكروات Carbon (انظر ماكروات Carbon)، وتحمّل ترجمات الحزمة تحت مساحة الأسماء rtly-kit، وتعرض ملف الإعدادات للنشر، وتسجّل قواعد التحقق حين تحتوي الحاوية على مصنع للتحقق (انظر التحقق والتحويل (Cast)).

وإذا لم يكن validator في الحاوية من النوع Illuminate\Validation\Factory (بديل مخصص) فإن المزوّد يتركه كما هو ويتخطى القواعد بدل أن يفشل.

واجهة Jalali#

الاسم المستعار Jalali (الفئة RtlyKit\Laravel\Facades\Jalali) يحوّل الاستدعاءات إلى المصنع. ويوفّر أربع دوال تحاكي المنشئات الثابتة في RtlyKit\Calendar\Jalali:

use RtlyKit\Laravel\Facades\Jalali;

echo Jalali::create(1404, 1, 1)->format('Y/m/d l');   // 1404/01/01 جمعه
echo Jalali::make('2025-03-21')->toDateString();       // 1404/01/01
echo get_class(Jalali::now());                         // RtlyKit\Calendar\Jalali
// Jalali::today() متاحة أيضاً

يُرجع كل استدعاء كائن Jalali عاديًا غير قابل للتغيير، فيسري عليه كل ما في صفحة التقويم الجلالي. والمصنع كائن وحيد (singleton)، لذا يُرجع تكرار app('rtly-kit.jalali') النسخة نفسها.

الواجهة اختيارية. ففي الفئات يمكنك استيراد الفئة مباشرة أو استخدام الدالة المساعدة ذات مساحة الأسماء \RtlyKit\jdate()؛ وفي الاختبارات لا شيء يحتاج إلى محاكاة لأن المصنع لا يحتفظ بحالة.

الترجمات: الفارسية والإنجليزية والعربية#

يستدعي المزوّد loadTranslationsFrom() مع مساحة الأسماء rtly-kit، فتكون الرسائل في rtly-kit::validation.* وتتبع لغة التطبيق. وهناك ثلاث مجموعات كاملة، بسطر واحد لكل قاعدة:

الملف العربي هو resources/lang/ar/validation.php في الحزمة، وله المفاتيح نفسها. وهذه هي القاعدة نفسها بثلاث لغات:

// حقل اسمه national_code، وقيمته '1234567890'، والقاعدة national_code
// locale fa: national code کد ملی معتبر نیست.
// locale en: The national code is not a valid Iranian national code.
// locale ar: national code ليس رقماً وطنياً إيرانياً صالحاً.

(يحوّل Laravel اسم الحقل national_code إلى التسمية "national code"؛ أعطِ الحقل تسمية مناسبة عبر ترجمات attributes لتحصل على جملة طبيعية.)

إذا لم يكن للغة المفعّلة سطر فتُستخدم لغة Laravel الاحتياطية المعتادة (app.fallback_locale). وإذا لم يوجد أي نص مترجم إطلاقًا فالملاذ الأخير هو النص الإنجليزي المدمج.

تجاوز رسالة#

لا تحتاج إلى نشر أي شيء. اختر ما يناسبك، من الأضيق نطاقًا إلى الأوسع:

1. لكل استدعاء تحقق: مرّر رسائل مخصصة إلى المُتحقِّق أو إلى $request->validate() بالطريقة المعتادة، مثلًا بالمفتاح postal_code أو zip.postal_code. والرسالة المخصصة تتغلب دائمًا.
2. على مستوى التطبيق: أضِف سطر القاعدة إلى ملفك lang/fa/validation.php (المفتاح هو اسم القاعدة، مثل 'sheba' => 'شبای :attribute اشتباه است.'). ويُفضَّل سطر validation.<rule> في التطبيق على سطر الحزمة.
3. استبدال نصوص الحزمة: أنشئ lang/vendor/rtly-kit/fa/validation.php (أو en أو ar). تحمّله آلية التجاوز القياسية للحزم في Laravel فوق ملف الحزمة؛ وتحتاج فقط إلى المفاتيح التي تغيّرها.

المخرجات المتحقَّق منها للخيارين 2 و3 مع اللغة fa:

// lang/vendor/rtly-kit/fa/validation.php  ->  ['national_code' => 'کد ملی :attribute درست نیست.']
// lang/fa/validation.php                  ->  ['sheba' => 'شبای :attribute اشتباه است.']
// رسالة مخصصة في الاستدعاء                ->  ['postal_code' => 'کد پستی :attribute نادرست']
//
// national_code: کد ملی x درست نیست.
// sheba:         شبای x اشتباه است.
// postal_code:   کد پستی x نادرست

اسم الحقل في هذه الأمثلة x، ولهذا يظهر x في الجمل. وفي نموذج حقيقي اضبط تسميات مقروءة في المصفوفة attributes داخل ملف validation.php لديك.

الإعداد#

ملف الإعداد اختياري، وبدونه يعمل كل شيء بالقيم الافتراضية. انشره حين تريد ضبط العطل:

php artisan vendor:publish --tag=rtly-kit-config

ينشئ هذا الأمر الملف config/rtly-kit.php. وفيه اليوم قسم واحد هو holidays: إزاحة التواريخ الإسلامية، وبدايات الأشهر الهجرية الفعلية، والعطل المضافة والمحذوفة، ومفتاح للبيانات الرسمية. وشرح الخيارات مع مثال عملي في صفحة تقويم العطل القابل للتعديل.

وما عدا ذلك يتحدد السلوك بالمكتبة وبلغة التطبيق. وتقرأ المكتبة المنطقة الزمنية الافتراضية من PHP (date_default_timezone_get()) التي يضبطها Laravel من config('app.timezone')، لذا تتبع Jalali::now() المنطقة الزمنية لتطبيقك.

التالي: قواعد التحقق وتحويل Eloquent (Cast).