Easy PHP Dates and Times With Carbon

Click to share! ⬇️

PHP Dates and Times With Carbon are made incredibly simple with the intuitive API provided by this great library. Carbon extends the native PHP DateTime class which gives it access to all of the functions you are familiar with, in addition to some other great new features. Carbon makes use of its own namespace aptly named Carbon. When you get started, make sure to import that namespace such as use Carbon/Carbon; to get up and running quickly. Let’s take a look at some of the various things Carbon can do for us while we review instantiation, getters, setters, string formatting, common formats, differences, modifiers, and more.

1Create a new Carbon Instance
2Carbon For Dummies
3Formatting Dates and Time with Carbon
4Carbon Getters
5Carbon Setters
6Carbon Timezone
7Manipulating Date and Time with Carbon
8Comparing Dates and Times in Carbon
9Checking Date and Time Differences with Carbon
10Modifying Dates and Times with Carbon
11Carbon in the Real World

Create a new Carbon Instance

The first thing we’ll do is to simply create a new instance of the Carbon class so we can have a look at what it is. We’ll do this by simply using the new operator with the Carbon class and assign it to a simple variable aptly named $carbon.

    $carbon = new Carbon;

    var_dump($carbon);

We can inspect our new object now.
var dump of carbon instance

We can see here that it is an object of the Carbon\Carbon class. The next thing we see is that there is a public property called date which is a string containing the date and the time. timezone_type is the next public property we see which is an integer with a value of 3, and a public property named timezone which is a string having the value of UTC. We’ll focus on that date property to start.

Using Carbon via Static Methods

A different approach we could use is to call static methods right off of the Carbon class without having to even new up an instance first. A useful method is the now() method. Let’s try it out right now.

Carbon::now()

    $carbon = Carbon::now();

    var_dump($carbon);

var dump of carbon now method

What we find when inspecting this instance with var_dump() is that we have the same type of object as when we took the approach of using the new keyword to create a new instance of the Carbon class. One might say this approach is slightly more readable, but it doesn’t really matter which you choose.

Carbon::today()

Carbon::today() is another method you can use and is just slightly different than Cabon::now(). You can use this when you’re not so much concerned at this exact moment in time, but rather simply what day it is. As such, this method only gives you the string representation of today and omits the time. We can see this by inspecting the var_dump and noticing that the time is all zeroes.

    $carbon = Carbon::today();

    var_dump($carbon);

ar dump of carbon today method

Carbon::tomorrow()

Carbon::tomorrow() is a useful method to dynamically determine the date of tomorrow. In our prior example, we saw the date as 11/11 of 2015. If this method works correctly, we should find a value of 11/12 of 2015 in our output.

    $carbon = Carbon::tomorrow();

    var_dump($carbon);

carbon tomorrow method

Excellent. Notice that the date did increment by one and we see the result of 11/12 of 2015.

Carbon::yesterday()

If we can easily return the value for tomorrow, it stands we should also be able to get the value of yesterday. Alas, this is quite easy with Carbon.

    $carbon = Carbon::yesterday();

    var_dump($carbon);

carbon yesterday method

This code is working just like we would expect it would, as it returns the value of 11/10 of 2015, which is a fine day indeed.

Carbon::create()

This method would be used to create an exact date and time of your choosing. This method depends on you passing in some arguments. We can view the source of the Carbon class to see what it expects.

    public static function create($year = null, $month = null, $day = null, $hour = null, $minute = null, $second = null, $tz = null)
    {
        $year = $year === null ? date('Y') : $year;
        $month = $month === null ? date('n') : $month;
        $day = $day === null ? date('j') : $day;

        if ($hour === null) {
            $hour = date('G');
            $minute = $minute === null ? date('i') : $minute;
            $second = $second === null ? date('s') : $second;
        } else {
            $minute = $minute === null ? 0 : $minute;
            $second = $second === null ? 0 : $second;
        }

        return static::createFromFormat('Y-n-j G:i:s', sprintf('%s-%s-%s %s:%02s:%02s', $year, $month, $day, $hour, $minute, $second), $tz);
    }

When using Carbon::create(), you would typically pass in the parameters of year, month, day, hour, minute, second, and timezone. We’ll test it out now.

    $carbon = Carbon::create(1999, 12, 31, 23, 59, 59);

    var_dump($carbon);

