date_modify()

Este guia aborda o método DateTime::modify() do PHP (o equivalente orientado a objetos da função procedural date_modify()). Explica como modify() interpreta strings de data relativa, o que retorna, o problema de estouro de mês que confunde a maioria dos desenvolvedores e como evitar a mutação acidental de uma data.

O que é DateTime::modify()?

modify() é um método nativo da classe DateTime que altera a data/hora armazenada usando uma string de formato relativo como +10 days, -3 months ou next monday. Use-o sempre que precisar de aritmética de datas — avançar um prazo, retroceder um timestamp ou pular para o próximo dia útil — sem calcular manualmente os segundos.

Dois aspectos tornam o modify() distinto e vale a pena fixar na mente antes de ler os exemplos:

• Ele muda o objeto no lugar — altera o mesmo DateTime em que é chamado, em vez de retornar uma nova cópia.
• Ele aceita a mesma gramática de formato relativo que o PHP usa ao construir datas a partir de strings, portanto tudo que new DateTime('+1 week') entende, modify() também entende.

Sintaxe

public DateTime::modify(string $modifier): DateTime|false

• $modifier — uma string de formato relativo (ex.: +1 day, -2 weeks, first day of next month, 14:00).
• Retorna o mesmo objeto DateTime em caso de sucesso (permitindo encadear chamadas), ou false em caso de falha (por exemplo, uma string que não pode ser interpretada).

Como retorna o próprio objeto, estas duas linhas são equivalentes — o $date original é modificado em ambos os casos:

$date->modify('+1 day');          // mutates $date, return value ignored
$date = $date->modify('+1 day');  // mutates $date AND reassigns the same object

Dica: Quando $modifier vem de entrada do usuário, sempre verifique se o retorno é false antes de usar o resultado, pois uma string malformada retorna false em vez de lançar uma exceção.

Exemplos

Exemplo 1: Adicionando dias a uma data

Para adicionar 10 dias a uma data fixa com tratamento básico de erros:

Adicionando dias a uma data em PHP

Saída:

2023-03-11

Exemplo 2: Subtraindo meses de uma data

Para subtrair 3 meses de uma data fixa:

Subtraindo meses de uma data em PHP

Saída:

2022-12-01

Exemplo 3: Definindo a hora para um valor específico

Para definir a hora para 14h em uma data fixa:

Definindo a hora para um valor específico em PHP

Saída:

2023-03-01 14:00:00

Observe que modify('14:00') define a parte do horário para 14h, mas deixa a data intacta — formatos relativos que mencionam apenas um horário atuam sobre o horário, não sobre o dia.

Exemplo 4: Combinando várias unidades em uma única chamada

É possível empilhar múltiplas unidades relativas em uma única string de modificação, separadas por espaços. Elas são aplicadas da esquerda para a direita:

<?php

$date = new DateTime('2023-03-01');
$date->modify('+1 week +2 days');
echo $date->format('Y-m-d');

Saída:

2023-03-10

O problema de estouro de mês

Adicionar ou subtrair meses não limita ao último dia de um mês mais curto — ocorre um estouro para o mês seguinte. Veja o que acontece ao adicionar um mês a 31 de janeiro:

<?php

$date = new DateTime('2023-01-31');
$date->modify('+1 month');
echo $date->format('Y-m-d');

Saída:

2023-03-03

Como fevereiro de 2023 tem apenas 28 dias, "31 de janeiro + 1 mês" cai no inexistente "31 de fevereiro," que o PHP converte para 3 de março. Se você precisar do último dia do próximo mês, use um formato relativo absoluto:

<?php

$date = new DateTime('2023-01-31');
$date->modify('last day of next month');
echo $date->format('Y-m-d');

Saída:

2023-02-28

Evite mutação acidental com DateTimeImmutable

Como modify() altera o objeto no lugar, compartilhar um único DateTime em seu código pode causar bugs difíceis de encontrar — modificá-lo em um lugar afeta todas as referências a ele. Se você quiser que cada operação retorne um novo valor e deixe o original intacto, use DateTimeImmutable, cujo modify() retorna um novo objeto:

<?php

$original = new DateTimeImmutable('2023-03-01');
$nextWeek = $original->modify('+7 days');

echo $original->format('Y-m-d') . "\n"; // unchanged
echo $nextWeek->format('Y-m-d');

Saída:

2023-03-01
2023-03-08

Formatos relativos úteis

modify() aceita uma gramática rica de expressões relativas. Alguns exemplos comuns:

Funções relacionadas

• date_add() — adiciona um DateInterval a uma data.
• date_sub() — subtrai um DateInterval de uma data.
• date_diff() — obtém a diferença entre duas datas.
• date_format() — formata um objeto DateTime como string.

Resumo

DateTime::modify() aplica uma string de formato relativo a uma data, mutando o objeto no lugar e retornando-o (ou false em caso de falha). É ideal para aritmética de datas e para pular para dias nomeados, mas lembre-se de dois pontos: a aritmética de meses pode causar estouro em meses mais curtos, e a mutação é compartilhada — use DateTimeImmutable quando precisar preservar o original.

Prática