date_modify()

Ce guide présente la méthode PHP DateTime::modify() (l'équivalent orienté objet de la fonction procédurale date_modify()). Il explique comment modify() analyse les chaînes de dates relatives, ce qu'elle retourne, le piège du débordement de mois qui surprend la plupart des développeurs, et comment éviter de muter une date par accident.

Qu'est-ce que DateTime::modify() ?

modify() est une méthode intégrée de la classe DateTime qui modifie la date/heure qu'elle contient à l'aide d'une chaîne de format relatif telle que +10 days, -3 months ou next monday. Utilisez-la lorsque vous avez besoin d'arithmétique de dates — décaler une échéance vers l'avant, reculer un horodatage, ou passer au prochain jour de la semaine — sans calculer manuellement les secondes.

Deux caractéristiques rendent modify() distinctive et méritent d'être assimilées avant de lire les exemples :

• Elle mute l'objet en place — elle modifie le même objet DateTime sur lequel elle est appelée plutôt que de retourner une nouvelle copie.
• Elle accepte la même grammaire de format relatif que PHP utilise lors de la construction de dates à partir de chaînes, donc tout ce que new DateTime('+1 week') comprend, modify() le comprend aussi.

Syntaxe

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

• $modifier — une chaîne de format relatif (p. ex. +1 day, -2 weeks, first day of next month, 14:00).
• Retourne le même objet DateTime en cas de succès (les appels peuvent donc être chaînés), ou false en cas d'échec (par exemple, une chaîne non analysable).

Comme elle retourne l'objet lui-même, ces deux lignes sont équivalentes — le $date original est modifié dans les deux cas :

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

Conseil : Lorsque $modifier provient d'une saisie utilisateur, vérifiez toujours false avant d'utiliser le résultat, car une chaîne mal formée retourne false plutôt que de lever une exception.

Exemples

Exemple 1 : Ajouter des jours à une date

Pour ajouter 10 jours à une date fixe avec une gestion d'erreur basique :

Ajouter des jours à une date en PHP

Résultat :

2023-03-11

Exemple 2 : Soustraire des mois d'une date

Pour soustraire 3 mois d'une date fixe :

Soustraire des mois d'une date en PHP

Résultat :

2022-12-01

Exemple 3 : Définir l'heure à une valeur spécifique

Pour définir l'heure à 14h sur une date fixe :

Définir l'heure à une valeur spécifique en PHP

Résultat :

2023-03-01 14:00:00

Notez que modify('14:00') définit la partie horaire à 14h mais laisse la date inchangée — les formats relatifs qui mentionnent uniquement une heure agissent sur l'heure, pas sur le jour.

Exemple 4 : Combiner plusieurs unités en un seul appel

Vous pouvez empiler plusieurs unités relatives dans une seule chaîne de modification, séparées par des espaces. Elles sont appliquées de gauche à droite :

<?php

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

Résultat :

2023-03-10

Le piège du débordement de mois

L'ajout ou la soustraction de mois ne se limite pas à la fin d'un mois plus court — cela déborde dans le suivant. Observez ce qui se passe lorsque vous ajoutez un mois au 31 janvier :

<?php

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

Résultat :

2023-03-03

Parce que février 2023 n'a que 28 jours, "31 janvier + 1 mois" atterrit sur le "31 février" inexistant, que PHP reporte au 3 mars. Si vous avez besoin du dernier jour du mois suivant à la place, utilisez un format relatif absolu :

<?php

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

Résultat :

2023-02-28

Éviter la mutation accidentelle avec DateTimeImmutable

Comme modify() modifie l'objet en place, partager un seul objet DateTime dans votre code peut provoquer des bugs difficiles à trouver — le modifier à un endroit affecte toutes les références à cet objet. Si vous souhaitez que chaque opération retourne une nouvelle valeur et laisse l'original intact, utilisez DateTimeImmutable, dont la méthode modify() retourne un nouvel objet :

<?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');

Résultat :

2023-03-01
2023-03-08

Formats relatifs utiles

modify() accepte une riche grammaire d'expressions relatives. Voici quelques-unes des plus courantes :

Fonctions associées

• date_add() — ajouter un DateInterval à une date.
• date_sub() — soustraire un DateInterval d'une date.
• date_diff() — obtenir la différence entre deux dates.
• date_format() — formater un objet DateTime en chaîne.

Résumé

DateTime::modify() applique une chaîne de format relatif à une date, mutant l'objet en place et le retournant (ou false en cas d'échec). Elle est idéale pour l'arithmétique de dates et le saut vers des jours nommés, mais gardez deux points à l'esprit : les calculs en mois débordent au-delà des mois courts, et la mutation est partagée — utilisez DateTimeImmutable lorsque vous avez besoin de conserver l'original intact.

Pratique