آیا کنجکاو هستید که بدانید پکیج 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 نصب کنید. امیدواریم که مطالب موجود در این مقاله برای شما مفید و آموزنده بوده باشد. خوشحال می‌شویم نظرات، تجربیات و سوالات خود را با ما و سایر کاربران سون لرن به اشتراک بگذارید.

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