Chronos focuses on providing immutable date/datetime objects. Immutable objects help ensure that datetime objects aren't accidentally modified keeping data more predictable.
Installing with composer:
$ composer require cakephp/chronos
You can then use Chronos:
<?php
require 'vendor/autoload.php';
use Cake\Chronos\Chronos;
printf("Now: %s", Chronos::now());
Chronos was originally compatible with Carbon but has diverged and no longer extends the PHP DateTime and DateTimeImmutable classes.
Immutable objects have a number of advantages:
- Using immutable objects is always free of side-effects.
- Dates and times don't accidentally change underneath other parts of your code.
With those benefits in mind, there are a few things you need to keep in mind when modifying immutable objects:
// This will lose modifications
$date = new Chronos('2015-10-21 16:29:00');
$date->modify(' 2 hours');
// This will keep modifications
$date = new Chronos('2015-10-21 16:29:00');
$date = $date->modify(' 2 hours');
PHP only offers datetime objects as part of the native extensions. Chronos adds
a number of conveniences to the traditional DateTime object and introduces
a ChronosDate
object. ChronosDate
instances their time frozen to 00:00:00
and the timezone
set to the server default timezone. This makes them ideal when working with
calendar dates as the time components will always match.
use Cake\Chronos\ChronosDate;
$today = new ChronosDate();
echo $today;
// Outputs '2015-10-21'
echo $today->modify(' 3 hours');
// Outputs '2015-10-21'
Like instances of Chronos
, ChronosDate
objects are also immutable.
A more descriptive documentation can be found at book.cakephp.org/chronos/3/en/.
API documentation can be found on api.cakephp.org/chronos.