آیا کنجکاو هستید که بدانید پکیج Carbon در لاراول چه کاربردهایی دارد؟ کار با تاریخ و زمان در PHP، ممکن است کار چندان راحتی نباشد. چرا که بحث تاریخ و زمان برای توسعه دهندگان PHP دردسرهای خاص خودش را دارد. کار کردن با توابع PHP مثل strtotime، مشکلات فرمت دهی تاریخ و زمان، محاسبات بسیار و... نمونه هایی از چالش‌های ایجاد شده، هنگام کار با تاریخ و زمان در PHP می‌باشند. اگر به مباحث آموزش php علاقه مندید پیشنهاد میکنم همین حالا به صفحه مربوطه مراجعه کنید.

پکیج Carbon برای کار با تاریخ و زمان در زبان PHP ایجاد شده است و به صورت پیش فرض، همراه با لاراول نصب می‌شود. این پکیج توسط Brian Nesbit توسعه یافته است و با متدهای مختلفی که دارد، کار با تاریخ و زمان در زبان PHP و فریمورک لاراول را بسیار ساده‌تر می‌کند. همچنین با استفاده از پکیج کربن، کدهای تاریخ و زمان، به لحاظ سمنتیک یا معنایی، بسیار خواناتر هستند؛ در نتیجه، کد، قابلیت نگهداری و توسعه ی بهتری خواهد داشت.

در ادامه ی این مقاله قصد داریم نحوه ی نصب پکیج Carbon در لاراول را به شما آموزش دهیم، سپس به صورت عملی متدهای این پکیج را بررسی خواهیم کرد. با ما همراه باشید.

پکیج Carbon در لاراول چه کاربردهایی دارد؟

پکیج Carbon در لاراول، از کلاس DateTime خود PHP ارث بری می‌کند. پکیج کربن امکانات بسیار خوبی را برای کار با تاریخ و زمان در PHP و لاراول، فراهم می‌کند که عبارتند از:

• مشخص کردن محدوده ی زمانی یا Timezone
• سادگی دسترسی به زمان کنونی
• تبدیل Datetime برای خوانایی بیشتر
• تبدیل یک عبارت انگلیسی به Datetime
• کاستن و افزودن تاریخ و زمان
• مقایسه ی تاریخ و زمان
• خوانایی بیشتر کد به لحاظ معنایی

تمامی موارد فوق، توسعه دهندگان PHP و لاراول را ناگزیر به استفاده از این پکیج کاربردی، برای کار با تاریخ و زمان در PHP می‌کنند. در ادامه، نحوه ی نصب پکیج Carbon را توضیح می‌دهیم.

نحوه ی نصب پکیج Carbon در لاراول

برای استفاده از پکیج Carbon، تنها نیاز دارید تا از Namespace آن استفاده کنید. خوش بختانه، این پکیج به صورت پیش فرض با لاراول نصب می‌شود و نیازی به افزودن آن به وسیله ی Composer نداریم:

<?php
use Carbon\Carbon;

حال که Namespace را اضافه کردیم، بیایید به قابلیت‌های متنوع این پکیج نگاهی بیاندازیم.

شروع کار با پکیج Carbon در لاراول

برای شروع کار با پکیج Carbon، می‌توانیم یک نمونه ی جدید از کلاس Carbon را ایجاد کنیم و سپس متدهای مختلف را روی آن فراخوانی کنیم:

$carbon = new Carbon;

شیء ایجاد شده، یک خصوصیت Public با نام date دارد که مقدار آن یک رشته شامل تاریخ و زمان است. در اینجا، یک خصوصیت Public دیگر نیز با نام timezone_type که مقدار آن یک عدد صحیح است و هم چنین یک خصوصیت Public با نام timezone که مقدار محدوده ی زمانی به صورت رشته در آن قرار می‌گیرد، داریم.

روش دیگر برای استفاده از متدهای Carbon، فراخوانی متدهای استاتیک به صورت مستقیم از کلاس Carbon، بدون نیاز به ایجاد نمونه ی جدید است. در ادامه ی این مقاله، از این روش استفاده خواهیم کرد.

گرفتن یک زمان و تاریخ مشخص در لاراول با پکیج کربن

برای گرفتن شیء Carbon مربوط به یک زمان و تاریخ، مثل اکنون، دیروز و فردا و مانند آن ها، می‌توانید به صورت زیر از متدهای مربوط به آن‌ها استفاده کنید:

// get the current time  - 2021-01-14 10:10:54
$current = Carbon::now();
// get today - 2021-01-14 00:00:00
$today = Carbon::today();
// get yesterday - 2021-01-13 00:00:00
$yesterday = Carbon::yesterday();
// get tomorrow - 2021-01-15 00:00:00
$tomorrow = Carbon::tomorrow();

هم چنین، می‌توانید با پاس دادن یک رشته هنگام ایجاد یک نمونه از کلاس Carbon، آن را به شیء Carbon تبدیل کنید:

// parse a specific string - 2021-01-01 00:00:00
$newYear = new Carbon('first day of January 2021');
// set a specific timezone - 2021-01-01 00:00:00
$newYearPST = new Carbon('first day of January 2021', 'America\Pacific');

این رشته را می‌توانید به اشکال گوناگون پاس دهید؛ برای مثال:

$carbon = new Carbon('November 5th 2021');
$carbon = new Carbon('5th November 2021');
$carbon = new Carbon('20211105');
$carbon = new Carbon('2021/11/5');
$carbon = new Carbon('21-11-05');
$carbon = new Carbon('2021-11-05');

این رشته را می‌توانید به صورت زمانی جلوتر یا عقب‌تر از زمان کنونی، هنگام ایجاد نمونه از کلاس Carbon، پاس دهید:

$carbon = new Carbon('-3 days');
$carbon = new Carbon('-4 weeks');
$carbon = new Carbon('-5 years');
$carbon = new Carbon('+2 days 9 hours');
$carbon = new Carbon('+3 weeks 4 days');
$carbon = new Carbon('+3 years 1 months 1 day 5 hours 33 minutes 25 seconds');

می توانیم با استفاده از متدهای زیر، با تعداد مشخصی پارامتر ورودی، یک شیء Carbon ایجاد کنیم:

Carbon::createFromDate($year, $month, $day, $tz);
Carbon::createFromTime($hour, $minute, $second, $tz);
Carbon::create($year, $month, $day, $hour, $minute, $second, $tz);

اگر هرکدام از پارامترهای فوق را برابر null قرار دهید، به صورت پیش فرض مقدار کنونی آن در نظر گرفته خواهد شد.

هم چنین می‌توانید با استفاده از متد createFromFormat، از فرمت دلخواه خود برای ایجاد شیء Carbon استفاده کنید. برای مثال:

$newDateTime = Carbon::createFromFormat('Y-m-d H:i:s.u', '2021-02-01 03:45:27.612584');

برای مشاهده ی فرمت‌های مختلف تاریخ و زمان در PHP، به صفحه ی DateTime Formats در وب سایت رسمی PHP مراجعه کنید.

فرمت دهی به تاریخ و زمان در PHP

می توانید برای تبدیل شیء Carbon ایجاد شده به یک رشته با فرمت خاص، از متدهای متعددی که این پکیج در اختیار شما قرار می‌دهد، استفاده کنید. برای مثال:

$newDateTime = Carbon::create(2021, 11, 05, 11, 45, 21, 'UTC');
$newDateTime ->toDateTimeString()
// output: ‘2021-11-05 11:45:21’
$newDateTime ->toAtomString()
// output: ‘2021-11-05T11:45:21+00:00’
$newDateTime ->toCookieString()
// output: ‘Friday, 05-Nov-2021 11:45:21 UTC’
$newDateTime ->toDayDateTimeString()
// output: ‘Fri, Nov 5, 2021 11:45 AM’
$newDateTime ->toFormattedDateString()
// output: ‘Nov 5, 2021’
$newDateTime ->toTimeString()
// output: ‘11:45:21’
$newDateTime ->toDateString()
// output: ‘2021-11-05’

برای تبدیل به فرمت دلخواه خود می‌توانید از متد format استفاده کنید:

$newDateTime ->format('l jS \\of F Y h:i:s A')
// output: ‘Friday 5th of November 2021 11:45:21 AM’

کاهش و افزایش تاریخ و زمان در PHP

وقتی که راجع به تاریخ و زمان صحبت می‌کنیم، گرفتن و فرمت دهی تاریخ و زمان، تنها مواردی نیستند که به آن‌ها نیاز داریم. در اغلب موارد انجام یک سری محاسبات ساده، امری ضروری به نظر می‌رسد.

