ماکروهای 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)

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

آرگومان $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

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

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

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