From a6c2b095d498c58fb9c200cd7e08d3d3e86bb077 Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Date: Fri, 4 Sep 2026 09:41:42 +0200 Subject: [PATCH] [Sync-En] ext/date: document that DateInterval addition depends on how the interval was created --- reference/datetime/dateinterval.xml | 36 +++-- .../dateinterval/createfromdatestring.xml | 111 +++++++------- reference/datetime/datetimeimmutable/add.xml | 3 +- reference/datetime/datetimeimmutable/sub.xml | 8 +- reference/datetime/examples.xml | 139 ++++++++++-------- 5 files changed, 167 insertions(+), 130 deletions(-) diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml index 5552c63e44..e8347008ce 100644 --- a/reference/datetime/dateinterval.xml +++ b/reference/datetime/dateinterval.xml @@ -1,7 +1,5 @@ - - - + La classe <classname>DateInterval</classname> @@ -9,7 +7,6 @@ -
&reftitle.intro; @@ -32,18 +29,32 @@ est en calculant la différence entre deux objets dates/moments à travers DateTimeInterface::diff. + + La façon dont la partie horaire d'un intervalle, c'est-à-dire les heures, + les minutes, les secondes et les microsecondes, est appliquée lorsque + l'intervalle est ajouté à un objet date/heure, ou soustrait de celui-ci, + dépend de la manière dont l'intervalle a été créé. Pour un intervalle créé + avec DateInterval::__construct, la partie horaire + correspond au temps écoulé, tandis que pour un intervalle créé avec + DateInterval::createFromDateString, ou retourné + par DateTimeInterface::diff, elle incrémente ou + décrémente les valeurs individuelles des composants. La partie date, + c'est-à-dire les années, les mois et les jours, incrémente ou décrémente + toujours les valeurs individuelles des composants. Les deux ne donnent donc + un résultat différent que lorsqu'une transition de fuseau horaire tombe + dans la partie horaire de l'intervalle ; voir + Arithmétique avec DateTime. + Comme il n'y a pas une manière bien définie pour comparer les intervalles, les instances de DateInterval sont incomparables.
-
&reftitle.classsynopsis; - DateInterval @@ -107,14 +118,9 @@ &Methods; - - - - - - + + -
@@ -231,7 +237,7 @@ -
+
&reftitle.changelog; @@ -274,7 +280,7 @@ -
+
&reference.datetime.entities.dateinterval; diff --git a/reference/datetime/dateinterval/createfromdatestring.xml b/reference/datetime/dateinterval/createfromdatestring.xml index 9712cde3b1..71cf3b2d3f 100644 --- a/reference/datetime/dateinterval/createfromdatestring.xml +++ b/reference/datetime/dateinterval/createfromdatestring.xml @@ -1,5 +1,5 @@ - + DateInterval::createFromDateString @@ -28,27 +28,25 @@ &reftitle.parameters; - - - - datetime - - - Une date avec des parties relatives. Spécifiquement, le - format relatif - supporté par l'analyseur utilisé pour les classes - DateTimeImmutable, - DateTime, et strtotime - sera utilisé pour construire le DateInterval. - - - Pour utiliser une chaîne au format ISO-8601 comme P7D, il faut - utiliser DateInterval::__construct. - - - - - + + + datetime + + + Une date avec des parties relatives. Spécifiquement, le + format relatif + supporté par l'analyseur utilisé pour les classes + DateTimeImmutable, + DateTime, et strtotime + sera utilisé pour construire le DateInterval. + + + Pour utiliser une chaîne au format ISO-8601 comme P7D, + il faut utiliser DateInterval::__construct. + + + + @@ -111,13 +109,12 @@ &reftitle.examples; - - - Analyse d'intervalles de dates valides - + + Analyse d'intervalles de dates valides + - - - - - - Analyse des combinaisons et des intervalles négatifs - + + + + + Les intervalles d'un ensemble qui comportent une partie horaire, tels que + P1DT12H et 1 day + 12 hours, ne sont + pas interchangeables lorsqu'ils sont ajoutés à un objet date/heure et + qu'une transition de fuseau horaire tombe dans cette partie horaire : pour + un intervalle créé avec DateInterval::__construct, + la partie horaire correspond au temps écoulé, tandis que pour un intervalle + créé avec cette méthode, elle incrémente ou décrémente les valeurs + individuelles des composants. Voir + Arithmétique avec DateTime. + + + + Analyse des combinaisons et des intervalles négatifs + format('%d %h %i'), "\n"; $i = DateInterval::createFromDateString('1 year - 10 days'); echo $i->format('%y %d'), "\n"; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - Analyse des intervalles de dates relatifs spéciaux - + + + + Analyse des intervalles de dates relatifs spéciaux + - - &example.outputs.82; - + + &example.outputs.82; + @@ -193,9 +199,9 @@ object(DateInterval)#2 (2) { string(12) "last weekday" } ]]> - - &example.outputs.8.similar; - + + &example.outputs.8.similar; + @@ -266,9 +272,8 @@ object(DateInterval)#2 (16) { int(1) } ]]> - - - + + diff --git a/reference/datetime/datetimeimmutable/add.xml b/reference/datetime/datetimeimmutable/add.xml index c2e09b6688..735455ea25 100644 --- a/reference/datetime/datetimeimmutable/add.xml +++ b/reference/datetime/datetimeimmutable/add.xml @@ -1,5 +1,5 @@ - + DateTimeImmutable::add @@ -117,6 +117,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::sub DateTimeImmutable::diff DateTimeImmutable::modify + Arithmétique avec DateTime diff --git a/reference/datetime/datetimeimmutable/sub.xml b/reference/datetime/datetimeimmutable/sub.xml index 8194a52c1c..b1c3f6d890 100644 --- a/reference/datetime/datetimeimmutable/sub.xml +++ b/reference/datetime/datetimeimmutable/sub.xml @@ -1,10 +1,11 @@ - - + DateTimeImmutable::sub - Soustrait un nombre de jours, mois, années, heures et secondes + + Soustrait un nombre de jours, mois, années, heures, minutes et secondes + @@ -153,6 +154,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::add DateTimeImmutable::diff DateTimeImmutable::modify + Arithmétique avec DateTime diff --git a/reference/datetime/examples.xml b/reference/datetime/examples.xml index 1e6f680965..0e968aadcb 100644 --- a/reference/datetime/examples.xml +++ b/reference/datetime/examples.xml @@ -1,7 +1,5 @@ - - - + &reftitle.examples; @@ -9,18 +7,17 @@
Arithmétique avec DateTime - Les exemples suivants montrent quelques pièges de l'arithmétique de DateTime - en ce qui concerne les transitions DST et les mois ayant un nombre différent + Les exemples suivants montrent quelques pièges de l'arithmétique de DateTime + en ce qui concerne les transitions DST et les mois ayant un nombre différent de jours. - - - DateTimeImmutable::add/sub ajout d'un intervalle de temps écoulé - - Ajouter PT24H au-delà d'une transition DST semblera ajouter 23/25 heures - (pour la plupart des fuseaux horaires). - - + + DateTimeImmutable::add/sub ajout d'un intervalle de temps écoulé + + Ajouter PT24H au-delà d'une transition DST semblera ajouter 23/25 heures + (pour la plupart des fuseaux horaires). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->add(new DateInterval("PT3H")); echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - DateTimeImmutable::modify et strtotime incrémentation ou décrémentation de valeurs individuelles - - Ajouter +24 heures au-delà d'une transition DST peut ajouter exactement 24 - heures comme vu avec la chaîne date/time - (sauf si l'heure de début ou de fin est sur un point de transition). - - + + + + DateTimeImmutable::modify et strtotime incrémentation ou décrémentation de valeurs individuelles + + Ajouter +24 heures au-delà d'une transition DST ajoutera exactement 24 + heures comme vu avec la chaîne date/time + (sauf si l'heure de début ou de fin est sur un point de transition). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("+24 hours"); echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - L'ajout ou la soustraction de dates/heures peut dépasser - (en plus ou en moins) des dates - - Comme pour 31 janvier + 1 mois donnera comme résultat 2 mars (année bissextile) ou - 3 mars (année normale). - - + + + + DateInterval::createFromDateString crée des intervalles qui incrémentent ou décrémentent les valeurs des composants + + DateInterval::createFromDateString utilise + l'analyseur de date/heure, et la partie horaire de l'intervalle obtenu + incrémente ou décrémente les valeurs individuelles des composants. Pour un + intervalle créé avec DateInterval::__construct, la + partie horaire correspond en revanche au temps écoulé ; les deux ne sont + donc pas interchangeables lorsqu'une transition de fuseau horaire tombe + dans cette partie horaire. La partie date est appliquée de la même manière + dans les deux cas, si bien que P1D et + 1 day donnent toujours le même résultat. + + +format("Y-m-d H:i:s P"), PHP_EOL; +echo "PT24H: ", $dt->add(new DateInterval("PT24H"))->format("Y-m-d H:i:s P"), PHP_EOL; +echo "24 hours: ", $dt->add(DateInterval::createFromDateString("24 hours"))->format("Y-m-d H:i:s P"), PHP_EOL; +]]> + + &example.outputs; + + + + + + L'ajout ou la soustraction de dates/heures peut dépasser + (en plus ou en moins) des dates + + Comme pour 31 janvier + 1 mois donnera comme résultat 2 mars (année bissextile) ou + 3 mars (année normale). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("+1 month"); echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - Pour obtenir le dernier jour du mois prochain (autrement dit pour prévenir le - dépassement), le format last day of est disponible. - - + + + Pour obtenir le dernier jour du mois prochain (autrement dit pour prévenir le + dépassement), le format last day of est disponible. + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("last day of next month"); echo "End: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - + +