حزمة Carbon التاريخية 😎

حزمة Carbon package :

هي حزمة تقوم بتسهيل التعامل مع التاريخ datetime , وذلك بتوفير الكثير من الدوال التي تساعدنا لإجراء عمل معين على التاريخ. وهي ترث كلاس dateTime الموجود في php .

وفي laravel لا تحتاج الى تنصيبها لانها موجودة افتراضية , ولكن فقط قم باستدعائها مباشرة :

use Carbon\Carbon;

استخدام الحزمة :

انشاء instance جديد من carbon وافتراضياً يأتي بقيمة التاريخ الحالي :

$c = new Carbon(); => equivalent to Carbon::now();

$d = Carbon::now( "Asia/Amman" );

لجلب التاريخ حاليا بتوقيت دولة معينة , ولو تركتها فارغة , ستجلب بالتوقيت الافتراضي.

 

$c = new Carbon( 'first day of January 2008', 'America/Vancouver' );

$d->isoFormat( "d" );

الحصول على معلومات عنصر معين من التاريخ , مثل (الشهر أو اليوم الخ ...) , وهذه هي الاختصارات :

 

Y => 2020 , M => month , m => minute , s => second , D => day ,

dd => short month name

 

انشاء تاريخ جديد ببيانات معينة بتوقيت معينة :

$d = Carbon::create( 2012, 1, 2, 0, 0, 0 , 'Asia/Amman' );

 

الحصول على كم اختلاف عدد الساعات بين تاريخين :

$d1->diffInHours( $d2 );

 

الحصول على تاريخ اليوم  :

$today = Carbon::today(); // 2020-07-28 00:00:00

الحصول على تاريخ الغد :

$tomorrow = Carbon::tomorrow(); // 2020-07-29 00:00:00

 

الحصول على تاريخ البارحة :

$yesterday = Carbon::yesterday(); // 2020-07-27 00:00:00

 

Getters

الحصول على بيانات معينة من التاريخ :

dt->year   /  $dt->month   /   $dt->day /   $dt->hour   /   $dt->minute   /   $dt->second$

dt->micro /   $dt->dayOfWeek /   $dt->weekOfMonth   /   $dt->daysInMonth$

$dt->timestamp       // 11212101212

$d>tzName;           // Asia/Amman

 

Setters

وضع قيمة معينة لعنصر معين بداخل التاريخ , مثل تعديل الشهر :

$dt->year = 1975;

$dt->month = 13; // would force year++ and month = 1

$dt->month = 5;

$dt->day = 21;

$dt->hour = 22;

$dt->minute = 32;

$dt->second = 5;

 

Fluent setters

هي امكانية عمل سلسلة من الدوال وكل دالة تعتمد على نتيجة الدالى التي قبلها , مثال :

$dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->microsecond(123456)->toDateTimeString();

 

echo (new Carbon('first day of December 2008'))->addWeeks(2);

// 2008-12-15 00:00:00

 

Addition/substitution

الجمع بين تاريخين أو طرح تاريخ من آخر , نستخدم الدوال التالية :

 

# لإضافة يوم/اسوع/شهر ... , الى تاريخ معين :

$dt->addDay(); // default 1

$dt->addWeekdays(4);

$dt->addWeekday(); // default 1

$dt->addWeeks(3);

$dt->addWeek(); // default 1

$dt->addHours(24);

$dt->addHour(); // default 1

$dt->addMinutes(61);

$dt->addMinute();

$dt->addSeconds(61);

$dt->addSecond();

 

# لطرح من التاريخ عدد معين من الايام / الاسابيع ... :

$dt->subDay();

$dt->subDays(29);

$dt->subWeekday();

$dt->subWeekdays(4);

$dt->subWeek();

$dt->subWeeks(3);

$dt->subHour();

$dt->subHours(24);

$dt->subMinute();

$dt->subMinutes(61);

$dt->subSecond();

$dt->subSeconds(61);

 

أو بطريقة أخرى , يمكنك تحديد نوع المدة الزمنية النضافة مثل ثواني أو دقائق أو ساعات , مع مقدار تلك الاضافة , مثال :

