Trabalhando e manipulando datas com a classe DateTime no PHP

Saber trabalhar e manipular datas é algo de muita importância e praticamente imprescindível para o desenvolvimento e manutenção de sistemas computacionais, por isso o objetivo desse artigo é abordar de forma conceitual e prática como podemos fazer isso utilizando à linguagem de programação PHP de forma moderna com a classe DateTime e suas classes auxiliares.

Inicialmente vamos começar falando sobre a classe DateTime, ela é uma classe que foi introduzida à princípio no PHP a partir de sua versão 5.2, ela provém uma interface orientada a objetos que possibilita que possamos trabalhar e fazer manipulação de datas, com ela você poderá desde simplesmente pegar a data atual e fazer sua exibição de forma formatada como também fazer a realização de modificações a manipulações mais avançadas utilizando intervalos de tempo e muito mais.

Sendo assim, vamos começar a utilizá-la fazendo alguns exemplos básicos de sua utilização para ver como ela funciona, para isso inicialmente vamos aprender como podemos criar objetos de instância dessa classe trabalhando com os seus parâmetros de seu método construtor.

Exibição e formatação básica de datas

No primeiro exemplo apresentado simplesmente vou criar uma instância da classe DateTime, suprimindo seus dois parâmetros que são opcionais, onde seu primeiro parâmetro refere-se a passagem de uma string que representará a data a qual você quer obter e caso esse parâmetro não seja passado a data padrão que será obtida virá a ser a data atual do servidor de onde o script PHP está rodando, e seu segundo parâmetro é referente ao fuso horário que será configurado para o objeto de data que irá ser criado e caso ele não seja passado o fuso horário padrão que será utilizado será o atual configurado no servidor mais especificamente o que é configurado no arquivo php.ini.

Nesse exemplo acima a data que será obtida será a data atual do servidor por padrão, onde nele está sendo utilizado o método format do objeto da classe DateTime que permite que nós possamos formatar a string de data que será apresentada, nesse método é passado uma string que representará o formato da data a qual nós queremos obter, esse formato de string se chama Format Characters (Caracteres de formatação). Existem também alguns formatos padronizados pré-definidos como constantes na classe DateTime que nós podemos utilizá-los, como poderemos ver no exemplo abaixo algumas dessas constantes em uso.

Para obter a lista completa das constantes padronizadas pré-definidas de formatos de datas da classe DateTime acesse o seguinte link DateTime Constants.

Contudo, você também pode criar suas próprias formatações de datas customizadas em um formato especifico, utilizando os Format Characters, como podemos ver no seguinte exemplo.

Passado datas especificas e obtendo datas relativas

Com a classe DateTime também podemos passar uma determinada data a qual pretendemos usar, podemos fazer isso passada essa data no seu primeiro parâmetro de seu construtor no formato Date and Time Formats. Isso é muito usado quando estamos trabalhando com datas obtidas de registros em banco de dados, onde seu formato é YYYY-MM-DD HH:MM:SS.

Ou também podemos definir uma determinada data e tempo usando os métodos setDate e setTime ao invés de passar nossa data pelo método construtor da classe DateTime, porém dessa forma teríamos mais trabalho caso nossa data esteja em formato de string, pois temos que passar cada valor da data e tempo individualmente como parâmetro, como podemos ver a seguir.

Além disso, também podemos definir uma determinada data relativamente à data atual passado uma string de Relative Formats como veremos no seguinte exemplo.

Como podemos ver no exemplo acima, é possível pegar as datas relativas a data atual, como a data de ontem (Yesterday), hoje (Today), agora (Now), amanhã (Tomorrow) e algumas outras datas com Relative Formats passando os como primeiro parâmetro do construtor da classe DateTime. Sendo que quando instanciamos essa classe e não passamos esse primeiro parâmetro, o valor default (padrão) que será assumido será o Relative Format Now, que a princípio aparenta ser semelhante ao Relative Format Today, pois suas datas são as mesmas, porém a diferença entre essas datas está no time (tempo) delas que não são os mesmos, onde o time da data Now é o horário atual do servidor de onde o script PHP está em execução e o time do Today é o horário inicial desse dia 00:00:01.

