Pular para o conteúdo
Setup do Dev
Programação

Por que 31 de janeiro mais um mês dá 3 de março no PHP

O +1 month do PHP transborda o dia que não existe, e a cobrança do dia 31 escorrega para o dia 3. Testamos o problema e uma função que soma meses certo.

Por Setup do Dev
4 min de leitura
Compartilhar
Capa roxa com a manchete "31 de janeiro + 1 mês", o resultado 3 de março em amarelo e um terminal com o modify do PHP.

Uma mensalidade que vence no dia 31 de janeiro, com o próximo vencimento calculado por modify('+1 month'), cai em 3 de março. Não é bug de servidor nem de fuso: é o comportamento documentado do PHP, e o manual do DateTime::modify tem um aviso só para ele, “Beware when adding or subtracting months”.

Testamos no PHP 8.5.7 o que acontece, onde dói e como somar meses do jeito que uma pessoa espera.

O que o PHP faz

O +1 month aumenta o número do mês e mantém o dia. Se o dia não existe no mês novo, ele transborda para o seguinte: 31 de fevereiro vira 3 de março, porque fevereiro de 2026 tem 28 dias.

2026-01-28 +1 month = 2026-02-28
2026-01-29 +1 month = 2026-03-01
2026-01-30 +1 month = 2026-03-02
2026-01-31 +1 month = 2026-03-03
2028-01-31 +1 month = 2028-03-02   (2028 é bissexto)
2026-03-31 +1 month = 2026-05-01
2026-08-31 +1 month = 2026-10-01

O strtotime, o modify() e o add(new DateInterval('P1M')) deram o mesmo resultado. A subtração tem o mesmo problema: 31 de março menos um mês deu 3 de março, e não 28 de fevereiro.

Onde isso vira dinheiro

O estrago maior vem quando cada vencimento é calculado a partir do anterior. Uma cobrança que começou em 31 de janeiro saiu assim, somando +1 month à data de antes:

2026-01-31  2026-03-03  2026-04-03  2026-05-03  2026-06-03

O cliente que escolheu o dia 31 passou a pagar no dia 3, e fevereiro ficou sem cobrança. Com DateTime mutável ainda há um segundo susto: o modify() muda o próprio objeto e devolve ele mesmo, então a variável que guardava 31 de janeiro também passa a valer 3 de março. No teste, as duas variáveis eram o mesmo objeto.

Tabela com seis vencimentos. Somando +1 month à data anterior: 31/01, 03/03, 03/04, 03/05, 03/06. Com a função que soma a partir da data original: 31/01, 28/02, 31/03, 30/04, 31/05, 30/06. Embaixo, o PostgreSQL: 31/01 mais 1 mês dá 28/02.
A mensalidade do dia 31 somando +1 month a cada mês, e com a soma a partir da data original

Os atalhos que o PHP tem

Os formatos relativos incluem duas frases que ajudam. last day of next month a partir de 31 de janeiro deu 28 de fevereiro, e first day of +1 month deu 1º de fevereiro. Servem quando a regra é “último dia do mês” ou “primeiro dia”, mas não resolvem a cobrança do dia 30, que precisa ficar no 30 quando o mês tem 30 dias e cair no 28 em fevereiro.

Uma função que soma meses sem pular

A ideia é ir para o primeiro dia do mês, somar os meses (o dia 1 sempre existe) e só então pôr o dia de volta, limitado ao último dia daquele mês:

function somarMeses(DateTimeImmutable $base, int $meses): DateTimeImmutable
{
    $alvo   = $base->modify('first day of this month')->modify("+$meses month");
    $ultimo = (int) $alvo->format('t');
    $dia    = min((int) $base->format('j'), $ultimo);

    return $alvo->setDate((int) $alvo->format('Y'), (int) $alvo->format('n'), $dia);
}

A regra que evita o escorregão: calcule sempre a partir da data original, com o número de meses (somarMeses($inicio, 3)), e nunca a partir do vencimento anterior. No teste, a partir de 31 de janeiro de 2026, os seis primeiros vencimentos saíram 31/01, 28/02, 31/03, 30/04, 31/05 e 30/06. Em 2028 fevereiro deu 29, 31 de março menos um mês deu 28 de fevereiro, 31 de dezembro mais dois meses deu 28 de fevereiro de 2027, e a hora (14h30) se manteve.

A conta ao contrário: quantos meses se passaram?

O diff() tem a mesma régua, e ela engana quem confere “a assinatura já completou um mês?”. De 31 de janeiro a 28 de fevereiro, ele respondeu 0 meses e 28 dias. De 31 de janeiro a 1º de março, 0 meses e 29 dias. Só em 3 de março apareceu 1 mês, e de 28 de fevereiro a 31 de março deu 1 mês e 3 dias. Se a regra do seu sistema é “fez aniversário de mês”, compare com a data que a somarMeses() calcula, e não com o ->m do diff().

Vale guardar essas datas como casos de teste da função de cobrança: 31 de janeiro, o 29 de fevereiro de 2028, 31 de março menos um mês e a virada de dezembro para fevereiro. São exatamente os casos que passam despercebidos num teste feito com o dia 15.

E o banco de dados?

O PostgreSQL faz diferente, e isso pega quem calcula o vencimento num lugar e confere no outro. A documentação dele diz que, se o dia não existe no mês novo, vale o último dia daquele mês. No nosso teste, date '2026-01-31' + interval '1 month' deu 28 de fevereiro, e não 3 de março. Mas a soma em cadeia também escorrega lá: dois + interval '1 month' seguidos deram 28 de março, e + interval '2 months' de uma vez deu 31 de março. A regra de partir da data original vale nos dois lados. Se a sua tabela guarda horário, vale ler também o guia de timestamp e timestamptz.

Fontes: Manual do PHP: DateTime::modify, Manual do PHP: formatos relativos, Documentação do PostgreSQL: funções de data e hora

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. O que o PHP faz
  2. Onde isso vira dinheiro
  3. Os atalhos que o PHP tem
  4. Uma função que soma meses sem pular
  5. A conta ao contrário: quantos meses se passaram?
  6. E o banco de dados?

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.