برای مثال، زمانی که می‌خواهید به یک کاربر، اشتراک محدود آزمایشی یا Trial بدهید، نیاز دارید تا اشتراک کاربر پس از مدت زمانی محدود، منقضی شود. این کار را می‌توانیم به راحتی و با استفاده از متدهای افزایش و کاهش در پکیج Carbon انجام دهیم.

// get the current time
$current = Carbon::now();
// add 30 days to the current time
$trialExpires = $current->addDays(30);

یک سری از متدهای افزایش و کاهش که از ثانیه تا سال تنوع دارند را بر اساس مستندات پکیج Carbom در زیر برایتان آورده ایم:

$dt = Carbon::create(2021, 1, 31, 0);
echo $dt->toDateTimeString();            // 2021-01-31 00:00:00
echo $dt->addYears(5);                   // 2026-01-31 00:00:00
echo $dt->addYear();                     // 2027-01-31 00:00:00
echo $dt->subYear();                     // 2026-01-31 00:00:00
echo $dt->subYears(5);                   // 2021-01-31 00:00:00
echo $dt->addMonths(60);                 // 2026-01-31 00:00:00
echo $dt->addMonth();                    // 2026-03-03 00:00:00 equivalent of $dt->month($dt->month + 1); so it wraps
echo $dt->subMonth();                    // 2026-02-03 00:00:00
echo $dt->subMonths(60);                 // 2021-02-03 00:00:00
echo $dt->addDays(29);                   // 2021-03-03 00:00:00
echo $dt->addDay();                      // 2021-03-04 00:00:00
echo $dt->subDay();                      // 2021-03-03 00:00:00
echo $dt->subDays(29);                   // 2021-02-03 00:00:00
echo $dt->addWeekdays(4);                // 2021-02-09 00:00:00
echo $dt->addWeekday();                  // 2021-02-10 00:00:00
echo $dt->subWeekday();                  // 2021-02-09 00:00:00
echo $dt->subWeekdays(4);                // 2021-02-03 00:00:00
echo $dt->addWeeks(3);                   // 2021-02-24 00:00:00
echo $dt->addWeek();                     // 2021-03-02 00:00:00
echo $dt->subWeek();                     // 2021-02-24 00:00:00
echo $dt->subWeeks(3);                   // 2021-02-03 00:00:00
echo $dt->addHours(24);                  // 2021-02-04 00:00:00
echo $dt->addHour();                     // 2021-02-04 01:00:00
echo $dt->subHour();                     // 2021-02-04 00:00:00
echo $dt->subHours(24);                  // 2021-02-03 00:00:00
echo $dt->addMinutes(61);                // 2021-02-03 01:01:00
echo $dt->addMinute();                   // 2021-02-03 01:02:00
echo $dt->subMinute();                   // 2021-02-03 01:01:00
echo $dt->subMinutes(61);                // 2021-02-03 00:00:00
echo $dt->addSeconds(61);                // 2021-02-03 00:01:01
echo $dt->addSecond();                   // 2021-02-03 00:01:02
echo $dt->subSecond();                   // 2021-02-03 00:01:01
echo $dt->subSeconds(61);                // 2021-02-03 00:00:00

مقایسه ی تاریخ و زمان در PHP

با استفاده از پکیج Carbon در لاراول می‌توانیم زمان‌های مختلف را با هم مقایسه کنیم. در ادامه، مثال هایی را از مستندات پکیج Carbon برای شما انتخاب کرده ایم:

$first = Carbon::create(2021, 9, 5, 23, 26, 11);
$second = Carbon::create(2021, 9, 5, 20, 26, 11, 'America/Vancouver');
var_dump($first->equalTo($second));                // bool(false)
var_dump($first->notEqualTo($second));             // bool(true)
var_dump($first->greaterThan($second));            // bool(false)
var_dump($first->greaterThanOrEqualTo($second));   // bool(false)
var_dump($first->lessThan($second));               // bool(true)
var_dump($first->lessThanOrEqualTo($second));      // bool(true)

از شکل کوتاه شده ی این متدها نیز به شکل زیر می‌توان استفاده کرد:

var_dump($first->eq($second));                     // bool(false)
var_dump($first == $second);                       // bool(false)
var_dump($first->ne($second));                     // bool(true)
var_dump($first != $second);                       // bool(true)
var_dump($first->gt($second));                     // bool(false)
var_dump($first->isAfter($second));                // bool(false)
var_dump($first > $second);                        // bool(false)
var_dump($first->gte($second));                    // bool(false)
var_dump($first >= $second);                       // bool(false)
var_dump($first->lt($second));                     // bool(true)
var_dump($first->isBefore($second));               // bool(true)
var_dump($first < $second);                        // bool(true)
var_dump($first->lte($second));                    // bool(true)
var_dump($first <= $second);                       // bool(true)

