307 lines
10 KiB
ReStructuredText
307 lines
10 KiB
ReStructuredText
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
|
|
inclues dans la librairie. Cependant, ``cakephp/i18n`` peut être utilisé
|
|
pour un support complet d'autres langues.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Pour installer Chronos, vous devez utiliser ``composer``. A partir du répertoire
|
|
ROOT de votre application (où le fichier composer.json se trouve) exécutez ce
|
|
qui suit::
|
|
|
|
php composer.phar require cakephp/chronos "@stable"
|
|
|
|
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 time* immutable.
|
|
* ``Cake\Chronos\Date`` est un objet de *date* immutable.
|
|
* ``Cake\Chronos\MutableDateTime`` est un objet de *date et time* mutable.
|
|
* ``Cake\Chronos\MutableDate`` est un objet de *date* mutable.
|
|
* ``Cake\Chronos\ChronosInterval`` est une extension pour l'objet
|
|
``DateInterval``.
|
|
|
|
Enfin si vous voulez typer selon les objets date/time fournis par Chronos,
|
|
vous devez utiliser ``Cake\Chronos\ChronosInterface``. Tous les objets date et
|
|
time implémentent cette interface.
|
|
|
|
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 des ensembles
|
|
ayant des arguments différents::
|
|
|
|
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');
|
|
|
|
// Les valeurs d'entier de Date et time.
|
|
$date = Chronos::create(2015, 12, 25, 4, 32, 58);
|
|
|
|
// Les valeurs d'entier pour Date ou time.
|
|
$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
|
|
dans le 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\Date;
|
|
|
|
$today = Date::today();
|
|
|
|
// Changements selon le time/timezone sont ignorés.
|
|
$today->modify('+1 hours');
|
|
|
|
// Affiche '2015-12-20'
|
|
echo $today;
|
|
|
|
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(ChronosInterface::TUESDAY);
|
|
$time->previous(ChronosInterface::MONDAY);
|
|
|
|
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::
|
|
|
|
// Suite complète de comparateurs existante
|
|
// ne, gt, lt, lte.
|
|
$first->eq($second);
|
|
$first->gte($second);
|
|
|
|
// Regardez 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');
|
|
$time->year; // 2015
|
|
$time->month; // 12
|
|
$time->day; // 31
|
|
$time->hour // 23
|
|
$time->minute // 59
|
|
$time->second // 58
|
|
|
|
Les autres propriétés accessibles sont:
|
|
|
|
- timezone
|
|
- timezoneName
|
|
- micro
|
|
- dayOfWeek
|
|
- dayOfMonth
|
|
- dayOfYear
|
|
- daysInMonth
|
|
- timestamp
|
|
- quarter
|
|
|
|
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());
|
|
Date::setTestNow(Date::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.
|