party like its 1999

This of course represents New Year’s Eve which was a Friday on December 31st of 1999 with exactly one second left until “Yeah, they say two thousand zero zero party over, Oops out of time, So tonight I’m gonna party like it’s 1999, Yeah.” You get the idea.

Carbon::createFromDate()

Maybe you need to create an object just based on the date, but not the time. This method is just what you need for that.

    $carbon = Carbon::createFromDate(1999, 12, 31);

    var_dump($carbon);

carbon createfromdate

This gives us the same date, however, the time is simply filled in with the current time rather than a specific time you provide as parameters to the method.

Carbon::createFromTime()

This method allows you to set a specific time of the current day.

    $carbon = Carbon::createFromTime(13, 35, 55);

    var_dump($carbon);

carbon createfromtime

Notice that the time is reflected as the values we passed in, while the date is an instance of today.

Carbon::createFromTimestamp

If you have a timestamp you would like to create a Carbon instance from, we can use this method.

    $carbon = Carbon::createFromTimestamp(0);

    var_dump($carbon);

unix time 1970 01 01

This is the birthday of the Unix operating system.

Let’s try something a timestamp that might be a little more applicable. http://www.unixtimestamp.com/ gives us the number of seconds which have passed since since Jan 01 1970. Let’s go ahead and pass in a timestamp from there.

    $carbon = Carbon::createFromTimestamp(1447271429);

    var_dump($carbon);

unix timestamp

Carbon For Dummies

Now that we’ve seen various ways to create an object of type Carbon, let’s look at the Creating a Carbon Instance for Dummies version. I say this because when you new up a Carbon instance, you can pass in a string in a human-readable form, and Carbon is smart enough to create what you are trying to achieve. For example, we can create a specific date like so.

    $carbon = new Carbon('November 5th 2013');

    var_dump($carbon);

    $carbon = new Carbon('5th November 2013');

    var_dump($carbon);

    $carbon = new Carbon('20131105');

    var_dump($carbon);

    $carbon = new Carbon('2013/11/5');

    var_dump($carbon);

    $carbon = new Carbon('13-11-05');

    var_dump($carbon);

    $carbon = new Carbon('2013-11-05');

    var_dump($carbon);

All of these are interpreted correctly by Carbon and PHP and provide the output like so.
carbon parent constructor

We can also pass in a string which represents something like 3 days ago or 4 days from now. In addition to this, you can specify plus or minus hours as well to get more granular. Here are a few examples.

    $carbon = new Carbon('-3 days');

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2015-11-08 21:31:13.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon = new Carbon('-4 weeks');

//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-14 21:33:08.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon = new Carbon('-5 years');

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2010-11-11 21:33:51.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon = new Carbon('+2 days 9 hours');

//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-11-14 06:35:06.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon = new Carbon('+3 weeks 4 days');

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2015-12-06 21:36:39.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon = new Carbon('+3 years 1 months 1 day 5 hours 33 minutes 25 seconds');

//  object(Carbon\Carbon)[142]
//  public 'date' => string '2018-12-13 03:12:44.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

This is pretty cool and we have covered most ways you would ever be creating an instance of Carbon manually. Now we can take a look at formatting dates with Carbon which is where Carbon really shines.

Formatting Dates and Time With Carbon

toDateString()

The first method of the Carbon class we’ll look at is toDateString(). It takes the date in the Carbon object and puts it into a nicely formatted date string.

    $carbon = new Carbon('-3 days');

    $formatted = $carbon->toDateString();

    var_dump($formatted);

//  string '2015-11-08' (length=10)

toTimeString()

The toTimeString() method formats the time in the Carbon object to a properly formatted time string.

    $carbon = new Carbon('-2 days 10 hours');

    $formatted = $carbon->toTimeString();

    var_dump($formatted);
//  string '08:26:32' (length=8)

What happened in this example is that since we did not actually provide a time in the constructor, the current time is used at the time of the code executing. We did however have a subtraction clause, and we were removing 10 hours, so that does get reflected in the time string.

toDateTimeString()

    $carbon = new Carbon('+5 days');

    $formatted = $carbon->toDateTimeString();

    var_dump($formatted);

