Page Contents

Chronos

Chronos fournit une collection d’extensions sans aucune dépendance pour l’objet DateTime. En plus de méthodes pratiques, Chronos fournit:

  • Des objets Date pour représenter les dates du calendrier.

  • Des objets immutables pour les dates et les datetimes.

  • Un système de traduction intégrable. Seules les traductions anglaises sont incluses dans la librairie. Cependant, cakephp/i18n peut être utilisé pour un support complet d’autres langues.

Installation

Pour installer Chronos, vous devez utiliser composer. À partir du répertoire ROOT de votre application (celui où se trouve le fichier composer.json), exécutez ce qui suit:

php composer.phar require "cakephp/chronos:^2.0"

Vue d’Ensemble

Chronos fournit un certain nombre d’extensions pour les objets DateTime fournis par PHP. Chronos fournit 5 classes qui gèrent les variantes mutables et immutables de date/time et les extensions de DateInterval.

  • Cake\Chronos\Chronos est un objet de date et heure immutable.

  • Cake\Chronos\ChronosDate est un objet de date immutable.

  • Cake\Chronos\MutableDateTime est un objet de date et heure mutable.

  • Cake\Chronos\MutableDate est un objet de date mutable.

  • Cake\Chronos\ChronosInterval est une extension pour l’objet DateInterval.

Créer des Instances

Il y a plusieurs façons d’obtenir une instance de Chronos ou de Date. Il y a un certain nombre de méthodes factory qui fonctionnent avec différents ensembles d’arguments:

use Cake\Chronos\Chronos;

$now = Chronos::now();
$today = Chronos::today();
$yesterday = Chronos::yesterday();
$tomorrow = Chronos::tomorrow();

// Parse les expressions relatives
$date = Chronos::parse('+2 days, +3 hours');

// Des entiers indiquant la date et l'heure.
$date = Chronos::create(2015, 12, 25, 4, 32, 58);

// Des entiers indiquant la date ou l'heure.
$date = Chronos::createFromDate(2015, 12, 25);
$date = Chronos::createFromTime(11, 45, 10);

// Parse les valeurs formatées.
$date = Chronos::createFromFormat('m/d/Y', '06/15/2015');

Travailler avec les Objets Immutables

Si vous avez utilisé les objets DateTime de PHP, vous êtes à l’aise avec les objets mutable. Chronos offre des objets mutables, mais elle fournit également des objets immutables. Les objets Immutables créent des copies des objets à chaque fois qu’un objet est modifié. Puisque les méthodes de modification autour des datetimes ne sont pas toujours transparentes, les données peuvent être modifiées accidentellement ou sans que le développeur ne le sache. Les objets immutables évitent les changements accidentels des données et permettent de s’affranchir de tout problème lié à l’ordre d’appel des fonctions ou des dépendances. L’immutabilité signifie que vous devez vous souvenir de remplacer les variables quand vous utilisez les modificateurs:

// Ce code ne fonctionne pas avec les objets immutables
$time->addDay(1);
doSomething($time);
return $time;

// Ceci fonctionne comme vous le souhaitez
$time = $time->addDay(1);
$time = doSomething($time);
return $time;

En capturant la valeur de retour pour chaque modification, votre code fonctionnera comme souhaité. Si vous avez déjà créé un objet immutable, et que vous souhaitez un objet mutable, vous pouvez utiliser toMutable():

$inplace = $time->toMutable();

Objets Date

PHP fournit seulement un unique objet DateTime. Représenter les dates de calendrier peut être un peu gênant avec cette classe puisqu’elle inclut les timezones, et les composants de time qui n’appartiennent pas vraiment au concept d’un “jour”. Chronos fournit un objet Date qui vous permet de représenter les dates. Les time et timezone pour ces objets sont toujours fixés à 00:00:00 UTC et toutes les méthodes de formatage/différence fonctionnent au niveau du jour:

use Cake\Chronos\ChronosDate;

$today = ChronosDate::today();

// Les changements selon le time/timezone sont ignorés.
$today->modify('+1 hours');

// Affiche '2015-12-20'
echo $today;

Bien que Date utilise en interne un fuseau horaire fixe, vous pouvez spécifier le fuseau à utiliser pour l’heure courante telle que now() ou today():

use Cake\Chronos\ChronosDate:

// Prend l'heure courante pour le fuseau horaire de Tokyo
$today = ChronosDate::today('Asia/Tokyo');

Méthodes de Modification

Les objets Chronos fournissent des méthodes de modification qui vous laissent modifier la valeur d’une façon assez précise:

// Définit les composants de la valeur du datetime.
$halloween = Chronos::create()
    ->year(2015)
    ->month(10)
    ->day(31)
    ->hour(20)
    ->minute(30);

Vous pouvez aussi modifier les parties de la date de façon relative:

$future = Chronos::create()
    ->addYear(1)
    ->subMonth(2)
    ->addDays(15)
    ->addHours(20)
    ->subMinutes(2);

Il est également possible de faire des sauts vers des points définis dans le temps:

$time = Chronos::create();
$time->startOfDay();
$time->endOfDay();
$time->startOfMonth();
$time->endOfMonth();
$time->startOfYear();
$time->endOfYear();
$time->startOfWeek();
$time->endOfWeek();

Ou de sauter à un jour spécifique de la semaine:

$time->next(Chronos::TUESDAY);
$time->previous(Chronos::MONDAY);

Quand vous modifiez des dates/heures au-delà d’un passage à l’heure d’été ou à l’heure d’hiver, vous opérations peuvent gagner/perdre une heure de plus, de sorte que les heures seront incorrectes. Vous pouvez éviter ce problème en définissant d’abord le timezone à UTC, ce qui change l’heure:

