همهی راهنماها
راهنمایی با این جستوجو پیدا نشد.
راهاندازی Laravel
RTLY-Kit چطور به Laravel وصل میشود. شناسایی خودکار بسته، کار service provider، facade به نام Jalali، پیامهای فارسی و انگلیسی و عربی که میتوانید عوض کنید، و تنظیمات تعطیلات.
در این صفحه
نصب و شناسایی خودکار
جز 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 هم کار میکند.
نکته. آزمونهای یکپارچگی، کلاسهای واقعی container، translator، validation factory و مدل Eloquent را اجرا میکنند، نه یک برنامهٔ کامل 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 است. تنظیمات پیشفرضrtly-kitرا هم ادغام میکند وRtlyKit\Holiday\HolidayCalendarرا به شکل singleton میبندد. اولین باری که خواسته شود، ازrtly-kit.holidaysساخته میشود ( تقویم تعطیلات ).boot()چند کار میکند: ماکروهای Carbon را نصب میکند ( ماکروهای Carbon )، ترجمههای بسته را با فضاینامrtly-kitبارگذاری میکند، فایل تنظیمات را برای انتشار آماده میکند و اگر container یک validation factory داشته باشد، قانونهای اعتبارسنجی را ثبت میکند ( اعتبارسنجی و cast ).
نکته. provider هیچ تابع سراسری ثبت نمیکند. یک آزمون provider را بوت میکند و میبیند که بعدش هیچکدام از ۲۷ نام کوتاه وجود ندارد. اگر نامهای کوتاه سراسری میخواهید، خودتان \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 میتوانید جابهجایی روز، شروع ماه قمری، تعطیلی اضافه و حذفشده و خاموش کردن دادههای رسمی را بدهید. همهٔ گزینهها در تقویم تعطیلات آمدهاند. این بلوک هنگام اولین ساخته شدن تقویم چک میشود: اگر holidays آرایه نباشد یا گزینهای نادرست باشد، InvalidDateException میدهد. islamic_offset رشتهٔ شبیه عدد صحیح مثل '1' را هم میپذیرد، چون env() همین را برمیگرداند.
خوب است بدانید. اگر در لحظهٔ بوت provider، validation factory در container بسته نشده باشد، قانونها ثبت نمیشوند و بعداً هم ثبت نخواهند شد. این فقط در بوتاسترپهای غیرمعمول پیش میآید، مثلاً container کنسولی بدون سرویس اعتبارسنجی.
این صفحه مفید بود؟