Usando as strings de Relative Format também é possível obter datas relativas a partir de uma determinada adição ou subtração de dias, semanas, meses ou anos, como se segue no seguinte exemplo.

Lembrando também que ao usar essa adição ou subtração de períodos usando Relative Formats, devemos levar em consideração a quantidade numérica que estamos usando, se ela está no singular ou plural, pois ao usar as strings de período de tempo devemos coloca-las na forma correta, por exemplo ‘+ 1 day’, ‘- 3 days’, ‘+ 1 month’, ‘+ 10 months’ e assim por diante.

Determinado o fuso horário de uma data

Determinar o fuso horário a ser utilizando é de grande importância dependendo da localização dos usuários os quais irão acessar nosso sistema, então para que possamos fazer essa configuração em uma determinada data a qual estamos utilizando, simplesmente teremos que passar um objeto da classe DateTimeZone, como segundo parâmetro no momento de instanciar à classe DateTime, onde no objeto da classe DateTimeZone nós configuraremos qual fuso horário iremos utilizar, isso será feito passado uma string com o nome do fuso horário no seu método construtor como primeiro e único parâmetro, como veremos no exemplo a seguir.

Como poderemos ver no exemplo anterior ao rodar esse script serão apresentadas três datas e horas diferentes cada uma delas correspondendo ao seu fuso horário configurado.

Caso não telhamos definido o fuso horário no momento da criação de nosso objeto da classe DateTime ou queremos alterá-lo, também poderemos defini-lo ou alterá-lo utilizando o método setTimezone a qualquer momento, da seguinte forma que veremos no exemplo abaixo.

Agora se você quiser configurar outros Timezones (Fuso horários), você pode acessar a listar completa com todos os Timezones suportados pelo PHP no seguinte link List of Supported Timezones.

Comparação entre duas datas

Utilizando a classe DateTime para manipular datas, possibilita que nós possamos comparar datas de forma muito simples utilizando estruturas condicionais com expressões boolianas.

Como podemos ver no exemplo anterior, é possível comparar se uma data é maior ou menor que outra simplesmente usando expressões boolianas comparando nossos objetos da classe da DateTime.

Agora se quiséssemos pegar o intervalo de tempo de diferença entre duas datas com mais precisão, podemos usar o método diff da classe DateTime a qual nos retorna um objeto da classe DateInterval com todos os dados referentes a diferença entre as duas datas que estão sendo usadas na comparação.

O exemplo anterior irá resultar no seguinte objeto que está sendo apresentado na imagem abaixo, onde podemos ver que nele contém todos os dados como quantidade de meses, dias, horas e etc., referentes as duas datas.

Objeto DateInterval

O objeto da classe DateInterval que é retornado também nos fornece o método format, que possibilita que nós possamos formatar e exibir o período de tempo que é retornado, como pode-se ver no exemplo abaixo.

Manipulando datas

Outra funcionalidade que a classe DateTime nos fornece é a manipulação de datas, possibilitando que nós possamos fazer a adição ou subtração de intervalos de tempo em nossas datas pré-definidas no momento de sua criação, como veremos no exemplo a seguir.

No exemplo anterior usamos o método add para fazer a adição de 40 dias à nossa data, e como se pode observar nesse exemplo foi preciso passar um objeto da classe DateInterval que representa essa quantidade de dias que serão adicionadas a nossa data, onde também podemos observar que essa representação é feita a partir de uma string de Period Designators que é passada no primeiro parâmetro do construtor da classe DateInterval.

Agora no próximo exemplo será mostrado como fazer a subtração de um determinado intervalo de tempo que é algo tão simples como fazer a adição.

Nesse exemplo foi feito a subtração de três anos e dois meses de nossa data com a utilização do método sub, de forma semelhante a como foi feito quando utilizamos o método add passando uma instância da classe DateInterval onde definimos o intervalo de tempo a ser subtraído a partir de uma string de Period Designators que agora veremos como ela funciona.

