نصب

پیش‌نیازها

همین‌قدر. ext-calendar، ext-intl و پایگاه داده لازم نیست. هر سه تقویم با PHP خالص نوشته شده‌اند و جدول ام‌القری داخل بسته است.

نصب با Composer

composer require tsi/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 و facade با نام Jalali خودکار شناخته می‌شوند و چیزی به config/app.php اضافه نمی‌شود. اگر استقرار شما کش شناسایی را نگه می‌دارد، بعد از نصب php artisan package:discover را اجرا کنید.

فایل تنظیمات تعطیلات اختیاری است. اگر می‌خواهید تعطیلات را خودتان تنظیم کنید، آن را منتشر کنید:

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

جزئیات در تقویم تعطیلات.

نصب بدون PHP روی دستگاه (Docker)

اگر PHP و Composer ندارید، از ایمیج‌های رسمی استفاده کنید. در پوشهٔ پروژه:

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 اجرا می‌کند. اگر می‌خواهید روی خود کتابخانه کار کنید، مخزن را clone کنید و از فایل compose آن استفاده کنید:

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، هر نسخهٔ فرعی ممکن است تغییر ناسازگار داشته باشد. همه را همراه با راه مهاجرت در ارتقا می‌نویسیم. تعهد سازگاری و فهرست کلاس‌های داخلی در پایداری API است. تا 1.0.0 نسخهٔ فرعی را در composer.json ثابت نگه دارید (مثلاً ~0.2.0 ) و پیش از بالا بردنش راهنمای ارتقا را بخوانید.

آزمودن نصب

فایل 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 است، باید PHP را به‌روز کنید. این دو دستور Composer هم کمک می‌کنند:

composer show tsi/rtly-kit            # نسخهٔ نصب‌شده و اطلاعات بسته
composer check-platform-reqs          # PHP و افزونه‌ها را با همهٔ بسته‌های نصب‌شده می‌سنجد

اگر چیزی کار نکرد

• Class "RtlyKit\..." not found یا Call to undefined function RtlyKit\jdate() : یا vendor/autoload.php فراخوانی نشده یا بارگذار خودکار کهنه است. composer dump-autoload را اجرا کنید.
• Call to undefined function jdate() (بدون فضای‌نام): نام‌های کوتاه سراسری اختیاری‌اند. use function RtlyKit\jdate; بنویسید یا \RtlyKit\Globals::register() را صدا بزنید.
• Composer به‌خاطر نسخهٔ PHP نصب نمی‌کند: PHP 8.2 یا جدیدتر نصب کنید.
• موارد دیگر: عیب‌یابی و پرسش‌های متداول .

حذف

1. بسته را حذف کنید: composer remove tsi/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 requestها بردارید. JalaliCast را از مدل‌ها و facade به نام Jalali را از کد پاک کنید. فایل ترجمه یا تنظیمات کپی‌شده (مثل config/rtly-kit.php ) را هم حذف کنید. بعد php artisan optimize:clear را اجرا کنید. داده‌های ذخیره‌شده در پایگاه داده با حذف بسته تغییر نمی‌کنند، اما پیش از برداشتن cast ببینید cast آن‌ها را چطور ذخیره کرده بود.

بسته بیرون از vendor/ چیزی نصب نمی‌کند (جز قفل Composer و اطلاعات بارگذار خودکار). پس کار دیگری برای پاک‌سازی نمی‌ماند.