Carbon لـ PHP: دليل شامل مع أمثلة

ما هو Carbon ولماذا هو مطلوب؟

Carbon هي مكتبة قوية وأنيقة للغة PHP، تعمل على توسيع الفئة المدمجة DateTime. إذا سبق لك العمل مع التواريخ في PHP بشكل أصلي، فأنت تعلم أن DateTime و DateTimeImmutable القياسيين يوفران وظائف أساسية، لكن واجهة برمجة التطبيقات (API) الخاصة بهما غالبًا ما تكون ضخمة وغير بديهية. يحل Carbon هذه المشكلة من خلال تقديم بناء جملة نظيف وقابل للقراءة ومعبر للعمل مع التواريخ والوقت.

لماذا نستخدم Carbon؟ تخيل أنك بحاجة إلى:

\n
• إضافة 3 أيام إلى التاريخ الحالي: $date->add(new DateInterval('P3D')) (PHP الأصلي) مقابل $date->addDays(3) (Carbon).
\n
• الحصول على الفرق بالأيام بين تاريخين: DateTime::diff() المرهق مع التنسيق اللاحق مقابل $date1->diffInDays($date2).
\n
• التحقق مما إذا كان التاريخ يوم عطلة نهاية الأسبوع: كتابة منطق خاص بك مقابل $date->isWeekend().
\n

يجعل Carbon الكود ليس فقط أقصر، بل وأكثر وضوحًا بشكل ملحوظ. يُستخدم على نطاق واسع في أطر عمل PHP الحديثة مثل Laravel (حيث يعتبر المعيار)، Symfony، Yii وغيرها. المكتبة متوافقة تمامًا مع DateTime الأصلي، مما يعني أنه يمكنك استخدام Carbon في أي مكان يُتوقع فيه استخدام DateTime.

المزايا الرئيسية لـ Carbon:

\n
• بناء جملة معبر: تمت تسمية الطرق بحيث يكون الغرض منها واضحًا دون تعليقات (startOfDay()، endOfMonth()، isFuture()).
\n
• الثبات (Immutable): دعم CarbonImmutable للعمل الآمن مع التواريخ دون آثار جانبية.
\n
• التدويل (Localization): دعم مدمج لتنسيق التواريخ بلغات مختلفة.
\n
• API غني: مئات الطرق للتلاعب بالتواريخ ومقارنتها وتنسيقها وحسابها.
\n
• مقارنة بديهية: طرق مثل isBefore()، isAfter()، isSameDay().
\n

تثبيت Carbon

يتم تثبيت Carbon عبر Composer - مدير الحزم القياسي لـ PHP. إذا لم يكن لديك Composer بعد، فيجب تثبيته (راجع getcomposer.org).

افتح الطرفية (Terminal) في جذر مشروعك ونفذ الأمر التالي:

composer require nesbot/carbon

بعد التثبيت الناجح، سيظهر في مشروعك مجلد vendor/ وملف composer.json مع إضافة التبعية. لاستخدام Carbon في الكود الخاص بك، يجب تضمين أداة التحميل التلقائي (autoloader) الخاصة بـ Composer:

<?php\nrequire_once 'vendor/autoload.php';\n\nuse Carbon\\Carbon;\n\n// الآن يمكنك استخدام Carbon\necho Carbon::now(); // 2025-04-03 15:30:00\n?>

هام: يتطلب Carbon إصدار PHP 8.0 أو أعلى (للإصدارات الأخيرة). يُوصى باستخدام PHP 8.1+.

بداية سريعة مع مثال كود

دعنا ننتقل فورًا إلى التطبيق العملي. إليك بعض الأمثلة البسيطة التي توضح قوة Carbon:

<?php\nrequire_once 'vendor/autoload.php';\nuse Carbon\\Carbon;\n\n// التاريخ والوقت الحاليين\n$now = Carbon::now();\necho "الآن: " . $now . "\\n"; // 2025-04-03 15:30:00\n\n// إنشاء تاريخ من نص\n$birthday = Carbon::createFromDate(1990, 5, 15);\necho "تاريخ الميلاد: " . $birthday->format('d.m.Y') . "\\n"; // 15.05.1990\n\n// التلاعب بالتواريخ\n$tomorrow = Carbon::tomorrow();\necho "غدًا: " . $tomorrow . "\\n";\n\n$nextWeek = Carbon::now()->addWeek();\necho "بعد أسبوع: " . $nextWeek . "\\n";\n\n// الفرق بين التواريخ\n$age = $birthday->diffInYears(Carbon::now());\necho "العمر: $age سنة\\n"; // 34 أو 35\n\n// التحقق من الشروط\n$date = Carbon::parse('2025-12-25');\nif ($date->isChristmas()) {\n    echo "هذا عيد الميلاد!\\n";\n}\n\n//