//  string '2015-11-16 22:30:36' (length=19)

toAtomString()

You may format the the date and time as an atom string like so.

    $carbon = new Carbon('tomorrow');

    $formatted = $carbon->toAtomString();

    var_dump($formatted);

//  string '2015-11-12T00:00:00+00:00' (length=25)

toCookieString()

Formatting the date and time to the standard of a cookie is easy with the toCookieString() method.

    $carbon = new Carbon('next week');

    $formatted = $carbon->toCookieString();

    var_dump($formatted);

//  string 'Monday, 16-Nov-2015 22:37:20 UTC' (length=32)

toDayDateTimeString()

This is how the toDayDateTimeString() method works, and the output is very nice.

    $carbon = new Carbon('now');

    $formatted = $carbon->toDayDateTimeString();

    var_dump($formatted);

//  string 'Wed, Nov 11, 2015 10:39 PM' (length=26)

toFormattedDateString()

The toFormattedDateString() outputs your Carbon instance like so.

    $carbon = new Carbon('now');

    $formatted = $carbon->toFormattedDateString();

    var_dump($formatted);

//  string 'Nov 11, 2015' (length=12)

toIso8601String()

There are several standards based date and time formats. This one is for ISO 8601.

    $carbon = new Carbon('now');

    $formatted = $carbon->toIso8601String();

    var_dump($formatted);

//  string '2015-11-11T22:42:27+0000' (length=24)

toRfc822String()

We have built in support for RFC 822 via the toRfc822String() method.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc822String();

    var_dump($formatted);

//  string 'Wed, 11 Nov 15 22:46:44 +0000' (length=29)

toRfc850String()

Get your RFC 850 formatted strings out of your Carbon object with the toRfc850String() method.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc850String();

    var_dump($formatted);

//  string 'Wednesday, 11-Nov-15 22:53:09 UTC' (length=33)

toRfc1036String()

Formatting RFC 1036 date time is a breeze with the toRfc1036String() method.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc1036String();

    var_dump($formatted);

//  string 'Wed, 11 Nov 15 22:55:41 +0000' (length=29)

toRfc1123String()

This is how you can set the format to an RFC 1123 string.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc1123String();

    var_dump($formatted);

//  string 'Wed, 11 Nov 2015 22:57:56 +0000' (length=31)

toRfc2822String()

Are you in need of an RFC 2822 formatted string? You are in luck with the toRfc2822String() method.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc2822String();

    var_dump($formatted);

//  string 'Wed, 11 Nov 2015 22:59:52 +0000' (length=31)

toRfc3339String()

Maybe RFC 3339 is what you are looking for. The toRfc3339String() method is the one you need.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRfc3339String();

    var_dump($formatted);

//  string '2015-11-11T23:01:48+00:00' (length=25)

toRssString()

The toRssString() method quickly formats the date time to something compliant with an RSS feed.

    $carbon = new Carbon('now');

    $formatted = $carbon->toRssString();

    var_dump($formatted);

//  string 'Wed, 11 Nov 2015 23:03:47 +0000' (length=31)

toTimeString()

The toTimeString() method offers a way to output a very simple format like so.

    $carbon = new Carbon('now');

    $formatted = $carbon->toTimeString();

    var_dump($formatted);

//  string '23:04:20' (length=8)

toW3cString()

Easily format to the W3C string format with the toW3cString() method.

    $carbon = new Carbon('now');

    $formatted = $carbon->toW3cString();

    var_dump($formatted);

//  string '2015-11-11T23:07:01+00:00' (length=25)

All of these methods begin with to as we can see here. There is a bit of overlap between the names of the methods and the formats they provide, but what this does is allow you to structure your code in a way that makes the most sense possible to you. In other words, you have enough sugar to make things easier to reason about during development.

Now you might be thinking about the standard way we format dates in PHP when using things like strtotime(), DateTime and date_create() in native PHP. The same rules apply for Carbon, and if you prefer, you can simply use the format() method like so.

    $carbon = new Carbon('now');

    $formatted = $carbon->format('l');

    var_dump($formatted);
//  string 'Thursday' (length=8)
//--------------------------------------------------------//

    $formatted = $carbon->format('l jS \of F Y h:i:s A');

    var_dump($formatted);
