init
This commit is contained in:
Sebastian Molenda
+329
@@ -0,0 +1,329 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user