// Une heure de plus de gagnée.
$time = new Chronos('2014-03-30 00:00:00', 'Europe/London');
debug($time->modify('+24 hours')); // 2014-03-31 01:00:00

// Passez d'abord à UTC, et modifiez ensuite
$time = $time->setTimezone('UTC')
    ->modify('+24 hours');

Une fois que vous avez modifié l’heure, vous pouvez repasser au timezone d’origine pour obtenir l’heure locale.

Méthodes de Comparaison

Une fois que vous avez 2 instances d’objets date/time de Chronos, vous pouvez les comparer de plusieurs façons:

// Il existe une suite complète de comparateurs
// equals, notEquals, greaterThan, greaterThanOrEquals, lessThan, lessThanOrEquals
$first->equals($second);
$first->greaterThanOrEquals($second);

// Regarder si l'objet courant est entre deux autres.
$now->between($start, $end);

// Trouver l'argument le plus proche ou le plus éloigné.
$now->closest($june, $november);
$now->farthest($june, $november);

Vous pouvez aussi vous renseigner sur le moment où une valeur donnée tombe dans le calendrier:

$now->isToday();
$now->isYesterday();
$now->isFuture();
$now->isPast();

// Vérifie le jour de la semaine
$now->isWeekend();

// Toutes les autres méthodes des jours de la semaine existent aussi.
$now->isMonday();

Vous pouvez aussi trouver si une valeur était dans une période de temps relative:

$time->wasWithinLast('3 days');
$time->isWithinNext('3 hours');

Générer des Différences

En plus de comparer les datetimes, calculer les différences ou les deltas entre des valeurs est une tâche courante:

// Récupère un DateInterval représentant la différence
$first->diff($second);

// Récupère la différence en tant que nombre d'unités spécifiques.
$first->diffInHours($second);
$first->diffInDays($second);
$first->diffInWeeks($second);
$first->diffInYears($second);

Vous pouvez générer des différences lisibles qui peuvent vous servir pour l’utilisation d’un feed ou d’une timeline:

// Différence à partir de maintenant.
echo $date->diffForHumans();

// Différence à partir d'un autre point du temps.
echo $date->diffForHumans($other); // 1 hour ago;

Formater les Chaînes

Chronos fournit un certain nombre de méthodes pour afficher nos sorties d’objets datetime:

// Utilise le format contrôlé par setToStringFormat()
echo $date;

// Différents formats standards
echo $time->toAtomString();      // 1975-12-25T14:15:16-05:00
echo $time->toCookieString();    // Thursday, 25-Dec-1975 14:15:16 EST
echo $time->toIso8601String();   // 1975-12-25T14:15:16-05:00
echo $time->toRfc822String();    // Thu, 25 Dec 75 14:15:16 -0500
echo $time->toRfc850String();    // Thursday, 25-Dec-75 14:15:16 EST
echo $time->toRfc1036String();   // Thu, 25 Dec 75 14:15:16 -0500
echo $time->toRfc1123String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time->toRfc2822String();   // Thu, 25 Dec 1975 14:15:16 -0500
echo $time->toRfc3339String();   // 1975-12-25T14:15:16-05:00
echo $time->toRssString();       // Thu, 25 Dec 1975 14:15:16 -0500
echo $time->toW3cString();       // 1975-12-25T14:15:16-05:00

// Récupère le trimestre
echo $time->toQuarter();         // 4;
// Récupère la semaine
echo $time->toWeek();            // 52;

// Formatage générique
echo $time->toTimeString();           // 14:15:16
echo $time->toDateString();           // 1975-12-25
echo $time->toDateTimeString();       // 1975-12-25 14:15:16
echo $time->toFormattedDateString();  // Dec 25, 1975
echo $time->toDayDateTimeString();    // Thu, Dec 25, 1975 2:15 PM

Extraire des Fragments de Date

Il est possible de récupérer des parties d’un objet date en accédant directement à ses propriétés:

$time = new Chronos('2015-12-31 23:59:58.123');
$time->year;    // 2015
$time->month;   // 12
$time->day;     // 31
$time->hour     // 23
$time->minute   // 59
$time->second   // 58
$time->micro    // 123

Les autres propriétés accessibles sont:

  • timezone

  • timezoneName

  • dayOfWeek

  • dayOfMonth

  • dayOfYear

  • daysInMonth

  • timestamp

  • quarter

  • half

Aides aux Tests

Quand vous écrivez des tests unitaires, il peut être utile de fixer le time courant. Chronos vous permet de fixer le time courant pour chaque classe. Pour l’intégrer dans votre processus de démarrage (bootstrap) de suite de tests, vous pouvez inclure ce qui suit:

Chronos::setTestNow(Chronos::now());
MutableDateTime::setTestNow(MutableDateTime::now());
ChronosDate::setTestNow(ChronosDate::parse(Chronos::now()));
MutableDate::setTestNow(MutableDate::now());

Ceci va fixer le time courant de tous les objets selon le moment où la suite de tests a démarré.

Par exemple, si vous fixez le Chronos à un moment du passé, chaque nouvelle instance de Chronos créée avec now ou une chaine de temps relative, sera retournée relativement à la date fixée:

Chronos::setTestNow(new Chronos('1975-12-25 00:00:00'));

$time = new Chronos(); // 1975-12-25 00:00:00
$time = new Chronos('1 hour ago'); // 1975-12-24 23:00:00

Pour réinitialiser la « fixation » du temps, appelez simplement setTestNow() sans paramètre ou avec null comme paramètre.