286 lines
9.1 KiB
ReStructuredText
286 lines
9.1 KiB
ReStructuredText
Chronos
|
|
#######
|
|
|
|
O Chronos oferece uma coleção independente de extensões para lidar com o objeto
|
|
``DateTime``. Além de métodos de conveniência, o Chronos oferece:
|
|
|
|
* Objetos ``Date`` para representar datas de calendário.
|
|
* Objetos *date* e *datetime* imutáveis.
|
|
* Um sistema de tradução acoplável. Apenas traduções em inglês estão incluídas
|
|
na biblioteca. Todavia, ``cakephp/i18n`` pode ser usado para suporte completo
|
|
a idiomas.
|
|
|
|
Instalação
|
|
----------
|
|
|
|
Para instalar o Chronos, você deve usar o ``composer``. A partir do diretório
|
|
*ROOT* de sua aplicação (local onde o arquivo composer.json está localizado)
|
|
execute o seguinte comando::
|
|
|
|
php composer.phar require cakephp/chronos "@stable"
|
|
|
|
Visão geral
|
|
-----------
|
|
|
|
Chronos oferece extensões para lidar com objetos *DateTime* do PHP. 5 classes
|
|
cobrem variantes de data/hora mutáveis e imutáveis e uma extensão do objeto
|
|
``DateInterval``.
|
|
|
|
* ``Cake\Chronos\Chronos`` é um objeto *date & time* imutável.
|
|
* ``Cake\Chronos\Date`` é um objeto *date* imutável.
|
|
* ``Cake\Chronos\MutableDateTime`` é um objeto *date and time* mutável.
|
|
* ``Cake\Chronos\MutableDate`` é um objeto *date* mutável.
|
|
* ``Cake\Chronos\ChronosInterval`` é uma extensão do objeto ``DateInterval``.
|
|
|
|
Por último, se você quiser usar o *typehint* em objetos do Chronos, será preciso
|
|
usar a interface ``Cake\Chronos\ChronosInterface``. Todos os objetos de data e
|
|
hora implementam essa interface.
|
|
|
|
Criando instâncias
|
|
------------------
|
|
|
|
Existem várias maneiras de criar instâncias do Chronos ou mesmo, do objeto Date.
|
|
Um número considerável de métodos padrão que funcionam com conjuntos diferentes
|
|
de argumentos::
|
|
|
|
use Cake\Chronos\Chronos;
|
|
|
|
$now = Chronos::now();
|
|
$today = Chronos::today();
|
|
$yesterday = Chronos::yesterday();
|
|
$tomorrow = Chronos::tomorrow();
|
|
|
|
// Interpreta expressões relativas.
|
|
$date = Chronos::parse('+2 days, +3 hours');
|
|
|
|
// Valores inteiros de Date e Time.
|
|
$date = Chronos::create(2015, 12, 25, 4, 32, 58);
|
|
|
|
// Valores inteiros de Date ou Time.
|
|
$date = Chronos::createFromDate(2015, 12, 25);
|
|
$date = Chronos::createFromTime(11, 45, 10);
|
|
|
|
// Interpreta valores formatados.
|
|
$date = Chronos::createFromFormat('m/d/Y', '06/15/2015');
|
|
|
|
Trabalhando com objetos imutáveis
|
|
---------------------------------
|
|
|
|
Se você é familiarizado com os objetos ``DateTime`` do PHP, você se sentirá
|
|
confortável com objetos *mutáveis*. Além de objetos mutáveis o Chronos também
|
|
oferece objetos imutáveis que por sua vez criam cópias de objetos toda vez que
|
|
um objeto é modificado. Devido ao fato de que metodos modificadores relativos
|
|
a data e hora nem sempre serem transparentes, informações podem ser modificadas
|
|
acidentalmente ou sem que o desenvolvedor saiba. Objetos imutáveis previnem
|
|
essas alterações acidentais nos dados. Imutabilidade significa que você deverá
|
|
lembrar de substituir variáveis usando modificadores::
|
|
|
|
// Esse código não funciona com objetos imutáveis
|
|
$time->addDay(1);
|
|
doSomething($time);
|
|
return $time;
|
|
|
|
// Esse funciona como o esperado
|
|
$time = $time->addDay(1);
|
|
$time = doSomething($time);
|
|
return $time;
|
|
|
|
Ao capturar o valor de retorno de cada modificação, seu código funcionará como o
|
|
esperado. Se você tem um objeto imutável e quer criar um mutável a partir do
|
|
mesmo, use ``toMutable()``::
|
|
|
|
$inplace = $time->toMutable();
|
|
|
|
Objetos Date
|
|
------------
|
|
|
|
O PHP disponibiliza um único objeto DateTime. Representar datas de calendário
|
|
pode ser um pouco desconfortável por essa classe, uma vez que ela inclui
|
|
*timezones* e componentes de hora que realmente não se encaixam no conceito de
|
|
'dia'. O Chronos oferece um objeto ``Date`` para representar datas. A hora e a
|
|
zona desse objeto é sempre fixado em ``00:00:00 UTC`` e todos os métodos de
|
|
formatação/diferença operam sob a resolução de dia::
|
|
|
|
use Cake\Chronos\Date;
|
|
|
|
$today = Date::today();
|
|
|
|
// Mudanças na hora/timezone são ignoradas
|
|
$today->modify('+1 hours');
|
|
|
|
// Exibe '2016-08-15'
|
|
echo $today;
|
|
|
|
Métodos modificadores
|
|
---------------------
|
|
|
|
Objetos Chronos disponibilizam métodos que permitem a modificação de valores de
|
|
forma granular::
|
|
|
|
// Define componentes do valor datetime
|
|
$halloween = Chronos::create()
|
|
->year(2015)
|
|
->month(10)
|
|
->day(31)
|
|
->hour(20)
|
|
->minute(30);
|
|
|
|
Você também pode modificar partes da data relativamente::
|
|
|
|
$future = Chronos::create()
|
|
->addYear(1)
|
|
->subMonth(2)
|
|
->addDays(15)
|
|
->addHours(20)
|
|
->subMinutes(2);
|
|
|
|
Também é possível realizar grandes saltos para períodos definidos no tempo::
|
|
|
|
$time = Chronos::create();
|
|
$time->startOfDay();
|
|
$time->startOfMonth();
|
|
$time->endOfMonth();
|
|
$time->endOfYear();
|
|
$time->startOfWeek();
|
|
$time->endOfWeek();
|
|
|
|
Ou ainda para dias específicos da semana::
|
|
|
|
$time->next(ChronosInterface::TUESDAY);
|
|
$time->previous(ChronosInterface::MONDAY);
|
|
|
|
Métodos de comparação
|
|
---------------------
|
|
|
|
Uma vez que você possui 2 instâncias de objetos data/hora do Chronos, é possível
|
|
compará-los de várias maneiras::
|
|
|
|
// Coleção completa de comparadores
|
|
// ne, gt, lt, lte.
|
|
$first->eq($second);
|
|
$first->gte($second);
|
|
|
|
// Veja se o objeto atual está entre outros
|
|
$now->between($start, $end);
|
|
|
|
// Encontre qual argumento está mais perto ou mais longe
|
|
$now->closest($june, $november);
|
|
$now->farthest($june, $november);
|
|
|
|
Você também pode arguir sobre quando um determinado valor cai no calendário::
|
|
|
|
$now->isToday();
|
|
$now->isYesterday();
|
|
$now->isFuture();
|
|
$now->isPast();
|
|
|
|
// Verifica se o dia é no final de semana
|
|
$now->isWeekend();
|
|
|
|
// Todos os métodos para outros dias da semana existem também
|
|
$now->isMonday();
|
|
|
|
Você também pode verificar se um determinado valor está dentro de um período de
|
|
tempo relativo::
|
|
|
|
$time->wasWithinLast('3 days');
|
|
$time->isWithinNext('3 hours');
|
|
|
|
Gerando diferenças
|
|
------------------
|
|
|
|
Em adição à comparação de *datetimes*, calcular diferenças ou deltas entre
|
|
valores é uma tarefa simples::
|
|
|
|
// Recebe um DateInterval representando a diferença
|
|
$first->diff($second);
|
|
|
|
// Recebe a diferença como um contador de unidades específicas
|
|
$first->diffInHours($second);
|
|
$first->diffInDays($second);
|
|
$first->diffInWeeks($second);
|
|
$first->diffInYears($second);
|
|
|
|
Você pode gerar diferenças de fácil leitura para humanos para usar em um *feed*
|
|
ou *timeline*::
|
|
|
|
// Diferença em relação ao momento atual
|
|
echo $date->diffForHumans();
|
|
|
|
// Diferença em relação a outro período no tempo
|
|
echo $date->diffForHumans($other); // 1 hora atrás;
|
|
|
|
Formatando strings
|
|
------------------
|
|
|
|
O Chronos disponibiliza métodos para exibir nossos objetos *datetime*::
|
|
|
|
// Usa o formato controlado por setToStringFormat()
|
|
echo $date;
|
|
|
|
// Diferentes padrões de formato
|
|
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
|
|
|
|
// Recebe o trimestre
|
|
echo $time->toQuarter(); // 4;
|
|
|
|
Extraindo componentes de data
|
|
-----------------------------
|
|
|
|
Podemos receber partes de um objeto *date* acessando propriedades::
|
|
|
|
$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
|
|
|
|
Outras propriedades que podem ser acessadas são:
|
|
|
|
- timezone
|
|
- timezoneName
|
|
- micro
|
|
- dayOfWeek
|
|
- dayOfMonth
|
|
- dayOfYear
|
|
- daysInMonth
|
|
- timestamp
|
|
- quarter
|
|
|
|
Auxílio para testes
|
|
-------------------
|
|
|
|
Ao escrever testes unitários, fixar a hora atual é bastante útil. O Chronos
|
|
lhe permite fixar a hora atual para cada classe. Como parte das suas ferramentas
|
|
de testes, você pode incluir o seguinte::
|
|
|
|
Chronos::setTestNow(Chronos::now());
|
|
MutableDateTime::setTestNow(MutableDateTime::now());
|
|
Date::setTestNow(Date::now());
|
|
MutableDate::setTestNow(MutableDate::now());
|
|
|
|
Isso irá corrigir a hora atual de todos os objetos para o momento em que o
|
|
processo de testes foi iniciado.
|
|
|
|
Por exemplo, se você fixar o ``Chronos`` em algum momento no passado, qualquer
|
|
nova instância do ``Chronos`` criada com ``now`` ou uma *string* de tempo
|
|
relativa, teremos um retorno referente ao tempo fixado::
|
|
|
|
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
|
|
|