//  string 'Thursday 12th of November 2015 01:33:57 AM' (length=42)
//--------------------------------------------------------//

    $formatted = $carbon->format(DATE_RFC2822);

    var_dump($formatted);
//  string 'Thu, 12 Nov 2015 01:33:57 +0000' (length=31)
//--------------------------------------------------------//

    $formatted = $carbon->format(DATE_ATOM);

    var_dump($formatted);
//  string '2015-11-12T01:33:57+00:00' (length=25)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('l \t\h\e jS');

    var_dump($formatted);
//  string 'Thursday the 12th' (length=17)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('F j, Y, g:i a');

    var_dump($formatted);
//  string 'November 12, 2015, 1:33 am' (length=26)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('"m.d.y');

    var_dump($formatted);
//  string '"11.12.15' (length=9)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('j, n, Y');

    var_dump($formatted);
//  string '12, 11, 2015' (length=12)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('Ymd');

    var_dump($formatted);
//  string '20151112' (length=8)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('\i\t \i\s \t\h\e jS \d\a\y.');

    var_dump($formatted);
//  string 'it is the 12th day.' (length=19)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('D M j G:i:s T Y');

    var_dump($formatted);
//  string 'Thu Nov 12 1:33:57 UTC 2015' (length=27)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('H:m:s \m \i\s\ \m\o\n\t\h');

    var_dump($formatted);
//  string '01:11:57 m is month' (length=19)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('H:i:s');

    var_dump($formatted);
//  string '01:33:57' (length=8)
//--------------------------------------------------------//
    
    $formatted = $carbon->format('Y-m-d H:i:s');

    var_dump($formatted);
//  string '2015-11-12 01:33:57' (length=19)

Behold diffForHumans() !

This is one of the coolest methods in the Carbon Library. What it does is to compare the current date and time to that which is stored in the current instance of Carbon. For example, the Carbon instance itself may hold a timestamp or some format of date and time from a few days ago, or perhaps even something in the future. The diffForHumans() method creates really nicely formatted and human-readable formats from this difference in time. Let’s see a few examples.

 $carbon = new Carbon('-5 days');

    $formatted = $carbon->diffForHumans();

    var_dump($formatted);
//  string '5 days ago' (length=10)
//--------------------------------------------------------// 
   
    $carbon = new Carbon('+2 hours');

    $formatted = $carbon->diffForHumans();

    var_dump($formatted);
//  string '2 hours from now' (length=16)
//--------------------------------------------------------//

    $carbon = new Carbon('-33 minutes');

    $formatted = $carbon->diffForHumans();

    var_dump($formatted);
//  string '33 minutes ago' (length=14)
//--------------------------------------------------------//

    $carbon = new Carbon('-55 seconds');

    $formatted = $carbon->diffForHumans();

    var_dump($formatted);
//  string '55 seconds ago' (length=14)

Carbon Getters

We already had a look at all of the ways we can format dates and times with Carbon. Now, what happens if you want to access say just the day, or just the hour, or just the minute you are interested in? Do you reformat the Carbon instance and then retrieve the values as you want? No, you don’t have to do that, you can make use of the special getter methods which will retrieve dates and times in the format you like. Let’s take a look at the source code that makes this possible since it will enlighten us on how Carbon is actually working its magic.

Getter Functionality

public function __get($name)
{
	switch (true) {
		case array_key_exists($name, $formats = array(
			'year' => 'Y',
			'yearIso' => 'o',
			'month' => 'n',
			'day' => 'j',
			'hour' => 'G',
			'minute' => 'i',
			'second' => 's',
			'micro' => 'u',
			'dayOfWeek' => 'w',
			'dayOfYear' => 'z',
			'weekOfYear' => 'W',
			'daysInMonth' => 't',
			'timestamp' => 'U',
		)):
			return (int) $this->format($formats[$name]);

		case $name === 'weekOfMonth':
			return (int) ceil($this->day / static::DAYS_PER_WEEK);

		case $name === 'age':
			return (int) $this->diffInYears();

		case $name === 'quarter':
			return (int) ceil($this->month / 3);

		case $name === 'offset':
			return $this->getOffset();

		case $name === 'offsetHours':
			return $this->getOffset() / static::SECONDS_PER_MINUTE / static::MINUTES_PER_HOUR;

		case $name === 'dst':
			return $this->format('I') === '1';

		case $name === 'local':
			return $this->offset === $this->copy()->setTimezone(date_default_timezone_get())->offset;

		case $name === 'utc':
			return $this->offset === 0;

		case $name === 'timezone' || $name === 'tz':
			return $this->getTimezone();

		case $name === 'timezoneName' || $name === 'tzName':
			return $this->getTimezone()->getName();

		default:
			throw new InvalidArgumentException(sprintf("Unknown getter '%s'", $name));
	}
}

