From 228ab41ca07ea248a0bf26b2b6c3656da6c26a6b Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Date: Mon, 7 Sep 2026 10:02:33 +0200 Subject: [PATCH] [Sync-En] ext/date: document that DateInterval addition depends on how the interval was created --- reference/datetime/dateinterval.xml | 33 ++-- .../dateinterval/createfromdatestring.xml | 108 ++++++------ reference/datetime/datetimeimmutable/add.xml | 3 +- reference/datetime/datetimeimmutable/sub.xml | 3 +- reference/datetime/examples.xml | 157 ++++++++++-------- 5 files changed, 171 insertions(+), 133 deletions(-) diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml index a510687d0a..7206f568ff 100644 --- a/reference/datetime/dateinterval.xml +++ b/reference/datetime/dateinterval.xml @@ -1,6 +1,6 @@ - + @@ -9,7 +9,6 @@ -
&reftitle.intro; @@ -31,18 +30,31 @@ es calculando la diferencia entre dos objetos de fecha/hora a través de DateTimeInterface::diff. + + La forma en que se aplica la parte horaria de un intervalo, es decir horas, + minutos, segundos y microsegundos, cuando el intervalo se suma a, o se + resta de, un objeto de fecha/hora depende de cómo se creó el intervalo. + Para un intervalo creado con + DateInterval::__construct la parte horaria + representa tiempo transcurrido, mientras que para un intervalo creado con + DateInterval::createFromDateString, o devuelto por + DateTimeInterface::diff, incrementa o decrementa + los valores de cada componente. La parte de fecha, es decir años, meses y + días, siempre incrementa o decrementa los valores de cada componente. Por + lo tanto, ambos solo dan un resultado distinto cuando una transición de + zona horaria cae dentro de la parte horaria del intervalo; véase + Aritmética con DateTime. + Dado que no hay una forma bien definida de comparar intervalos de fechas, las instancias de DateInterval son incomparables.
-
&reftitle.classsynopsis; - DateInterval @@ -106,14 +118,9 @@ &Methods; - - - - - - + + -
@@ -231,7 +238,7 @@ -
+
&reftitle.changelog; @@ -274,7 +281,7 @@ -
+
diff --git a/reference/datetime/dateinterval/createfromdatestring.xml b/reference/datetime/dateinterval/createfromdatestring.xml index eba221591d..810c99c7fe 100644 --- a/reference/datetime/dateinterval/createfromdatestring.xml +++ b/reference/datetime/dateinterval/createfromdatestring.xml @@ -1,6 +1,6 @@ - + @@ -30,26 +30,24 @@ &reftitle.parameters; - - - - datetime - - - Una fecha con partes relativas. Específicamente, los - formatos relativos - admitidos por el analizador utilizados por DateTimeImmutable, - DateTime, y strtotime - serán los empleados para construir el objeto DateInterval - - - Para usar un string con formato ISO-8601 como P7D, debes - usar DateInterval::__construct. - - - - - + + + datetime + + + Una fecha con partes relativas. Específicamente, los + formatos relativos + admitidos por el analizador utilizados por DateTimeImmutable, + DateTime, y strtotime + serán los empleados para construir el objeto DateInterval + + + Para usar un string con formato ISO-8601 como P7D, debes + usar DateInterval::__construct. + + + + @@ -112,13 +110,12 @@ &reftitle.examples; - - - Analizando intervalos de fechas válidos - + + Analizando intervalos de fechas válidos + - - - - - - Analizando combinaciones e intervalos negativos - + + + + + Los intervalos de un conjunto que tienen una parte horaria, como + P1DT12H y 1 day + 12 hours, no son + intercambiables cuando se suman a un objeto de fecha/hora y una transición + de zona horaria cae dentro de esa parte horaria: para un intervalo creado + con DateInterval::__construct la parte horaria + representa tiempo transcurrido, mientras que para un intervalo creado con + este método incrementa o decrementa los valores de cada componente. Véase + Aritmética con DateTime. + + + + Analizando combinaciones e intervalos negativos + format('%d %h %i'), "\n"; $i = DateInterval::createFromDateString('1 year - 10 days'); echo $i->format('%y %d'), "\n"; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - Analizando intervalos de fechas relativas especiales - + + + + Analizando intervalos de fechas relativas especiales + - - &example.outputs.82; - + + &example.outputs.82; + @@ -194,9 +199,9 @@ object(DateInterval)#2 (2) { string(12) "last weekday" } ]]> - - &example.outputs.8.similar; - + + &example.outputs.8.similar; + @@ -267,9 +272,8 @@ object(DateInterval)#2 (16) { int(1) } ]]> - - - + + diff --git a/reference/datetime/datetimeimmutable/add.xml b/reference/datetime/datetimeimmutable/add.xml index 09e4edacca..f6991f21bf 100644 --- a/reference/datetime/datetimeimmutable/add.xml +++ b/reference/datetime/datetimeimmutable/add.xml @@ -1,6 +1,6 @@ - + @@ -118,6 +118,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::sub DateTimeImmutable::diff DateTimeImmutable::modify + Aritmética con DateTime diff --git a/reference/datetime/datetimeimmutable/sub.xml b/reference/datetime/datetimeimmutable/sub.xml index cfa63a9fdb..00f5bc8a56 100644 --- a/reference/datetime/datetimeimmutable/sub.xml +++ b/reference/datetime/datetimeimmutable/sub.xml @@ -1,6 +1,6 @@ - + @@ -156,6 +156,7 @@ echo $newDate2->format('Y-m-d') . "\n"; DateTimeImmutable::add DateTimeImmutable::diff DateTimeImmutable::modify + Aritmética con DateTime diff --git a/reference/datetime/examples.xml b/reference/datetime/examples.xml index 5234cdf921..2b79ddd9af 100644 --- a/reference/datetime/examples.xml +++ b/reference/datetime/examples.xml @@ -1,6 +1,6 @@ - + &reftitle.examples; @@ -11,14 +11,13 @@ Los ejemplos siguientes muestran algunos problemas de la aritmética de DateTime en lo que respecta a las transiciones DST y los meses con diferente número de días. - - - DateTimeImmutable::add/sub añadir un intervalo de tiempo transcurrido - - Añadir PT24H más allá de una transición DST parecerá añadir 23/25 horas - (para la mayoría de los husos horarios). - - + + DateTimeImmutable::add/sub añadir un intervalo de tiempo transcurrido + + Añadir PT24H más allá de una transición DST parecerá añadir 23/25 horas + (para la mayoría de los husos horarios). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->add(new DateInterval("PT3H")); echo "Fin: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - DateTimeImmutable::modify y strtotime incrementar o decrementar valores individuales - - Añadir +24 horas más allá de una transición DST puede añadir exactamente 24 - horas como se ve con la cadena fecha/hora - (excepto si la hora de inicio o fin está en un punto de transición). - - + + + + DateTimeImmutable::modify y strtotime incrementar o decrementar valores individuales + + Añadir +24 horas más allá de una transición DST puede añadir exactamente 24 + horas como se ve con la cadena fecha/hora + (excepto si la hora de inicio o fin está en un punto de transición). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("+24 hours"); echo "Fin: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - - - - La adición o sustracción de fechas/horas puede exceder - (en más o en menos) fechas - - Como para 31 de Enero + 1 mes dará como resultado 2 de Marzo (año bisiesto) o - 3 de Marzo (año normal). - - + + + + DateInterval::createFromDateString crea intervalos que incrementan o decrementan los valores de cada componente + + DateInterval::createFromDateString utiliza el + analizador de fecha/hora, y la parte horaria del intervalo resultante + incrementa o decrementa los valores de cada componente. Para un intervalo + creado con DateInterval::__construct la parte + horaria representa en cambio tiempo transcurrido, de modo que ambos no son + intercambiables cuando una transición de zona horaria cae dentro de esa + parte horaria. La parte de fecha se aplica de la misma forma en ambos + casos, por lo que P1D y 1 day dan + siempre el mismo resultado. + + +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; + + + + + + La adición o sustracción de fechas/horas puede exceder + (en más o en menos) fechas + + Como para 31 de Enero + 1 mes dará como resultado 2 de Marzo (año bisiesto) o + 3 de Marzo (año normal). + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("+1 month"); echo "Fin: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - Para obtener el último día del mes próximo (es decir, para prever el - excedente), el formato last day of está disponible. - - + + + Para obtener el último día del mes próximo (es decir, para prever el + excedente), el formato last day of está disponible. + + format("Y-m-d H:i:s P"), PHP_EOL; $dt = $dt->modify("last day of next month"); echo "Fin: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL; ]]> - - &example.outputs; - + + &example.outputs; + - - - + +