Blog do Beraldo

A partir do PHP 5.2.0, há uma maneira nativa e simples de se trabalhar com datas e horários, com ajuda da classe DateTime.

Neste artigo, vou mostrar algumas das utilidades dessa classe. Eu nunca a usei antes, estou aprendendo-a agora, enquanto monto o post. Logo, contribuições serão muito bem-vindas.

Vamos iniciar mostrando como funciona o construtor da classe.

Índice:
1. Construtor da classe
2. Formatando datas
3. Adicionando períodos a datas
4. Subtraindo períodos de uma data
5. Calculando diferença entre datas
6. Modificando a data e a hora do objeto

1. Construtor da classe

Sintaxe do construtor:

DateTime::__construct ([ string $time = "now" [, DateTimeZone $timezone = NULL ]] )

Esse método aceita dois parâmetros, ambos opcionais. O primeiro é a data/hora, no mesmo formato aceito pela função strftime(). O segundo consiste no timezone que deve ser utilizado. Ele deve ser uma instância da classe DateTimeZone. Outra maneira de definir o timezone é por meio da função date_default_timezone_set().

Ambas as classes DateTime e DateTimeZone disparam uma exceção se seus construtores receberem parâmetro inválidos. Logo, podemos usar blocos try/catch para instanciar essas classes.

try
{
	$DateTime = new DateTime( 'now', new DateTimeZone( 'America/Sao_Paulo') );
}
catch( Exception $e )
{
	echo 'Erro ao instanciar objeto.<br />';
	echo $e->getMessage();
	exit();
}

Experimente trocar o “now” por um valor não aceito pelo método, como uma string qualquer. Uma exceção será disparada.

2. Formatando datas

Para formatar datas, usamos o método format, que aceita um parâmetro, correspondente a uma formatação de data aceita pela função date().

$DateTime = new DateTime();
 
echo $DateTime->format( "d/m/Y H:i:s" ) . '<br />';
echo $DateTime->format( "Y-m-d H:i:s" ) . '<br />';
echo $DateTime->format( "Y/m/d H:i:s" ) . '<br />';

3. Adicionando períodos a datas

Com o método add(), podemos adicionar períodos à data salva no objeto DateTime. É possível adicionar períodos de dias, períodos de tempo ou ambos, seguindo a formatação aceita pelo método, que recebe um único parâmetro, o qual é uma instância da classe DateInterval, responsável por manipular os dados do período especificado.

Os períodos são especificados da seguinte maneira: períodos de dias são precedidos pela letra “P”, seguidas de inteiros e seus respectivos identificadores de tempo (“D” para dias, “M” para meses e “Y” para anos). Períodos de tempo são precedidos pela letra “T” e seguidos de inteiros e seus respectivos identificadores de unidade (“H” para horas, “M” para minutos e “S” para segundos).

$DateTime = new DateTime();
 
$DateTime->add( new DateInterval( "P30D" ) ); // adiciona 30 dias
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->add( new DateInterval( "P2M" ) ); // adiciona 2 meses
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->add( new DateInterval( "P5Y" ) ); // adiciona 5 anos
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->add( new DateInterval( "P5Y2M30D" ) ); // adiciona 30 dias, 2 meses e 5 anos
echo $DateTime->format( "d/m/Y" ) . '<br />';

Note que cada adição é feita com base na adição anterior, uma vez que cada soma modifica a data armazenada no objeto.

4. Subtraindo períodos de uma data

O método sub funciona da mesma forma que o add, com a mesma lista de parâmetros, mas, logicamente, em vez de adicionar períodos, ele os subtrai.

$DateTime = new DateTime();
 
$DateTime->sub( new DateInterval( "P30D" ) ); // subtrai 30 dias
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->sub( new DateInterval( "P2M" ) ); // subtrai 2 meses
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->sub( new DateInterval( "P5Y" ) ); // subtrai 5 anos
echo $DateTime->format( "d/m/Y" ) . '<br />';
 
$DateTime->sub( new DateInterval( "P5Y2M30D" ) ); // subtrai 30 dias, 2 meses e 5 anos
echo $DateTime->format( "d/m/Y" ) . '<br />';

5. Calculando diferença entre datas

Usando o método diff, podemos calcular o intervalo entre duas datas, com precisão de dias, meses, anos, horas, minutos e segundos. Esse método retorna uma instância da classe DateInterval, já citada anteriormente neste artigo.

$DateTime = new DateTime();
 
$diff = $DateTime->diff( new DateTime( '2009-02-14' ) );
 
echo "Diferença de:<br />
" . $diff->d . " dias<br />
" . $diff->m . " meses<br />
" . $diff->y . " anos<br />
" . $diff->h . " horas<br />
" . $diff->i . " minutos<br />
" . $diff->s . " segundos<br />
";

6. Modificando a data e a hora do objeto

Para modificar a data e a hora armazenadas no objeto, utilizamos os métodos setDate e setTime.

$DateTime = new DateTime();
 
echo $DateTime->format( "d/m/Y H:i" ) . '<br />';
 
$DateTime->setDate( 2007, 07, 07 );
$DateTime->setTime( 07, 27 );
 
echo $DateTime->format( "d/m/Y H:i" ) . '<br />';

Espero que tenha ficado tudo claro para todos. A utilização das classes não é difícil. Mais informações podem ser obtidas na documentação oficial.

Link úteis:
Documentação da classe DateTime
Documentação da classe DateTimeZone
Documentação da classe DateTimeInterval
Funções de data e hora do PHP