How To Manage DateTime with Carbon in Laravel and PHP

Introduction

Working with date and time in PHP can be complicated. We have to deal with strtotime, formatting issues, lots of calculations, and more.

The Carbon package can help make dealing with date and time in PHP much easier and more semantic so that our code can become more readable and maintainable.

Carbon is a package by Brian Nesbit that extends PHP’s own DateTime class.

It provides some nice functionality to deal with dates in PHP. Specifically things like:

• Dealing with timezones.
• Getting current time easily.
• Converting a datetime into something readable.
• Parse an English phrase into datetime ("first day of January 2016").
• Add and Subtract dates ("+ 2 weeks", "-6 months").
• Semantic way of dealing with dates.

In this article, you will install Carbon and explore the features and functionality that it provides.

Prerequisites

To follow along with this guide, you need to meet the following prerequisites:

• A working Laravel development environment. To set this up, you can follow our guide on How to Install and Configure a Laravel application on Ubuntu 20.04.
  • Or alternatively, follow the Larvel installation documentation. If you opt for the Laravel Sail approach, you will require Docker.

This tutorial was verified with PHP v8.0.5, Composer v2.0.13, MySQL 8.0.24, Laravel v8.40.0, and Carbon v2.31.

Setting Up the Project

In order to use Carbon, you’ll need to import Carbon from the Carbon namespace. Luckily for us, Carbon is already included in Laravel.

Whenever we need to use Carbon, we can import it like so:

<?php
use Carbon\Carbon;

After importing, let’s explore what Carbon provides.

Getting a Specific Date and Time

Get the current time:

$current = Carbon::now();

Current time can also be retrieved with this instantiation:

$current2 = new Carbon();

Get today’s date:

$today = Carbon::today();

Get yesterday’s date:

$yesterday = Carbon::yesterday();

Get tomorrow’s date:

$tomorrow = Carbon::tomorrow();

Parse a specific string:

$newYear = new Carbon('first day of January 2016');

This returns:

Output
2016-01-01 00:00:00

These helpers provide human-readable requests for frequent date and time needs like today(), yesterday(), and tomorrow().

Creating Dates with More Fine-Grained Control

In addition to the quick ways to define date and times, Carbon also let’s us create date and times from a specific number of arguments.

createFromDate() accepts $year, $month, $day, $tz (time zone):

Carbon::createFromDate($year, $month, $day, $tz);

createFromTime() accepts $hour, $minute, $second, and $tz (time zone):

Carbon::createFromTime($hour, $minute, $second, $tz);

create() accepts $year, $month, $day, $hour, $minute, $second, $tz (time zone):

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

These are very helpful when you get some sort of date or time in a format that isn’t normally recognized by Carbon. If you pass in null for any of those attributes, it will default to current.

Manipulating the Date and Time

Grabbing the date and time isn’t the only thing you’ll need to do when working with dates. You’ll often need to manipulate the date or time.

For instance, when creating a trial period for a user, you will want the trial period to expire after a certain amount of time. So let’s say we have a 30-day trial period. We could calculate that time with Carbon’s add and subtract.

For this example, we can use addDays() to determine when the trial expires:

// get the current time
$current = Carbon::now();

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

From the Carbon documentation, here are some of the other add() and sub() methods available to us.

Consider a date set to January 31, 2012:

$dt = Carbon::create(2012, 1, 31, 0);

echo $dt->toDateTimeString();

This will return:

Output
2012-01-31 00:00:00

Modifying the date with addYears() and subYears() will result in the following:

Modifying the date with addMonths() and subMonths() will result in the following:

Take note of how adding one month to “January 31” resulted in “March 3” instead of “February 28”. If you prefer to not have that rollover, you can use addMonthWithoutOverflow().

Modifying the date with addDays() and subDays() will result in the following:

Modifying the date with addWeekdays() and subWeekdays() will result in the following:

