Wern Ancheta

Adventures in Web Development.

Working With Dates and Times in PHP With Carbon

| Comments

When writing PHP applications there’s often a need for working with dates and times. In this tutorial, I’ll be walking you through Carbon, a simple PHP API extension for the DateTime class. It basically makes working with dates and times a lot more easier. I’ve personally used this library on my Ahead project, a Laravel app for scheduling posts to social media sites like Facebook, Twitter and LinkedIn.

Installation

To install Carbon, you need to use Composer.

1
composer require nesbot/carbon

Usage

Include the vendor autoload in your file and then use the Carbon class in the Carbon namespace.

1
2
3
4
5
<?php
require_once 'vendor/autoload.php';

use Carbon\Carbon;
?>

Getting the Current Date and Time

You can get the current date and time using the now method. If you do not specify an argument, it uses the default timezone from your PHP config.

1
2
3
<?php
echo Carbon::now(); //2015-07-26 20:21:20
?>

If you want to use a different timezone, you can pass a valid timezone as the argument.

1
2
3
<?php
echo Carbon::now('Asia/Manila'); //2015-07-26 20:21:20
?>

Aside from the now method, there’s also today, which returns the start of today’s date, yesterday, which returns the start of the date yesterday, and tomorrow, which returns the start of the date tomorrow.

1
2
3
4
5
<?php
echo Carbon::today()->toDateTimeString(); //2015-07-26 00:00:00
echo Carbon::yesterday()->toDateTimeString(); //2015-07-25 00:00:00
echo Carbon::tomorrow()->toDateTimeString(); //2015-07-27 00:00:00
?>

Converting to String

By default, methods in Carbon returns a datetime object. Though its an object, you can directly output it using echo because of the __toString magic method. But if you want to convert it to a string, you can use the toDateString or toDateTimeString methods.

1
2
3
4
<?php
echo Carbon::now()->toDateString(); //2015-07-26
echo Carbon::now()->toDateTimeString(); //2015-07-26 20:22:50
?>

Parsing Dates

You can also parse dates in all sorts of formats using the parse method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?php
echo Carbon::parse('2015/03/30')->toDateTimeString(); //2015-03-30 00:00:00
echo Carbon::parse('2015-03-30')->toDateTimeString(); //2015-03-30 00:00:00
echo Carbon::parse('2015-03-30 00:10:25')->toDateTimeString(); //2015-03-30 00:10:25

echo Carbon::parse('today')->toDateTimeString(); //2015-07-26 00:00:00
echo Carbon::parse('yesterday')->toDateTimeString(); //2015-07-25 00:00:00
echo Carbon::parse('tomorrow')->toDateTimeString(); //2015-07-27 00:00:00
echo Carbon::parse('2 days ago')->toDateTimeString(); //2015-07-24 20:49:53
echo Carbon::parse('+3 days')->toDateTimeString(); //2015-07-29 20:49:53
echo Carbon::parse('+2 weeks')->toDateTimeString(); //2015-08-09 20:49:53
echo Carbon::parse('+4 months')->toDateTimeString(); //2015-11-26 20:49:53
echo Carbon::parse('-1 year')->toDateTimeString(); //2014-07-26 20:49:53
echo Carbon::parse('next wednesday')->toDateTimeString(); //2015-07-29 00:00:00
echo Carbon::parse('last friday')->toDateTimeString(); //2015-07-24 00:00:00
?>

Constructing Dates

You can also construct dates by using individual parts such as the year month and day.

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
$year = '2015';
$month = '04';
$day = '12';

echo Carbon::createFromDate($year, $month, $day); //2015-04-12 20:55:59

$hour = '02';
$minute = '15':
$second = '30';

echo Carbon::create($year, $month, $day, $hour, $minute, $second); //2015-04-12 02:15:30
?>

Optionally, you can pass in any valid timezone as the last argument for the create and createFromDate methods.

Manipulating Dates

Manipulating dates can be done by using add (to add) or sub (to subtract) followed by the unit of time you want to add or subtract. For example, you want to add a specific number of days to the specific date, you use the addDays method. There’s also the modify method which allows you to pass in the modification that you want. It takes the format of + or - followed by the unit value and the unit. So if you want to add a year to the current date, you use +1 year. Check out the examples below to have an idea what else you can do.

1
2
3
4
5
6
7
8
9
<?php
echo Carbon::now()->addDays(25); //2015-08-20 21:10:00
echo Carbon::now()->addWeeks(3); //2015-08-16 21:10:00
echo Carbon::now()->addHours(25); //2015-07-27 22:10:00
echo Carbon::now()->subHours(2); //2015-07-26 19:10:00
echo Carbon::now()->addHours(2)->addMinutes(12); //2015-07-26 23:22:00
echo Carbon::now()->modify('+15 days'); //2015-08-10 21:10:00
echo Carbon::now()->modify('-2 days'); //2015-07-24 21:10:00
?>

Commonly in PHP apps are international. This means that you need to work with different timezones. Here’s how to convert from one timezone to another.

1
2
3
<?php
echo Carbon::now()->setTimezone('America/Los_Angeles'); //2015-07-26 06:23:48
?>

Comparing Dates

You can use the following methods to compare dates in Carbon.

  • min – returns the smaller date.
  • max – returns the larger date.
  • eq – check if two dates are the same.
  • gt – check if the first date is greater than the second date.
  • lt – check if the first date is less than the second date.
  • gte – check if the first date is greater than or equal to the second date.
  • lte – check if the first date is lesser than or equal to the second date.

Other helpful methods include isWeekDay, isWeekend, isYesterday, isFuture and isPast.

Laravel Integration

If you’re on Laravel, you can just add an alias for the Carbon library in the aliases in the app/config/app.php.

1
'Carbon' => 'Carbon\Carbon'

Conclusion

That’s it! In this tutorial, you’ve learned how to work with the Carbon library in PHP. Carbon is a really nice and easy way to work with dates in PHP. Be sure to check out the official docs to learn more about it.

Comments