Introduction

The Carbon class is inherited from the PHP DateTime class.

php

namespace Carbon;

class Carbon extends \DateTime
{
    // code here
}

You can see from the code snippet above that the Carbon class is declared in the Carbon namespace. You need to import the namespace to use Carbon without having to provide its fully qualified name each time.

php

use Carbon\Carbon;

Examples in this documentation will assume you imported classes of the Carbon namespace this way.

If you're using Laravel, you may check our Laravel configuration and best-practices recommendations.

If you're using Symfony, you may check our Symfony configuration and best-practices recommendations.

We also provide CarbonImmutable class extending DateTimeImmutable. The same methods are available on both classes but when you use a modifier on a Carbon instance, it modifies and returns the same instance, when you use it on CarbonImmutable, it returns a new instance with the new value.

php

$mutable = Carbon::now();
$immutable = CarbonImmutable::now();
$modifiedMutable = $mutable->add(1, 'day');
$modifiedImmutable = CarbonImmutable::now()->add(1, 'day');

var_dump($modifiedMutable === $mutable); // bool(true)
var_dump($mutable->isoFormat('dddd D')); // string(11) "Saturday 27"
var_dump($modifiedMutable->isoFormat('dddd D')); // string(11) "Saturday 27"

// So it means $mutable and $modifiedMutable are the same object
// both set to now + 1 day.
var_dump($modifiedImmutable === $immutable); // bool(false)
var_dump($immutable->isoFormat('dddd D')); // string(9) "Friday 26"
var_dump($modifiedImmutable->isoFormat('dddd D')); // string(11) "Saturday 27"

// While $immutable is still set to now and cannot be changed and
// $modifiedImmutable is a new instance created from $immutable
// set to now + 1 day.

$mutable = CarbonImmutable::now()->toMutable();
var_dump($mutable->isMutable()); // bool(true)
var_dump($mutable->isImmutable()); // bool(false)

$immutable = Carbon::now()->toImmutable();
var_dump($immutable->isMutable()); // bool(false)
var_dump($immutable->isImmutable()); // bool(true)

The library also provides CarbonInterface interface extends DateTimeInterface and JsonSerializable, CarbonInterval class extends DateInterval, CarbonTimeZone class extends DateTimeZone and CarbonPeriod class polyfills DatePeriod.

Carbon has all the functions inherited from the base DateTime class. This approach allows you to access the base functionality such as modify, format or getTimestamp.

Now, let's see how cool this documentation page is. Click on the code below:

php

$dtToronto = Carbon::create(2012, 1, 1, 0, 0, 0, 'America/Toronto');
$dtVancouver = Carbon::create(2012, 1, 1, 0, 0, 0, 'America/Vancouver');
// Try to replace the 4th number (hours) or the last argument (timezone) with
// Europe/Paris for example and see the actual result on the right hand.
// It's alive!

echo $dtVancouver->diffInHours($dtToronto);    // -3
// Now, try to double-click on "diffInHours" or "create" to open
// the References panel.
// Once the references panel is open, you can use the search field to
// filter the list or click the (<) button to close it.

Some examples are static snippets, some other are editable (when there is a top right hand corner expand button). You can also click on this button to open the snippet in a new tab. You can double-click on method names in both static and dynamic examples.

Introduction ​

Introduction