date_isodate_set()

A função date_isodate_set() define a data de um objeto DateTime usando o calendário baseado em semanas da ISO 8601 — ou seja, por ano, número de semana e dia da semana, em vez de mês e dia. É o alias procedural do método DateTime::setISODate(), portanto ambos fazem exatamente a mesma coisa.

Esta página aborda a sintaxe da função, como o calendário de semanas ISO difere do calendário comum, exemplos executáveis e os erros mais comuns.

Sintaxe

A função date_isodate_set() tem a seguinte sintaxe:

Sintaxe da função PHP date_isodate_set()

date_isodate_set(DateTime $object, int $year, int $week, int $dayOfWeek = 1): DateTime

onde:

• $object — o objeto DateTime a ser modificado (é alterado no lugar).
• $year — o ano ISO.
• $week — o número da semana ISO, 1–53.
• $dayOfWeek — o dia da semana, 1 para segunda-feira até 7 para domingo (opcional, padrão 1).

A função retorna o mesmo objeto DateTime, portanto as chamadas podem ser encadeadas. A chamada equivalente orientada a objetos é:

$date->setISODate($year, $week, $dayOfWeek);

Por que usar datas de semana ISO

Ao contrário do calendário comum, a ISO 8601 numera cada semana do ano e identifica uma data por (ano, semana, dia da semana). Isso é útil para relatórios de negócios, agendamento e qualquer sistema que pensa em semanas em vez de meses.

Duas regras valem a pena lembrar:

• A semana 1 é a semana que contém a primeira quinta-feira do ano — equivalentemente, a semana que contém o dia 4 de janeiro. Por causa disso, os primeiros dias de janeiro podem pertencer ao ano ISO anterior, e os últimos dias de dezembro podem pertencer ao próximo.
• Valores fora do intervalo transbordam em vez de lançar um erro. Pedir pela semana 53 ou pelo dia 7 de uma semana que não existe simplesmente avança a data para a próxima semana ou ano. Por exemplo, date_isodate_set($d, 2022, 52, 7) resulta em 2023-01-01, porque a 52ª semana de 2022 termina no domingo, 1º de janeiro de 2023.

Nota: date_isodate_set() altera apenas a parte da data. O horário do dia permanece o que o DateTime já tinha (o horário atual para um objeto recém-criado).

Exemplos

Uso básico

Defina uma data para o 3º dia (quarta-feira) da 10ª semana ISO de 2023:

A função altera $date no lugar. Começamos de um horário fixo para que a saída seja a mesma a cada execução; apenas a parte da data é substituída.

Números de semana podem cruzar a fronteira do ano

Pedir pelo último dia da última semana de 2022 leva você a janeiro de 2023 — isso é o calendário ISO funcionando, não um bug:

A 52ª semana de 2022 termina no domingo, 1º de janeiro de 2023, portanto essa é a data retornada.

Equivalente orientado a objetos

DateTime::setISODate() faz o mesmo trabalho e retorna o objeto, o que permite encadear uma chamada format() diretamente:

Isso define a data para o 1º dia (segunda-feira) da 24ª semana de 2023.

Funções relacionadas

• date_create() — cria um objeto DateTime para passar como argumento.
• date_format() — formata a data resultante para exibição.

Conclusão

date_isodate_set() define um DateTime para um (ano, semana, dia da semana) específico usando o calendário de semanas ISO 8601. Lembre-se de que a semana ISO 1 contém a primeira quinta-feira do ano, que os valores de semana e dia transbordam para a próxima semana ou ano em vez de gerar erros, e que apenas a data — não o horário — é alterada.

Prática