در این صفحه
نصب و شناسایی خودکار#
جز Composer چیز دیگری لازم نیست. بسته service provider و facade را در 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.0||^12.0||^13.0). خود Laravel 13 به PHP 8.3 یا بالاتر نیاز دارد. خود کتابخانه فقط PHP 8.2 می‌خواهد و بدون Laravel هم کار می‌کند.
اگر شناسایی خودکار این بسته را خاموش کرده‌اید ("dont-discover": ["enaxon/rtly-kit"])، provider را خودتان ثبت کنید. در Laravel 11 و بالاتر در bootstrap/providers.php اضافه کنید:
return [
App\Providers\AppServiceProvider::class,
RtlyKit\Laravel\RtlyKitServiceProvider::class,
];در ساختار قدیمی همین کلاس را به آرایهٔ providers در config/app.php اضافه کنید. فایل تنظیمات و migration اجباری نیست. فقط اگر بخواهید تعطیلات را تنظیم کنید، فایل تنظیمات را منتشر می‌کنید (پیکربندی).
service provider چه می‌کند#
کلاس RtlyKit\Laravel\RtlyKitServiceProvider در هر مرحله یک کار دارد:
register()یک singleton با کلیدrtly-kit.jalaliمی‌بندد، از نوعRtlyKit\Laravel\JalaliFactory. همین شیء پشت facade است. تنظیمات پیش‌فرض را هم ادغام می‌کند و یکHolidayCalendarدر container می‌گذارد (تقویم تعطیلات).boot()سه کار می‌کند: ماکروهای Carbon را نصب می‌کند (ماکروهای Carbon)، ترجمه‌های بسته را با فضای‌نامrtly-kitبارگذاری می‌کند و اگر container یک validation factory داشته باشد، قانون‌های اعتبارسنجی را ثبت می‌کند (اعتبارسنجی و cast).
\RtlyKit\Globals::register() را صدا بزنید. توابع کمکی و سراسری را ببینید.اگر validator در container از نوع Illuminate\Validation\Factory نباشد (جایگزین سفارشی)، provider آن را دست نمی‌زند و ثبت قانون‌ها را کنار می‌گذارد، به‌جای اینکه خطا بدهد.
facade به نام Jalali#
نام مستعار Jalali (کلاس RtlyKit\Laravel\Facades\Jalali) به factory می‌رسد. چهار متد دارد که سازنده‌های استاتیک 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 می‌دهد. پس هر چه در تقویم جلالی خواندید اینجا هم درست است. factory یک singleton است و app('rtly-kit.jalali') همیشه همان نمونه را می‌دهد.
facade اختیاری است. در کلاس‌ها می‌توانید کلاس را مستقیم import کنید یا از \RtlyKit\jdate() استفاده کنید. در آزمون‌ها هم چیزی برای fake کردن نیست، چون factory حالت ندارد.
ترجمه‌ها: فارسی، انگلیسی، عربی#
provider ترجمه‌ها را با فضای‌نام rtly-kit بارگذاری می‌کند. پس پیام‌ها زیر rtly-kit::validation.* هستند و از زبان برنامه پیروی می‌کنند. سه مجموعهٔ کامل هست و هر قانون یک خط دارد:
| کلید | fa | en | ar |
|---|---|---|---|
national_code | :attribute کد ملی معتبر نیست. | The :attribute is not a valid Iranian national code. | :attribute ليس رقماً وطنياً إيرانياً صالحاً. |
sheba | :attribute شماره شبا معتبر نیست. | The :attribute is not a valid Iranian Sheba (IBAN). | :attribute ليس رقم شبا (IBAN) إيرانياً صالحاً. |
bank_card | :attribute شماره کارت بانکی معتبر نیست. | The :attribute is not a valid Iranian bank card. | :attribute ليس رقم بطاقة مصرفية إيرانية صالحاً. |
iran_mobile، mobile | :attribute شماره موبایل معتبر نیست. | The :attribute is not a valid Iranian mobile number. | :attribute ليس رقم هاتف محمول إيرانياً صالحاً. |
postal_code | :attribute کد پستی معتبر نیست. | The :attribute is not a valid Iranian postal code. | :attribute ليس رمزاً بريدياً إيرانياً صالحاً. |
vehicle_plate | :attribute پلاک خودرو معتبر نیست. | The :attribute is not a valid Iranian vehicle plate. | :attribute ليست لوحة مركبة إيرانية صالحة. |
فایل عربی در بسته 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) به کار می‌رود. اگر ترجمه‌ای پیدا نشود، آخرین راه متن انگلیسی داخل بسته است.
عوض کردن پیام‌ها#
لازم نیست چیزی منتشر کنید. از ساده به کلی، یکی را انتخاب کنید:
- برای یک فراخوانی: پیام دلخواه را مثل همیشه به validator یا
$request->validate()بدهید، مثلاً با کلیدpostal_codeیاzip.postal_code. پیام دلخواه همیشه برنده است. - در کل برنامه: خط قانون را به
lang/fa/validation.phpخودتان اضافه کنید (کلید همان نام قانون است، مثلاً'sheba' => 'شبای :attribute اشتباه است.'). خطvalidation.<rule>برنامه بر خط بسته مقدم است. - جایگزین کردن متن‌های بسته: فایل
lang/vendor/rtly-kit/fa/validation.php(یاenوar) را بسازید. روش استاندارد vendor-override در Laravel آن را روی فایل بسته می‌نشاند. فقط کلیدهایی را بنویسید که عوض می‌شوند.
نتیجهٔ گزینه‌های ۲ و ۳ با زبان 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 (date_default_timezone_get()) می‌خواند و Laravel آن را از config('app.timezone') تنظیم می‌کند. پس Jalali::now() از منطقهٔ زمانی برنامهٔ شما پیروی می‌کند.
تنها فایل تنظیمات اختیاری، مخصوص تعطیلات است:
php artisan vendor:publish --tag=rtly-kit-configدر config/rtly-kit.php می‌توانید جابه‌جایی روز، شروع ماه قمری، تعطیلی اضافه و حذف‌شده و خاموش کردن داده‌های رسمی را بدهید. همهٔ گزینه‌ها در تقویم تعطیلات آمده‌اند.