This code now makes it extremely easy and convenient to do things as we see here giving us quick access to the integer values of all of the various parts of a date-time.

$carbon = new Carbon('now');

$carbon->year;  //  2015
$carbon->yearIso;  //  2015
$carbon->month;  //  11
$carbon->day;  //  12
$carbon->hour;  //  16
$carbon->minute;  //  5
$carbon->second;  //  1
$carbon->micro;  //  0
$carbon->dayOfWeek;  //  4
$carbon->dayOfYear;  //  315
$carbon->weekOfYear;  //  46
$carbon->daysInMonth;  //  30
$carbon->timestamp;  //  1447344301

Carbon Setters

Just as we have getters we can work within Carbon to make things easier for us, Carbon also provides a nice Setter functionality. Using setters in Carbon is another way to create an instance of a date-time in Carbon. Sometimes it is easier to explicitly set the year month day or hour manually, rather than to figure out how to properly pass in the right format to do so. Let’s have a look at the Carbon source code which makes these setters possible. We can see that it has support for setting the year, month, day, hour, minute, second, timestamp, and timezone. If you pass in something the code does not understand, it will throw an exception.

Setter Functionality

public function __set($name, $value)
{
	switch ($name) {
		case 'year':
			$this->setDate($value, $this->month, $this->day);
			break;

		case 'month':
			$this->setDate($this->year, $value, $this->day);
			break;

		case 'day':
			$this->setDate($this->year, $this->month, $value);
			break;

		case 'hour':
			$this->setTime($value, $this->minute, $this->second);
			break;

		case 'minute':
			$this->setTime($this->hour, $value, $this->second);
			break;

		case 'second':
			$this->setTime($this->hour, $this->minute, $value);
			break;

		case 'timestamp':
			parent::setTimestamp($value);
			break;

		case 'timezone':
		case 'tz':
			$this->setTimezone($value);
			break;

		default:
			throw new InvalidArgumentException(sprintf("Unknown setter '%s'", $name));
	}
}

Now consider we new up a Carbon instance like so.

    $carbon = new Carbon('now');

    var_dump($carbon);

We can inspect that instance and confirm it is what we might expect.
carbon instance

What happens however when we go ahead and set some of the values in that Carbon instance? Let’s find out! We will new up the instance, set some properties, then var dump it and also output the result as a formatted string.

    $carbon = new Carbon('now');

    $carbon->year = 2012;
    $carbon->month = 3;
    $carbon->day = 5;

    var_dump($carbon);

    echo $carbon->toDayDateTimeString();

carbon setters

So we see that we can easily set values on our Carbon instance and update it with ease.

Carbon Timezone

Carbon makes working with Timezones in PHP really easy. You can interact with timezones in Carbon via the property $timezone and its alias $tz. You will need to make sure, however, that you are using one of the supported timezones in PHP. For example, here is the list of supported timezones in America. With this knowledge, let us set up a new Carbon instance with the Time Zone of New York City.

    $carbon = Carbon::now('America/New_York');

    var_dump($carbon);

carbon timezone

Another way you might tackle implementing a Time Zone in Carbon is like so.

    $carbon = Carbon::createFromDate(2010, 5, 14, 'America/Chicago');

    var_dump($carbon);
    
//  object(Carbon\Carbon)[141]
//  public 'date' => string '2010-05-14 18:35:38.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'America/Chicago' (length=15)