Getterها و Setterها در پکیج کربن

برای تغییر تاریخ و زمان یا اخذ آن، می‌توانید از Getterها و Setterها به روش زیر استفاده کنید:

$dt = Carbon::now();
// set some things
$dt->year   = 2015;
$dt->month  = 04;
$dt->day    = 21;
$dt->hour   = 22;
$dt->minute = 32;
$dt->second = 5;
// get some things
var_dump($dt->year);
var_dump($dt->month);
var_dump($dt->day);
var_dump($dt->hour);
var_dump($dt->second);
var_dump($dt->dayOfWeek);
var_dump($dt->dayOfYear);
var_dump($dt->weekOfMonth);
var_dump($dt->daysInMonth);

می توانیم متدهای Setter را به صورت زنجیره ای فراخوانی کنیم:

$dt = Carbon::now();
$dt->year(1975)->month(5)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();
$dt->setDate(1975, 5, 21)->setTime(22, 32, 5)->toDateTimeString();
$dt->setDateTime(1975, 5, 21, 22, 32, 5)->toDateTimeString();

گرفتن زمان نسبی در PHP

پکیج کربن این امکان را برای ما فراهم می‌آورد تا با استفاده از متدهای diff، زمان را به صورت نسبی نمایش دهیم. برای مثال، فرض کنید که یک بلاگ داریم و می‌خواهیم زمان انتشار را به شکل، مثلا، 3 ساعت پیش، نمایش دهیم. برای انجام این کار، می‌توانیم به راحتی از متدهای diff استفاده کنیم.

یافتن اختلاف زمانی در PHP

متدهای زیر برای یافتن رقم اختلاف استفاده می‌شوند:

$current = Carbon::now();
$dt      = Carbon::now();
$dt = $dt->subHours(6);
echo $dt->diffInHours($current);         // -6
echo $current->diffInHours($dt);         // 6
$future = $current->addMonth();
$past   = $current->subMonths(2);
echo $current->diffInDays($future);      // 31
echo $current->diffInDays($past);        // -62

نمایش اختلاف زمانی برای کاربر

گاهی نیاز داریم اختلاف زمانی را به صورت خوانا، برای کاربر نمایش دهیم. با استفاده از متد diffForHumans می‌توانیم هم اختلاف را بیابیم و هم آن را به صورت خوانا برای کاربر نمایش دهیم. برای مثال:

$dt     = Carbon::now();
$past   = $dt->subMonth();
$future = $dt->addMonth();
echo $dt->subDays(10)->diffForHumans();     // 10 days ago
echo $dt->diffForHumans($past);             // 1 month ago
echo $dt->diffForHumans($future);           // 1 month before

تاریخ شمسی در PHP

همان طور که می‌دانید، پکیج Carbon براساس تاریخ میلادی کار می‌کند.

منابع تکمیلی

برای مشاهده ی تمامی متدهای موجود در پکیج Carbon که تعدادشان بسیار زیاد و متنوع نیز هست، می‌توانید به مستندات رسمی پکیج Carbon مراجعه کنید.

نتیجه گیری

در این مقاله از مجموعه مقالات آموزش لاراول، با امکانات فوق العاده ی پکیج Carbon برای کار با تاریخ و زمان در لاراول آشنا شدیم و کاربردی‌ترین متدهای آن را فرا گرفتیم. این پکیج و متدهایش را می‌توانید به همین شیوه در پروژه‌های PHP خود نیز استفاده کنید؛ فقط باید ابتدا آن را به وسیله ی Composer نصب کنید. امیدواریم که مطالب موجود در این مقاله برای شما مفید و آموزنده بوده باشد. خوشحال می‌شویم نظرات، تجربیات و سوالات خود را با ما و سایر کاربران سون لرن به اشتراک بگذارید.

اگر به یادگیری بیشتر لاراول علاقه داری می‌توانی در دوره آموزش لاراول کاربردی (بسته پروژه محور) شرکت کنی، این دوره شامل ۱۲ پروژه کاربردی و پر استفاده در دنیای واقعی است، که تمامی پروژه‌ها به صورت کامل برنامه نویسی خواهند شد، تا دانشجو بتواند با روند ایجاد و تکمیل پروژه به صورت کامل آشنا شود.