date_isodate_set()

La fonction date_isodate_set() définit la date d'un objet DateTime en utilisant le calendrier hebdomadaire ISO 8601 — c'est-à-dire par année, numéro de semaine et jour de la semaine, plutôt que par mois et jour. Il s'agit de l'alias procédural de la méthode DateTime::setISODate(), les deux font exactement la même chose.

Cette page couvre la syntaxe de la fonction, la façon dont le calendrier ISO hebdomadaire diffère du calendrier ordinaire, des exemples exécutables, et les erreurs courantes à éviter.

Syntaxe

La fonction date_isodate_set() possède la syntaxe suivante :

Syntaxe de la fonction PHP date_isodate_set()

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

où :

• $object — l'objet DateTime à modifier (il est modifié en place).
• $year — l'année ISO.
• $week — le numéro de semaine ISO, de 1 à 53.
• $dayOfWeek — le jour de la semaine, 1 pour lundi jusqu'à 7 pour dimanche (optionnel, par défaut 1).

La fonction retourne le même objet DateTime, ce qui permet d'enchaîner les appels. L'appel équivalent en orienté objet est :

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

Pourquoi utiliser les dates ISO hebdomadaires

Contrairement au calendrier ordinaire, ISO 8601 numérote chaque semaine de l'année et identifie une date par (année, semaine, jour de la semaine). C'est pratique pour les rapports d'entreprise, la planification et tout système qui raisonne en semaines plutôt qu'en mois.

Deux règles méritent d'être retenues :

• La semaine 1 est la semaine contenant le premier jeudi de l'année — autrement dit, la semaine contenant le 4 janvier. De ce fait, les premiers jours de janvier peuvent appartenir à l'année ISO précédente, et les derniers jours de décembre peuvent appartenir à l'année suivante.
• Les valeurs hors plage débordent plutôt que de déclencher une erreur. Demander la semaine 53 ou le jour 7 d'une semaine qui n'existe pas fait simplement avancer la date dans la semaine ou l'année suivante. Par exemple, date_isodate_set($d, 2022, 52, 7) donne 2023-01-01, car la 52e semaine de 2022 se termine le dimanche 1er janvier 2023.

Remarque : date_isodate_set() ne modifie que la partie date. L'heure reste celle que le DateTime avait déjà (l'heure courante pour un objet fraîchement créé).

Exemples

Utilisation de base

Définir une date au 3e jour (mercredi) de la 10e semaine ISO de 2023 :

La fonction modifie $date en place. On part d'une heure fixe pour que la sortie soit identique à chaque exécution ; seule la partie date est remplacée.

Les numéros de semaine peuvent traverser la frontière d'année

Demander le dernier jour de la dernière semaine de 2022 vous amène en janvier 2023 — c'est le calendrier ISO en action, pas un bug :

La 52e semaine de 2022 se termine le dimanche 1er janvier 2023, c'est donc la date retournée.

Équivalent orienté objet

DateTime::setISODate() fait le même travail et retourne l'objet, ce qui permet d'enchaîner directement un appel format() :

Cela définit la date au 1er jour (lundi) de la 24e semaine de 2023.

Fonctions connexes

• date_create() — créer un objet DateTime à passer en argument.
• date_format() — formater la date résultante pour l'affichage.

Conclusion

date_isodate_set() définit un DateTime à un (année, semaine, jour de la semaine) précis en utilisant le calendrier hebdomadaire ISO 8601. Retenez que la semaine ISO 1 contient le premier jeudi de l'année, que les valeurs de semaine et de jour débordent dans la semaine ou l'année suivante plutôt que de générer une erreur, et que seule la date — pas l'heure — est modifiée.

Exercice