7 Less-known but Useful Carbon functions

We all use Carbon library to manage date and time, right? But who has actually read full documentation of what functions it has? In addition to well-known ones like now() or format(), Carbon has a lot more useful stuff. Let's take a look.

1. isX: True/False

There are a lot of functions to check whether Carbon object is Today, Tomorrow, Weekend, LeapYear and much more. Here's the list from the official docs:

$dt->isWeekday();
$dt->isWeekend();
$dt->isYesterday();
$dt->isToday();
$dt->isTomorrow();
$dt->isFuture();
$dt->isPast();
$dt->isLeapYear();
$dt->isSameDay(Carbon::now());

Impressive, right?

2. isBirthday

In addition to the first list, there's a function to check if today's date is person's birthday. Instead of checking month and day separately, you just call one function:

$born = Carbon::createFromDate(1987, 4, 23);
$noCake = Carbon::createFromDate(2014, 9, 26);
$yesCake = Carbon::createFromDate(2014, 4, 23);
var_dump($born->isBirthday($noCake));              // bool(false)
var_dump($born->isBirthday($yesCake));             // bool(true)

3. StartOfX and EndOfX list

One of the usual comparison in projects happens - is the date within that month, meaning between 1st day and last day of month. For the end of month you can use good old PHP function cal_days_in_month(), but with Carbon it's more convenient - there's a function EndOfMonth(), like this:

$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->endOfMonth();         // 2012-01-31 23:59:59

Not only that, there's a whole lot of functions for StartOf period and EndOf period:

$dt = Carbon::create(2012, 1, 31, 12, 0, 0);
echo $dt->startOfDay();     // 2012-01-31 00:00:00
echo $dt->endOfDay();       // 2012-01-31 23:59:59
echo $dt->startOfMonth();   // 2012-01-01 00:00:00
echo $dt->endOfMonth();     // 2012-01-31 23:59:59
echo $dt->startOfYear();    // 2012-01-01 00:00:00
echo $dt->endOfYear();      // 2012-12-31 23:59:59
echo $dt->startOfDecade();  // 2010-01-01 00:00:00
echo $dt->endOfDecade();    // 2019-12-31 23:59:59
echo $dt->startOfCentury(); // 2000-01-01 00:00:00
echo $dt->endOfCentury();   // 2099-12-31 23:59:59
echo $dt->startOfWeek();    // 2012-01-30 00:00:00
echo $dt->endOfWeek();      // 2012-02-05 23:59:59

4. Today, Tomorrow, Yesterday

Three simple but useful functions - instead of calling now(), stripping hours/minutes/seconds and adding or subtracting days, use these:

$today = Carbon::today();  // assuming 2016-06-24
echo $today;                             // 2016-06-24 00:00:00
$tomorrow = Carbon::tomorrow();
echo $tomorrow;                          // 2016-06-25 00:00:00
$yesterday = Carbon::yesterday();
echo $yesterday;                         // 2016-06-23 00:00:00

5. DiffForHumans + locale

Probably you have used function called diffForHumans() - it returns the difference between two dates in a human-friendly readable way:

echo Carbon::now()->subDays(5)->diffForHumans();  // 5 days ago

But did you know it can also be localized? Just change your locale and result will be different, example for German language:

Carbon::setLocale('de');
echo Carbon::now()->addYear()->diffForHumans();    // in 1 Jahr

6. Changing NOW to whatever you want

I've written a separate article about that before, but would be a shame to not mention this brilliant function again. Basically, if you want to test your functionality against now() function which will be in the future, you can "fake" current now and set it to whatever you want:

$knownDate = Carbon::create(2001, 5, 21, 12);  // create testing date
Carbon::setTestNow($knownDate);                     // set the mock
echo Carbon::now();                                 // 2001-05-21 12:00:00

7. Finally, weekdays constants

Another thing I had written about, but really useful so repeating here. Instead of guessing which day of week corresponds to which number (and also for better readability of the code), you can use these:

var_dump(Carbon::SUNDAY);                          // int(0)
var_dump(Carbon::MONDAY);                          // int(1)
var_dump(Carbon::TUESDAY);                         // int(2)
var_dump(Carbon::WEDNESDAY);                       // int(3)
var_dump(Carbon::THURSDAY);                        // int(4)
var_dump(Carbon::FRIDAY);                          // int(5)
var_dump(Carbon::SATURDAY);                        // int(6)

So these are less-known (in my opinion) Carbon functions, did you know them? Or would you add anything else to the list?

7 Less-known but Useful Carbon functions

1. isX: True/False

2. isBirthday

3. StartOfX and EndOfX list

4. Today, Tomorrow, Yesterday

5. DiffForHumans + locale

6. Changing NOW to whatever you want

7. Finally, weekdays constants

Like our articles?

Recent New Courses

[Mini-course] Filament: Visual Customizations

Design Patterns in Laravel 11

[Mini-Course] Laravel 11: Breeze with User Role Areas