PHP: Usando a classe nativa DateTime

PHP: Usando a classe nativa DateTime

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
7. Criando objeto DateTime a partir de uma data no formato brasileiro

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
{
    $DT = new DateTime( 'now', new DateTimeZone( 'America/Sao_Paulo') );
}
catch( Exception $e )
{
    echo 'Erro ao instanciar objeto.
';
    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.

Também é possível instanciar a classe com uma data fixa, desde que siga o padrão internacional, da ISO 8601, que é o mesmo usado por strtotime, por exemplo:

$DateTime = new DateTime( '2010-11-01' );

Ainda é possível criar um objeto DateTime a partir de uma data que não esteja no formato da ISO 8601. Mostrarei um exemplo prático de como fazer isso na Seção 7 deste tutorial. Não perca! Continue lendo! :)

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().

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

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).

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

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.

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

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.

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

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.

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

7. Criando objeto DateTime a partir de uma data no formato brasileiro

Para criarmos um objeto DateTime usando o construtor da classe, é necessário que a data esteja no formato internacional, conforme a ISO 8601. Porém, é possível criar um objeto DateTime a partir de uma data em qualquer outro formato. Basta usarmos o método createFromFormat. Veja um exemplo:

$dataBR = '01/11/2010';
$DT = DateTime::createFromFormat( 'd/m/Y', $dataBR );

Assim, a variávle $DateTime será uma instância da classe DateTime, e você pode usar quaisquer métodos que vimos anteriormente. Se dermor um var_dump nela, veremos o seguinte:

class DateTime#1 (3) {
  public $date =>
  string(26) "2010-11-01 15:34:38.000000"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(17) "America/Sao_Paulo"
}

Portanto, a variável $DT é, de fato, instância da classe DateTime.

 

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

 

Aprenda Ainda Mais

15 Dicas, Boas Práticas e Fundamentos do PHP

Conheça Dicas FUNDAMENTAIS para programar em PHP de forma Profissional

Não se considere Programador PHP sem antes ler este guia e adotar estas práticas!

Baixe gratuitamente este guia com 15 Dicas de PHP

The following two tabs change content below.
Graduado em Ciência da Computação, pela Universidade Federal do Paraná (UFPR), é desenvolvedor de software desde 2008, com foco em Desenvolvimento Web com PHP.