If you would rather use a method instead of passing in an argument, you can also complete setting the time zone this way as well. Here are a few more ways we might to this.

    $carbon = Carbon::now();

    $carbon->tz('America/Denver');

    var_dump($carbon);

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2015-11-12 11:39:03.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'America/Denver' (length=14)


    $carbon = Carbon::now();

    $carbon->setTimezone('America/Phoenix');

    var_dump($carbon);

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2015-11-12 11:40:49.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'America/Phoenix' (length=15)


    $carbon = Carbon::now();

    $carbon->tz = 'America/Los_Angeles';

    var_dump($carbon);

//  object(Carbon\Carbon)[141]
//  public 'date' => string '2015-11-12 10:41:57.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'America/Los_Angeles' (length=19)

So we can see that Carbon is quite flexible, and you have several ways to accomplish the same task.

Manipulating Date and Time with Carbon

When you need to manipulate Dates and Times in raw PHP, things can get a bit messy. Carbon provides all kinds of useful methods that will take care of all the messy calculations for you and allows you to easily manipulate dates and times using much more readable syntax.

Add Days Using Carbon

 $carbon = Carbon::createFromDate(2015, 10, 30);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-30 18:47:21.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon->addDays(1);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-31 18:49:01.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon->addDays(10);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-11-10 18:51:25.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

carbon add methods

Subtract Days Using Carbon

Just as we can easily add a given number of days to a Carbon object, we can just as easily subtract days.

 $carbon = Carbon::createFromDate(2015, 10, 30);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-30 18:54:22.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon->subDays(1);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-29 18:54:22.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

    $carbon->subDays(10);

    var_dump($carbon);
//  object(Carbon\Carbon)[142]
//  public 'date' => string '2015-10-19 18:54:22.000000' (length=26)
//  public 'timezone_type' => int 3
//  public 'timezone' => string 'UTC' (length=3)

carbon subtract methods

This is really so slick. We can see that Carbon takes care of everything for us. If we happen to add so many days that it is going to go into the next month, Carbon is smart enough to adjust the month as well. There are a ton more methods you can use such as add(), addDay(), addDays(), addHour(), addHours(), addMinute(), addMinutes(), addMonth(), addMonthNoOverflow(), addMonths(), addMonthsNoOverflow(), addSecond(), addSeconds(), addWeek(), addWeekday(), addWeekdays(), addWeeks(), addYear(), addYears(), sub(), subDay(), subDays(), subHour(), subHours(), subMinute(), subMinutes(), subMonth(), subMonthNoOverflow(), subMonths(), subMonthsNoOverflow(), subSecond(), subSeconds(), subWeek(), subWeekday(), subWeekdays(), subWeeks(), subYear(), and subYears(). That’s a lot of methods to work with! Your best bet would be to test them out for yourself, and see what works best for your particular application.

Comparing Dates and Times in Carbon

Carbon allows you to compare two instances of Carbon in different ways to see how they relate. Are they greater than, less than, equal to, and so on. The best way to have a look at how this works is to just whip up a few examples.

Checking Date Equality

    $carbonone = new Carbon;
    $carbontwo = new Carbon('+5 days');

    if ($carbonone->eq($carbontwo)) {
        echo 'The two dates are equal!';
    } else {
        echo 'These two dates are not equal!';
    }

//  These two dates are not equal!

Checking Greater Than Values

    $carbonone = new Carbon;
    $carbontwo = new Carbon('+5 days');

    if ($carbontwo->gt($carbonone)) {
        echo 'Carbon 2 is greater than Carbon 1!';
    } else {
        echo 'Carbon 2 is *not* greater than Carbon 1!';
    }

    //  Carbon 2 is greater than Carbon 1!

Checking Less Than Values

    $carbonone = new Carbon;
    $carbontwo = new Carbon('+5 days');

    if ($carbonone->lt($carbontwo)) {
        echo 'Carbon 1 is less than Carbon 2!';
    } else {
        echo 'Carbon 1 is *not* less than Carbon 2!';
    }

    //  Carbon 1 is less than Carbon 2!

We can see how the gt(), lt(), and eq() methods work which allows us to quickly check for equality between two dates. In addition, you can use the gte() and lte() methods if you need to check for a greater than or equal to, and less than or equal to situation.

Checking Between Dates With Carbon

We have a nice between() method for checking where a date exists between two given dates. Let’s see how this works.

    $carbonone = new Carbon;
    $carbontwo = new Carbon('+5 days');
    $carbonthree = new Carbon('+1 year');

    if($carbonone->between($carbontwo, $carbonthree)){
        echo 'Carbon 1 is between Carbon 2 and Carbon 3!';
    } else {
        echo 'Carbon 1 is *not* between Carbon 2 and Carbon 3!';
    }

