Everything you need to know about Carbon within Laravel

If you’re using Laravel, Carbon is provided out of the box. Carbon extends the \DateTime class of PHP. You need to import Carbon with it fully qualified namespace to use it.

use Carbon\Carbon;

Within Laravel

Sometimes you may see your IDE suggests importing \Illuminate\Support\Carbon this does the same as importing Carbon\Carbon, as this class of the Laravel framework only extends the Carbon base class.

Laravel contains two Carbon helpers to create a new Carbon instance.

1. today() this creates a new instance for the current date — this is the same as Carbon::today()
2. now() this creates a new instance for the current time — this is the same as Carbon::now()

Create a Carbon instance from a date string

You can create a new Carbon instance from a string with a date(time) using the methods createFromFormat and parse. We will explain the difference between both methods below.

If your date input input isn’t a common format, it’s a good practice to use the method createFromFormat.

$format = 'd/m/Y'; // this format is not supported
$input = '18/04/2022';
$date = Carbon::createFromFormat($format, $input);

If your date input string is a common format, you can use the method parse.

$input = '18-04-2022';
$date = Carbon::parse($input);

The PHP date methods handles dates by default in the US date format. US dates have the format month/day/year. European countries use the format day–month–year. If your date input string contains a / it will try to parse it using the US date format (mm/dd/yyyy). While if your date input string contains a - it will try to parse it using the European date format (dd-mm-yyyy).

So if you try to parse ‘18/04/2022’ it will fail, because it uses the US date format with forward slashes but the day and month are in the wrong order. In the US format the month comes before the day, the example is using the European order.

In the list below, we list the most common formats and whether they’re correct or incorrect.

04/18/2022 // correct
18/04/2022 // incorrect
18-04-2022 // correct
04-18-2022 // incorrect
2022-04-18 // correct
2022/04/18 // correct

Always include time zones when saving dates

You should always save your dates and timestamps including the time zone. When it is 18:00 in Amsterdam it is 19:00 in London. In Tokyo it could be Monday while in New York it is still Sunday. Build your app in such a way that you can use it multiple time zones.

Save all your dates in your database in the same time zone. This allows you to easily sort and compare dates. A good practice is to always use UTC unless all your users will be based in another time zone.

CarbonInterval

CarbonInterval represents a date interval. A date interval is a fixed amount of time (in seconds, minutes, hours, days, months, etc.) between 2 Carbon instances. You can also use the diff method between two Carbon instances to get the interval.

$date1 = Carbon::create(2022, 01, 15, 8);
$date2 = Carbon::create(2022, 04, 18, 12);
$interval = $date->diff($date2);
$interval->days; // 93
$interval->m; // 3 (months)
$interval->h; // 4 (hours)

CarbonPeriod

CarbonPeriod represents a date period. A period allows you to iterate within the period at a regular interval.

$period = new CarbonPeriod('2022-02-14', '2022-05-01');
foreach($period as $date) {
    echo $date->toDateString(); // 2022-02-14, 2022-02-15 etc.
}

CarbonTimeZone

CarbonTimezone is the representation of the time zones.

$timezone = new CarbonTimeZone('Europe/Amsterdam');
$timezone->getName(); // Europe/Amsterdam
$timezone->getAbbr(true); // cest (true to incl. DST)
$timezone->toOffsetName(); // +02:00

CarbonImmutable

CarbonImmutable extends the \DateTimeImmutable class. All methods that are available on the Carbon instance are also available on the CarbonImmutable instance. The only difference is that when you modify a Carbon instance, it modifies and returns the same instance. When you use CarbonImmutable it always returns a new instance.

Sometimes you’ll find yourself asking why two dates in your Laravel always return the same date, while you tried to set 2 different dates. Probably you used the first instance to set the second variable. But while setting the second variable, you unintentionally also changed the value of the first instance.

Common Carbon Examples

now()->format('Y-m-d'); // 2022-04-18
now()->translatedFormat('l d F Y'); // maandag 18 april 2022
now()->subDays(2)->diffForHumans(); // 2 days ago
now()->locale('nl')->monthName; // April
now()->isoFormat('LLLL'); // maandag 8 maart 2022 20:00
now()->subWeeks(3)->longAbsoluteDiffForHumans(); // 3 weeks
now()->toDateString(); // 2022-04-18
now()->toFormattedDateString(); // Apr 18, 2022
now()->toTimeString(); // 20:00:00
now()->toDateTimeString(); // 2022-04-18 20:00:00
Carbon::create('18-03-2022')->diffForHumans(); // 1 month ago
Carbon::create('18-04-2000')->age; // 22

You can use the following constants for the day of the weeks.

Carbon::SUNDAY // 0
Carbon::MONDAY // 1
Carbon::TUESDAY // 2
Carbon::WEDNESDAY // 3
Carbon::THURSDAY // 4
Carbon::FRIDAY // 5
Carbon::SATURDAY // 6

You can use the following constants for the months.

Carbon::JANUARY // 1
Carbon::FEBRUARY // 2
Carbon::MARCH // 3
Carbon::APRIL // 4
Carbon::MAY // 5
Carbon::JUNE // 6
Carbon::JULY // 7
Carbon::AUGUST // 8
Carbon::SEPTEMBER // 9
Carbon::OCTOBER // 10
Carbon::NOVEMBER // 11
Carbon::DECEMBER // 12

You can use PHP to get a list of all time zones.

DateTimeZone::listIdentifiers(DateTimeZone::ALL);