ماكروات 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)

ثبّت Carbon عبر Composer. تُسجَّل الماكروات عند بدء المحمّل التلقائي في Composer وإمكان العثور على فئات Carbon. أما نسخة Carbon غير الموجودة على المحمّل التلقائي نفسه (مثل phar مضمَّن) فلا يُكتشف. فئات التسجيل داخلية؛ فاعتمد على أسماء الماكروات، فهي جزء من واجهة API العامة.

مرجع الماكروات

يقبل الوسيط $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.

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

من المفيد أن تعرف. الماكروات تعطي النتائج نفسها التي تعطيها فئات التقويم. فالجلالي يعتمد القاعدة الحسابية ذات الدورة البالغة 33 سنة، وهي مطابقة للتقويم الرسمي في السنوات 1206 إلى 1497. وبيانات أم القرى الهجرية (1300 إلى 1500 هـ) مأخوذة من ICU/CLDR، وتطابق بدايات أشهرها تقويم KACST الرسمي للسنوات 1318 إلى 1500 هـ (فُحص في 2026-10-08). ويتغير اليوم عند منتصف الليل المدني.

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