//    Carbon 1 is *not* between Carbon 2 and Carbon 3!

    if($carbontwo->between($carbonone, $carbonthree)){
        echo 'Carbon 2 is between Carbon 1 and Carbon 3!';
    } else {
        echo 'Carbon 2 is *not* between Carbon 1 and Carbon 3!';
    }

//    Carbon 2 is between Carbon 1 and Carbon 3!

Checking Date and Time Differences with Carbon

Calculating differences in dates is a very useful application that you can take advantage of. Carbon makes it pretty easy. Let’s imagine we have two cars. One was built in 1988 and the other was built in 2013. How can we check the difference between these two? Let’s see.

    $honda = new Carbon('January 10th 1988');
    $subaru = new Carbon('May 20th 2013');

    echo 'The Honda was built '.$honda->diffInYears($subaru).' years before the Subaru';

//  The Honda was built 25 years before the Subaru

Now just like everything else in Carbon, you have many more methods available to you.
date differences

Have a play and see what you can come up with.

Modifying Dates and Times with Carbon

When we talk about Modifiers, we’re looking at methods such as startOfDay(), startOfDecade(), startOfMonth(), startOfWeek(), startOfYear(), and their associated methods of endOfDay(), endOfDecade(), endOfMonth(), endOfWeek(), and endOfYear(). Should you have a need for it, there is also a startOfCentury() and endOfCentury() for you to work with. We can check out these examples.

    $carbon = Carbon::now();

    echo $carbon->endOfWeek()->toDayDateTimeString();
//  Sun, Nov 15, 2015 11:59 PM

    $carbon = Carbon::now();

    echo $carbon->startOfMonth()->toDayDateTimeString();
//  Sun, Nov 1, 2015 12:00 AM

    $carbon = Carbon::now();

    echo $carbon->startOfYear()->toDayDateTimeString();
//  Thu, Jan 1, 2015 12:00 AM

Carbon Next

The next() method is a really useful one in Carbon. How often do you talk to other people using the next nomenclature? You’ll be like, “Hey Tom, I’ll see you next week!” or “Jill, I don’t have a free night until next Wednesday” and so on and so forth. The next() method in Carbon accepts a dayOfWeek integer value, however, it is null by default. Recall that in PHP 0 is Sunday, and 6 is Saturday. Let’s try it out.

    $carbon = Carbon::now();

    echo 'Hey Julie, see you next '. $carbon->next(3)->format('l \t\h\e jS');

//  Hey Julie, see you next Wednesday the 18th

If we omit the argument to the next() method, it will just move forward one week starting from today. Today is Thursday as we write this, so this is what the output is when we combine with our handy toCookieString() formatting method.

    $carbon = Carbon::now();

    echo $carbon->next()->toCookieString();
//  Thursday, 19-Nov-2015 00:00:00 UTC

Carbon Previous

The complimentary method to next() is of course previous(). Let’s try it.

    $carbon = Carbon::now();

    echo $carbon->previous()->toCookieString();
//  Thursday, 05-Nov-2015 00:00:00 UTC

Carbon Copy

The copy() method is very important in Carbon. The reason is, if you call modifying methods on an instance of Carbon, that instance gets immediately updated directly. It is not a copy of the object, but a reference. Let’s see an example.

    $carbon = new Carbon('Thursday November 12th');

    $carbon->addDay();

    echo $carbon->format('l');
//  Friday

This works as expected. We create a Carbon instance based on a Thursday, add a day, and see that the output is now Friday. Check this out, however.

    $carbonone = new Carbon('Thursday November 12th');

    $carbontwo = $carbonone->addDay();

    if ($carbonone->eq($carbontwo)) {
        echo 'these days are equal';
    } else {
        echo 'these days are *not* equal';
    }
    
    // these days are equal

