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?
Login or register to comment or ask questions

No comments or questions yet...

Like our articles?

Become a Premium Member for $129/year or $29/month
What else you will get:
  • 58 courses (1056 lessons, total 44 h 09 min)
  • 78 long-form tutorials (one new every week)
  • access to project repositories
  • access to private Discord

Recent Premium Tutorials