Modifying the date with addWeeks() and subWeeks() will result in the following:

Modifying the date with addHours() and subHours() will result in the following:

Modifying the date with addMinutes() and subMinutes() will result in the following:

Modifying the date with addSeconds() and subSeconds() will result in the following:

Using Carbon’s add and subtract tools can provide you with adjusted date and times.

Using Getters and Setters

Another way to read or manipulate the time is to use Carbon’s getters and setters.

Read values with getters:

$dt = Carbon::now();

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);

Change values with setters:

$dt = Carbon::now();

$dt->year   = 2015;
$dt->month  = 04;
$dt->day    = 21;
$dt->hour   = 22;
$dt->minute = 32;
$dt->second = 5;

echo $dt;

We can even chain together some setters.

Here is the previous example using year(), month(), day(), hour(), minute(), and second():

$dt->year(2015)->month(4)->day(21)->hour(22)->minute(32)->second(5)->toDateTimeString();

And here is the same example using setDate() and setTime():

$dt->setDate(2015, 4, 21)->setTime(22, 32, 5)->toDateTimeString();

And here is the same example using setDateTime():

$dt->setDateTime(2015, 4, 21, 22, 32, 5)->toDateTimeString();

All of these approaches will produce the same result: 2015-04-21 22:32:05.

Formatting Date and Time

PHP’s toXXXString() methods are available to display dates and times with predefined formatting:

It’s also possible to use PHP’s DateTime format() for custom formatting:

echo $dt->format('l jS \of F Y h:i:s A');

• l: A full textual representation of the day of the week.
• jS:
  • Day of the month without leading zeros.
  • English ordinal suffix for the day of the month, 2 characters.
• F: A full textual representation of a month.
• Y: A full numeric representation of a year, 4 digits.
• h:i:s:
  • 12-hour format of an hour with leading zeros.
  • Minutes with leading zeros.
  • Seconds with leading zeros.
• A: Uppercase Ante meridiem and Post meridiem.

This code will produce the following result:

Output
Tuesday 21st of April 2015 10:32:05 PM

Using Carbon’s formatting tools can display dates and times to fit your needs.

Calculating Relative Time

Carbon also lets us display time relatively with the diff() methods.

For instance, let’s say we have a blog and wanted to show a published time of 3 hours ago. We would be able to do that with these methods.

Finding the Difference

Consider the following example with a time in the future and a time in the past:

$dt      = Carbon::create(2012, 1, 31, 0);
$future  = Carbon::create(2012, 1, 31, 0);
$past    = Carbon::create(2012, 1, 31, 0);

$future  = $future->addHours(6);
$past    = $past->subHours(6);

Here are the results using diffInHours():

Consider the following example with a date in the future and a date in the past:

$dt      = Carbon::create(2012, 1, 31, 0);
$future  = Carbon::create(2012, 1, 31, 0);
$past    = Carbon::create(2012, 1, 31, 0);

$future  = $future->addMonth();
$past    = $past->subMonths(2);

Here are the results using diffInDays():

Displaying the Difference for Humans

Displaying time relatively can sometimes be more useful to readers than a date or timestamp.

For example, instead of displaying the time of a post like 8:12 AM, the time will be displayed as 3 hours ago.

The diffForHumans() method is used for calculating the difference and also converting it to a humanly readable format.

Consider the following example with a date in the future and a date in the past:

$dt      = Carbon::create(2012, 1, 31, 0);
$future  = Carbon::create(2012, 1, 31, 0);
$past    = Carbon::create(2012, 1, 31, 0);

$future  = $future->addMonth();
$past    = $past->subMonth();

Here are the results using diffForHumans():

Conclusion

In this article, you installed Carbon and explored the features and functionality that it provides.

If you’d like to learn more about Laravel, check out our Laravel topic page for exercises and programming projects. If you’d like to learn more about PHP, check out our PHP topic page for exercises and programming projects.