This is saying that $carbonone and $carbontwo are equal, is that right? It looks like $carbonone should be a Thursday and $carbontwo should be a Friday, why is this saying the days are equal? Let’s add in the copy() method to get something more consistent.

    $carbonone = new Carbon('Thursday November 12th');

    $carbontwo = $carbonone->copy()->addDay();

    if ($carbonone->eq($carbontwo)) {
        echo 'these days are equal';
    } else {
        echo 'these days are *not* equal';
    }

    // these days are *not* equal

This behavior is a little more consistent with what we might expect. In the first example, all we are doing is taking the original instance, adding a day, then assigning that to a new variable. The original variable holding the Carbon instance is also updated, however, much like you would expect with a reference or pointer type of situation.

The second example uses the copy() method to clone the object so that we can leave the original Carbon instance untouched. This way when you add fluently or chained calls onto the end of a Carbon instance which includes copy() within the chain, you can leave the original intact. I hope that makes sense. Let’s see one more example to drive it home.

This does not work correctly

    $today = Carbon::now();

    echo 'Today is '.$today->format('l').'<br>';

    $tomorrow = $today->addDay();

    echo 'Today is '.$today->format('l').' and Tomorrow is '.$tomorrow->format('l');

//  Today is Thursday
//  Today is Friday and Tomorrow is Friday

Adding the copy() method makes things work correctly

    $today = Carbon::now();

    echo 'Today is '.$today->format('l').'<br>';

    $tomorrow = $today->copy()->addDay();

    echo 'Today is '.$today->format('l').' and Tomorrow is '.$tomorrow->format('l');

//  Today is Thursday
//  Today is Thursday and Tomorrow is Friday

Carbon in the Real World

So you might be a little overwhelmed with the sheer number of ways you can interact with, update, modify and otherwise hack dates and times using the Carbon Library. I know this because that is exactly what I am thinking! In all seriousness, however, the best way to see how Carbon is used in the real world is to look at projects that actually use Carbon. The best example we could look at is Laravel Cashier, which makes heavy use of Carbon. Let’s see how.

Checking for a Trial period

    /**
     * Determine if the entity is within their trial period.
     *
     * @return bool
     */
    public function onTrial()
    {
        if (! is_null($this->getTrialEndDate())) {
            return Carbon::today()->lt($this->getTrialEndDate());
        } else {
            return false;
        }
    }

We can see use of the today() method (instantiation) and lt() method (comparison).

Checking for a Grace Period

    /**
     * Determine if the entity is on grace period after cancellation.
     *
     * @return bool
     */
    public function onGracePeriod()
    {
        if (! is_null($endsAt = $this->getSubscriptionEndDate())) {
            return Carbon::now()->lt(Carbon::instance($endsAt));
        } else {
            return false;
        }
    }

We can see use of the now() method (instantiation) and lt() method (comparison), as well as the instance() method (instantiation).

Creating a Carbon Instance from a Timestamp

    /**
     * Get a Carbon date for the invoice.
     *
     * @param  \DateTimeZone|string  $timezone
     * @return \Carbon\Carbon
     */
    public function date($timezone = null)
    {
        $carbon = Carbon::createFromTimestamp($this->date);

        return $timezone ? $carbon->setTimezone($timezone) : $carbon;
    }

Here we can see the code making use of the createFromTimestamp() method and setTimeZone() method which is fluent.

Calculating Remaining Trial Days

    /**
     * Calculate the remaining trial days based on the current trial end.
     *
     * @param  \Carbon\Carbon  $trialEnd
     * @return void
     */
    protected function calculateRemainingTrialDays($trialEnd)
    {
        // If there is still trial left on the current plan, we'll maintain that amount of
        // time on the new plan. If there is no time left on the trial we will force it
        // to skip any trials on this new plan, as this is the most expected actions.
        $diff = Carbon::now()->diffInHours($trialEnd);

        return $diff > 0 ? $this->trialFor(Carbon::now()->addHours($diff)) : $this->skipTrial();
    }

This gives us a good idea of how Carbon might be used in the real world with real code powering real transactions. Read through the source further on your own if you are interested!

Easy PHP Dates and Times With Carbon Summary

Like most lengthy tutorials, we are coming away from this with more knowledge about the topic than we began with. After testing all of these various methods for yourself in your own sandbox, you will come up with ideas on how to best implement Carbon in your own projects. In addition, we were able to examine Carbon usage in a real-world project by way of the popular Laravel Cashier package.

Click to share! ⬇️