Working with Dates and Times in PHP with Carbon


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 Aheadproject, a Laravel app for scheduling posts to social media sites like Facebook, Twitter and LinkedIn.


To install Carbon, you need to use Composer.

composer require nesbot/carbon Usage

Include the vendor autoload in your file and then use the Carbonclass in the Carbonnamespace.

<?phprequire_once 'vendor/autoload.php';use Carbon/Carbon;?> Getting the Current Date and Time

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

<?phpecho Carbon::now(); //2015-07-26 20:21:20?>

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

<?phpecho Carbon::now('Asia/Manila'); //2015-07-26 20:21:20?>

Aside from the nowmethod, 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.

<?phpecho Carbon::today()->toDateTimeString(); //2015-07-26 00:00:00echo Carbon::yesterday()->toDateTimeString(); //2015-07-25 00:00:00echo 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 echobecause of the __toStringmagic method. But if you want to convert it to a string, you can use the toDateStringor toDateTimeStringmethods.

<?phpecho Carbon::now()->toDateString(); //2015-07-26echo Carbon::now()->toDateTimeString(); //2015-07-26 20:22:50?> Parsing Dates

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

<?phpecho Carbon::parse('2015/03/30')->toDateTimeString(); //2015-03-30 00:00:00echo Carbon::parse('2015-03-30')->toDateTimeString(); //2015-03-30 00:00:00echo Carbon::parse('2015-03-30 00:10:25')->toDateTimeString(); //2015-03-30 00:10:25echo Carbon::parse('today')->toDateTimeString(); //2015-07-26 00:00:00echo Carbon::parse('yesterday')->toDateTimeString(); //2015-07-25 00:00:00echo Carbon::parse('tomorrow')->toDateTimeString(); //2015-07-27 00:00:00echo Carbon::parse('2 days ago')->toDateTimeString(); //2015-07-24 20:49:53echo Carbon::parse('+3 days')->toDateTimeString(); //2015-07-29 20:49:53echo Carbon::parse('+2 weeks')->toDateTimeString(); //2015-08-09 20:49:53echo Carbon::parse('+4 months')->toDateTimeString(); //2015-11-26 20:49:53echo Carbon::parse('-1 year')->toDateTimeString(); //2014-07-26 20:49:53echo Carbon::parse('next wednesday')->toDateTimeString(); //2015-07-29 00:00:00echo 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.

<?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 createand createFromDatemethods.

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 addDaysmethod. There’s also the modifymethod 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.

<?phpecho Carbon::now()->addDays(25); //2015-08-20 21:10:00echo Carbon::now()->addWeeks(3); //2015-08-16 21:10:00echo Carbon::now()->addHours(25); //2015-07-27 22:10:00echo Carbon::now()->subHours(2); //2015-07-26 19:10:00echo Carbon::now()->addHours(2)->addMinutes(12); //2015-07-26 23:22:00echo Carbon::now()->modify('+15 days'); //2015-08-10 21:10:00echo 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.

<?phpecho 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, isFutureand isPast.

Laravel Integration

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

'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 docsto learn more about it.