Para forma essa string de designação de período devemos colocar a primeira letra de nossa string sempre iniciando com a letra P que vez de period (período) posteriormente deveremos definir um valor inteiro com a duração do período seguido por um Period Designator (Designador de Período). A seguinte tabela mostra todos os Period Designators que podemos usar e suas devidas descrições.

Tabela de Period Designators

A seguir temos alguns exemplos de como forma essa string para definir períodos de tempo:

  • P40D: Período de 40 dias
  • P1Y20M3D: Período de 1 ano, 20 meses e 3 dias
  • P3M10D: Período de 3 meses e 10 dias

Agora se quiséssemos definir tempo em nossa string deveremos preceder esse tempo pela letra T que vez de time (tempo) como veremos nos seguintes exemplos:

  • P1YT10H55S: Período de um ano e 10 horas e 55 segundos
  • PT5H30M20S: Período de tempo de 5 horas, 30 minutos e 20 segundos.
  • P1Y4M10DT2H30M50S: Período de 1 ano, 4 meses, 10 dias, 2 horas, 30 minutos e 50 segundos.

Esses exemplos ficariam da seguinte forma em formato de código utilizando a classe DateInterval:

A classe DateInterval também fornece outra forma de definimos o período de tempo a qual queremos usar, utilizando seu método estático createFromDateString que permite que nós possamos criar nosso período de tempo a partir de Relative Formats como já utilizamos anteriormente, porém nós passamos essa string como parâmetro do construtor da classe DateTime, mas agora passaremos essa string para o método createFromDateString. Como veremos no exemplo a seguir.

Modificando datas

Nós podemos fazer modificações de adição ou subtração de períodos de tempo em nossas datas a partir do método modify da classe DateTime, isso de princípio aparenta ser semelhante aos métodos add e sub, mas usando um método só ou invés de dois, porém existe uma diferença em relação à esses métodos e essa diferença vem do fato que o tipo de entrada de seus parâmetros são diferentes, onde nos métodos add e sub, nós temos que passar um objeto da classe DateInterval para podemos fazer a manipulação de nossas datas, contudo no método modify o que passamos é uma string de Relative Formats para podemos definir qual período de tempo queremos usar para modificamos nossa data, assim como veremos no exemplo a seguir.

Conclusão

No decorrer desse artigo foi possível ver o quanto a classe DateTime pode nós ajudar quando precisamos manipular datas em nosso sistema. Vimos como é fácil criar objetos dessa classe e fazer a sua formatação de apresentação utilizando o método format com a string de Format Characters, fizemos a configuração de fuso horário de nossas datas utilizando a classe DateTimeZone.

Posteriormente também vimos como podemos fazer comparação entre datas utilizando expressões boolianas de forma muito simples, e também como saber qual é a diferença de intervalo de tempo de duas datas usando o método diff que nos retorna um objeto da classe DateInterval com todos esses dados para que possamos analisá-los.

Depois disso aprendemos como trabalhar com manipulação de datas fazendo adição e subtração de período de tempo usando os métodos add e sub em conjunto com à classe DateInterval, onde com ela definíamos o período de tempo usando Period Designators ou se não usando Relative Formats com o método estático createFromDateString dessa classe.

E para finalizar vimos como fazer modificações em nossos objetos de datas usando o método modify de tal forma como os métodos add e sub nos permiti, porém ao invés de passamos um objeto da classe DateInterval, simplesmente passamos como parâmetro uma string de Relative Formats.

Contudo, ainda existem muitas peculiaridades que podem ser estudadas em relação à manipulação de datas utilizando à classe DateTime que não foram abordadas nesse artigo, e caso você queira aprender mais sobre elas acesse sua documentação completa no seguinte link PHP Data e Hora.


Se gostou do artigo dê like ❤️e me siga, para acompanhar novos artigos. Mas se gostou muito, compartilha que ficarei muito grato. E sinta-se à vontade para fazer comentários, sobre dúvidas, críticas construtivas (ou não), melhorias e agradecimentos.

Like what you read? Give Yure Pereira a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.