$d->add( 1 , "second" );

إضافة ثانية للتاريخ المخزن بالمتغير d , ويمكنك استخدام month , day hour , year, minute مكان
كلمة second , ويمكنك وضع اي رقم مكان 1 للاشارة الى كم ثانية أو كم دقيقة الخ…

 

# تحويل التاريخ النصي المكتوب مسبقا ب carbon أو بال format الخاص فيها , الى كائن carbon للتعامل معه , وذلك لأمور التخزين بال DB والاسترجاع منها , يتم هكذا :

$s = "2020-07-30 00:00:00";

$d = Carbon::createFromFormat( 'Y-m-d H:i:s' , $s );

 

$d->format(‘Y-m‘)

 

يمكنك استخدام copy لنسخ carbon instance والتعديل عليها :

$dt->copy()

تقوم بإرجاع بداية الأسبوع :

$dt->startOfWeek()->format('Y-m-d H:i'); // string(16) "2021-02-07 00:00"

 

تقوم بإرجاع نهاية الأسبوع :

$dt->endOfWeek()->format('Y-m-d H:i')); // string(16) "2021-02-13 23:59"

 

هذه الدوال تقوم بتحويل التاريخ ك string format وكل واحدة بشكل معين :

$dt->toDateString(); // 1975-12-25

$dt->toFormattedDateString(); // Dec 25, 1975

$dt->toTimeString(); // 14:15:16

$dt->toDateTimeString(); // 1975-12-25 14:15:16

$dt->toDayDateTimeString(); // Thu, Dec 25, 1975 2:15 PM

 

# تحويل ال instance الى مصفوفة تحتوي على جميع بيانات التاريخ ك properties :

$dt->toArray();

# هذه الدالة تقوم بإرجاع مصفوفة تحتوي على خاصية Date و timezone :

$dt->carbonize( '2019-03-21' );

مثال :

// as result
array(2) {

["date"]=> string(26) "2019-03-21 00:00:00.000000"

["timezone"]=> string(12) "Europe/Paris"

}

 

Comparison 

إمكانية المقارنة بين two carbon instances :

$first->equalTo($second);

$first->notEqualTo($second);

$first->greaterThan($second);

$first->greaterThanOrEqualTo($second);

$first->lessThan($second);

$first->lessThanOrEqualTo($second);

$first->isAfter($second);

$first->isBefore($second);

 

اختصارات الدوال السابقة (وهي تعمل نفس العمل) :

equalTo() => eq() => ==

notEqualTo() => ne() => !=

greaterThan() => gt() => >

equalTo() => eq() => ==

greaterThanOrEqualTo() => gte() => >=

lessThanOrEqualTo() => lte() => <=

lessThan() => lt() => <

 

# مقارنة تاريخ بين تاريخين غيره , هل هذا التاريخ هو بين كذا وكذا :

Carbon::create(2012, 9, 5, 3)->between( $first, $second );

 

# تقوم دالة isSameAs بمقارنة جزء معين من تاريخين مع بعضهم , مثل أن نقارن (هل اسبوع التاريخ التاريخ الأول هو نفس الأسبوع من التاريخ الثاني ) :

$dt->isSameAs( 'w', $dt2 );

 

# التحقق من تاريخ معين هل هو في المستقبل بناءا على الوقت الحالي , أم هو في الماضي :

$dt->isFuture();

$dt->isPast();

 

# دوال تتحقق من السنوات , مثل هل هذا التاريخ بنفس السنة الحالية , أم في السنة الماضية , الخ ...

$dt->isSameYear($dt2);

$dt->isCurrentYear();

$dt->isNextYear();

$dt->isLastYear();

$dt->isLongYear();

$dt->isLeapYear();

 

والدوال في هذه الحزمة package  كثيرة وفيها تفاصيل كثيرة , ولكن حاولنا تغطية أهم هذه الدوال, واكثرها استخداما, وللتعمق أكثر قم بزيارة الموقع الرسمي 

 

 

المصادر :

https://carbon.nesbot.com/

كلمات دليلية: carbon date datetime laravel php