ماکروهای Carbon

این بخش چه می‌دهد

اگر nesbot/carbon نصب باشد، RTLY-Kit چند ماکرو روی Carbon\Carbon و Carbon\CarbonImmutable ثبت می‌کند. با آن‌ها در یک خط از Carbon به کلاس‌های تقویم می‌روید و برمی‌گردید. Carbon اختیاری است. اگر نصب نباشد، چیزی ثبت نمی‌شود و چیزی خراب نمی‌شود. برنامه‌های Laravel خودشان Carbon دارند و ماکروها بدون کار اضافه کار می‌کنند (راه‌اندازی Laravel).

پیش‌نیاز. RTLY-Kit نصب باشد (نصب) و Carbon نسخهٔ ۳ (composer require nesbot/carbon).

ماکروها چطور ثبت می‌شوند

وقتی Composer بارگذاری خودکار را شروع می‌کند، فایل توابع کمکی بسته هم بارگذاری می‌شود. این فایل چک می‌کند کلاس‌های Carbon هست یا نه و اگر بود، ماکروها را یک بار ثبت می‌کند. شما کاری نمی‌کنید:

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

use Carbon\Carbon;
use Carbon\CarbonImmutable;
use RtlyKit\Calendar\HijriVariant;
use RtlyKit\Calendar\Jalali;

var_dump(Carbon::hasMacro('toJalali'));   // bool(true)

Carbon را با Composer نصب کنید. ماکروها هنگام شروع بارگذار خودکار Composer ثبت می‌شوند و فقط اگر کلاس‌های Carbon پیدا شوند. Carbonی که روی همان بارگذار نباشد (مثلاً phar کنار برنامه) پیدا نمی‌شود. کلاس‌هایی که ماکروها را ثبت می‌کنند داخلی‌اند. به نام ماکروها تکیه کنید، که بخشی از API عمومی هستند.

فهرست ماکروها

آرگومان $tz می‌تواند DateTimeZone، رشتهٔ نام منطقه یا null باشد. با null منطقهٔ پیش‌فرض PHP به کار می‌رود، نه منطقهٔ یک شیء Carbon دیگر.

از Carbon به تقویم

$c = Carbon::create(2026, 3, 21, 12, 0, 0, 'UTC');

echo $c->toJalali();                           // 1405/01/01 12:00:00
echo get_class($c->toJalali());                // RtlyKit\Calendar\Jalali
echo $c->jformat('l j F Y');                   // شنبه 1 فروردین 1405
echo $c->jformat();                            // 1405/01/01 12:00:00
echo $c->toHijri()->format('j F Y', 'en');     // 2 Shawwal 1447
echo $c->toHebrew()->format('j F Y');          // 3 Nisan 5786

نتیجه یک شیء تقویم است، نه Carbon. از اینجا به بعد با API تقویم کار کنید (مثلاً رقم فارسی با $c->toJalali()->format('Y/m/d', true)). هر وقت خواستید با toGregorian() برگردید:

echo Carbon::now('UTC')->setDate(2026, 3, 21)->toJalali()->addMonths(1)->format('Y/m/d');  // 1405/02/01

صدا زدن مستقیم make() با یک شیء Carbon همین نتیجه را می‌دهد، چون Carbon یک DateTimeInterface است:

echo Jalali::make($c)->format('Y/m/d H:i');                                   // 1405/01/01 12:00
echo Jalali::make(Carbon::create(2026, 3, 21, 22, 0, 0, 'UTC'), new DateTimeZone('Asia/Tehran'))->format('Y/m/d H:i');  // 1405/01/02 01:30

از اجزای تقویم به Carbon

$a = Carbon::createFromJalali(1405, 1, 1, 0, 0, 0, 'UTC');
echo get_class($a), ' ', $a->toDateTimeString();      // Carbon\Carbon 2026-03-21 00:00:00

$b = CarbonImmutable::createFromJalali(1405, 1, 1, 8, 30, 0, 'Asia/Tehran');
echo get_class($b), ' ', $b->toIso8601String();       // Carbon\CarbonImmutable 2026-03-21T08:30:00+03:30

echo Carbon::createFromHijri(1446, 9, 1, 0, 0, 0, 'UTC')->toDateString();   // 2025-03-01
echo Carbon::createFromHebrew(5786, 1, 1, 0, 0, 0, 'UTC')->toDateString();  // 2025-09-23

برای گونهٔ Tabular هجری، آن را آخرین آرگومان createFromHijri() بدهید: Carbon::createFromHijri(1446, 10, 1, 0, 0, 0, 'UTC', HijriVariant::Tabular).

خطاها

ماکروها با خود کلاس‌های تقویم اعتبارسنجی می‌کنند. پس ورودی نامعتبر یا بیرون از بازه RtlyKit\Exceptions\InvalidDateException می‌دهد (InvalidFormatException خود Carbon بیرون نمی‌آید). نام ناشناختهٔ منطقهٔ زمانی هم همین خطا را می‌دهد:

use RtlyKit\Exceptions\RtlyKitThrowable;

$cases = [
    fn () => Carbon::createFromJalali(1404, 12, 30),
    fn () => Carbon::createFromJalali(1404, 1, 1, 0, 0, 0, 'Nowhere/Land'),
    fn () => Carbon::createFromHijri(9999, 1, 1),
    fn () => Carbon::createFromHebrew(1, 1, 1),
];
foreach ($cases as $f) {
    try { $f(); }
    catch (RtlyKitThrowable $e) { echo get_class($e), ': ', $e->getMessage(), "\n"; }
}
// RtlyKit\Exceptions\InvalidDateException: Invalid Jalali date: 1404/12/30
// RtlyKit\Exceptions\InvalidDateException: Unknown timezone: Nowhere/Land
// RtlyKit\Exceptions\InvalidDateException: Invalid Hijri date: 9999/1/1
// RtlyKit\Exceptions\InvalidDateException: Invalid Hebrew date: 1/1/1

بازه‌ها همان بازهٔ تقویم‌هاست: جلالی ‎-۶۲۰ تا ۹۳۷۷، هجری ۱ تا ۹۶۶۵، عبری ۳۷۶۲ تا ۱۳۷۵۹.

خوب است بدانید

خوب است بدانید. ماکروها همان دقتِ کلاس‌های تقویم را دارند. جلالی با قاعدهٔ حسابی ۳۳ ساله کار می‌کند و برای ۱۲۰۶ تا ۱۴۹۷ با تقویم رسمی برابر است. ام‌القری برای ۱۳۱۸ تا ۱۵۰۰ هجری قمری با تقویم رسمی KACST می‌خواند (بررسی در 2026-10-08) و ۱۳۰۰ تا ۱۳۱۷ از داده‌ی ICU/CLDR می‌آید. مرز روز نیمه‌شب مدنی است.

• ماکروها روی کلاس Carbon سراسری ثبت می‌شوند. اگر بستهٔ دیگری ماکرویی با همین نام ( toJalali ، toHijri و ...) ثبت کند، آخرین ثبت برنده است. اگر می‌خواهید مطمئن باشید، مستقیم از کلاس‌های تقویم استفاده کنید ( Jalali::make($carbon) ).
• منطقهٔ زمانی همراه شیء می‌آید. toJalali() منطقهٔ همان شیء Carbon را می‌گیرد. اگر روز تقویمی مهم است، پیش از تبدیل منطقه را یکسان کنید.
• شمارهٔ روز هفته بین تقویم‌ها فرق دارد. نتیجهٔ getDayOfWeek() یک تقویم را به تقویم دیگر ندهید. تبدیل و مقایسهٔ تاریخ‌ها را ببینید.