ماكروات Carbon

ما الذي يمنحك إياه هذا#

إذا كانت الحزمة nesbot/carbon مثبّتة، يسجّل RTLY-Kit مجموعة صغيرة من الماكروات على Carbon\Carbon وCarbon\CarbonImmutable. بها تنتقل بين Carbon وفئات التقويم باستدعاء واحد، في الاتجاهين. Carbon اختياري: لا يشترطه RTLY-Kit، وبدونه لا يُسجَّل شيء ولا يتعطل شيء. وتأتي تطبيقات Laravel مع Carbon أصلًا، فالماكروات متاحة فيها دون أي خطوة إضافية (انظر أيضًا إعداد Laravel).

المتطلبات. تثبيت RTLY-Kit (التثبيت) وCarbon 3 (composer require nesbot/carbon؛ الإصدار 3 هو المدعوم).

كيف يعمل التسجيل#

يحمّل 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 (وعندها تُطبَّق المنطقة الافتراضية في 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، فاستخدم واجهة التقويم من هنا فصاعدًا (الأرقام الفارسية مثلًا عبر $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

النطاقات المدعومة هي نطاقات التقاويم: الجلالي -620..9377، والهجري 1..9665، والعبري 3762..13759.

الحدود وأمور تستوجب الحذر#

• الماكروات عامة على مستوى الفئة: فإذا عرّفت حزمة أخرى ماكرو بالاسم نفسه (toJalali أو toHijri ...) فالغلبة لمن يسجّل آخرًا. استخدم فئات التقويم مباشرةً (Jalali::make($carbon)) عندما تحتاج إلى اليقين.
• تنتقل المناطق الزمنية مع الكائن: تستخدم toJalali() المنطقة الخاصة بكائن Carbon نفسه، فوحّد المنطقة قبل التحويل إذا كان يوم التقويم مهمًا.
• تختلف أرقام أيام الأسبوع بين التقاويم؛ فلا تمرّر ناتج getDayOfWeek() من تقويم إلى آخر. راجع تحويل التواريخ ومقارنتها.