Author: Derick Rethans (derickr)
Date: 2022-08-12T17:31:45+01:00
Commit: https://github.com/php/doc-en/commit/1a9ee818e554e116b4721d432c6d671e14281ea0
Raw diff: https://github.com/php/doc-en/commit/1a9ee818e554e116b4721d432c6d671e14281ea0.diff
Incorporate useful information from notes (take #1)
Changed paths:
M language-snippets.ent
M reference/datetime/book.xml
M reference/datetime/datetime.xml
M reference/datetime/datetime/settime.xml
M reference/datetime/datetime/settimezone.xml
M reference/datetime/datetime/sub.xml
M reference/datetime/datetimeimmutable.xml
M reference/datetime/datetimeimmutable/add.xml
M reference/datetime/datetimeimmutable/construct.xml
M reference/datetime/datetimeimmutable/createfromformat.xml
M reference/datetime/datetimeimmutable/getlasterrors.xml
M reference/datetime/datetimeimmutable/modify.xml
M reference/datetime/datetimeimmutable/setisodate.xml
M reference/datetime/datetimeimmutable/settime.xml
M reference/datetime/datetimeimmutable/settimestamp.xml
M reference/datetime/datetimeimmutable/settimezone.xml
M reference/datetime/datetimeimmutable/sub.xml
M reference/datetime/datetimeinterface.xml
M reference/datetime/datetimeinterface/diff.xml
M reference/datetime/datetimeinterface/format.xml
M reference/datetime/datetimeinterface/getoffset.xml
M reference/datetime/datetimeinterface/gettimestamp.xml
M reference/datetime/datetimeinterface/gettimezone.xml
M reference/datetime/datetimezone/getlocation.xml
M reference/datetime/datetimezone/getname.xml
M reference/datetime/datetimezone/gettransitions.xml
M reference/datetime/datetimezone/listabbreviations.xml
M reference/datetime/datetimezone/listidentifiers.xml
M reference/datetime/formats.xml
Diff:
diff --git a/language-snippets.ent b/language-snippets.ent
index ce4fe58cfc7..c864f62fe39 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1400,8 +1400,8 @@ The function modifies this
object.</para></listitem></varlistentry>'>
<parameter>object</parameter></term><listitem><para>Procedural style
only: A <classname>DateTimeZone</classname> object
returned by
<function>timezone_open</function></para></listitem></varlistentry>'>
-<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname
xmlns="http://docbook.org/ns/docbook">DateTime</classname>
object for method chaining&return.falseforfailure;.'>
-<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new
modified <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname>
object &return.falseforfailure;.'>
+<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified
<classname xmlns="http://docbook.org/ns/docbook">DateTime</classname>
object for method chaining&return.falseforfailure;.'>
+<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new
<classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname>
object with the modified data &return.falseforfailure;.'>
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database
version'>
diff --git a/reference/datetime/book.xml b/reference/datetime/book.xml
index 26018d6c4de..aac86be8707 100644
--- a/reference/datetime/book.xml
+++ b/reference/datetime/book.xml
@@ -10,9 +10,14 @@
<preface xml:id="intro.datetime">
&reftitle.intro;
<para>
- These functions allow you to get the date and time from the server
- where your PHP scripts are running. You can use these functions to format the
- date and time in many different ways.
+ The <classname>DateTimeImmutable</classname> and related classes allow you
+ represent date/time information. The objects can be created by passing in a
+ string presentation of date/time information, or from the current system's
+ time.
+ </para>
+ <para>
+ A rich set of methods is supplied to modify and format this information
+ as well, including handling timezones and DST transitions.
</para>
<para>
The date and time information is internally stored as a 64-bit number so
@@ -20,17 +25,6 @@
range is from about 292 billion years in the past to the same in the
future.
</para>
- <note>
- <simpara>
- Please keep in mind that these functions are dependent on
- the locale settings of your server. Make sure to take
- daylight saving time (use e.g.
- <literal>$date = $date->modify('+7 days')</literal> and not
- <literal>$date += 7*24*60*60</literal>)
- and leap years into consideration when working
- with these functions.
- </simpara>
- </note>
<note>
<simpara>
The timezones referenced in this section can be found in the
diff --git a/reference/datetime/datetime.xml b/reference/datetime/datetime.xml
index e0f7880abc3..2f6172cbdc0 100644
--- a/reference/datetime/datetime.xml
+++ b/reference/datetime/datetime.xml
@@ -18,10 +18,16 @@
except objects are modified itself when modification methods such as
<function>DateTime::modify</function> are called.
</para>
- <para>
- Using <classname>DateTimeImmutable</classname> over this class is
- recommended.
- </para>
+ <warning>
+ <para>
+ Calling methods on objects of the class <classname>DateTime</classname>
+ will change the information encapsulated in these objects, if you want to
+ prevent that you will have to use <literal>clone</literal> operator to
+ create a new object. Use the <classname>DateTimeInterface</classname>
+ instead of <classname>DateTime</classname> to obtain this recommended
+ behaviour by default.
+ </para>
+ </warning>
</section>
<!-- }}} -->
@@ -83,6 +89,22 @@
on <classname>DateTimeInterface</classname>.
</entry>
</row>
+ <row>
+ <entry>7.1.0</entry>
+ <entry>
+ The <classname>DateTime</classname> constructor now includes the
+ current microseconds in the constructed value. Before this, it would
+ always initialise the microseconds to <literal>0</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>5.2.2</entry>
+ <entry>
+ Support for microseconds was added in both date/time parser, and
+ <methodname>DateTime::format</methodname> through the
+ <literal>'u'</literal> modifier.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
diff --git a/reference/datetime/datetime/settime.xml b/reference/datetime/datetime/settime.xml
index 0e965701128..b1ea2652dc4 100644
--- a/reference/datetime/datetime/settime.xml
+++ b/reference/datetime/datetime/settime.xml
@@ -86,6 +86,33 @@
</para>
</refsect1>
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.1.0</entry>
+ <entry>The behaviour with double existing hours (during the fall-back
+ DST transition) changed. Previously PHP would pick the second occurrence
+ (after the DST transition), instead of the first occurrence (before DST
+ transition).
+ </row>
+ <row>
+ <entry>7.1.0</entry>
+ <entry>The <parameter>microsecond</parameter> parameter was
added.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
diff --git a/reference/datetime/datetime/settimezone.xml
b/reference/datetime/datetime/settimezone.xml
index c067381b91f..179ce6dde51 100644
--- a/reference/datetime/datetime/settimezone.xml
+++ b/reference/datetime/datetime/settimezone.xml
@@ -53,7 +53,8 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Returns the <classname>DateTime</classname> object for method chaining.
+ Returns the <classname>DateTime</classname> object for method chaining. The
+ underlaying point-in-time is not changed when calling this method.
</para>
</refsect1>
diff --git a/reference/datetime/datetime/sub.xml b/reference/datetime/datetime/sub.xml
index 82a9bfa136e..4a7cbfdcff0 100644
--- a/reference/datetime/datetime/sub.xml
+++ b/reference/datetime/datetime/sub.xml
@@ -25,8 +25,8 @@
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
</methodsynopsis>
<para>
- Subtracts the specified <classname>DateInterval</classname> object from the
specified DateTime
- object.
+ Modifies the specified DateTime object, by subtracting the specified
+ <classname>DateInterval</classname> object.
</para>
<para>
Like <methodname>DateTimeImmutable::sub</methodname> but works with
diff --git a/reference/datetime/datetimeimmutable.xml b/reference/datetime/datetimeimmutable.xml
index 4f79f5a02d3..36cebbac570 100644
--- a/reference/datetime/datetimeimmutable.xml
+++ b/reference/datetime/datetimeimmutable.xml
@@ -60,6 +60,31 @@
</section>
+ <section role="changelog" xml:id="datetimeimmutable.changelog"><!--
{{{ -->
+ &reftitle.changelog;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>7.1.0</entry>
+ <entry>
+ The <classname>DateTimeImmutable</classname> constructor now includes the
+ current microseconds in the constructed value. Before this, it would
+ always initialise the microseconds to <literal>0</literal>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </section><!-- }}} -->
</partintro>
&reference.datetime.entities.datetimeimmutable;
diff --git a/reference/datetime/datetimeimmutable/add.xml
b/reference/datetime/datetimeimmutable/add.xml
index 97404dd3588..176cda60088 100644
--- a/reference/datetime/datetimeimmutable/add.xml
+++ b/reference/datetime/datetimeimmutable/add.xml
@@ -15,16 +15,15 @@
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
</methodsynopsis>
<para>
- Adds the specified <classname>DateInterval</classname> object to the
- specified <classname>DateTime</classname> object, and returns a new
- <classname>DateTimeImmutable</classname> object to represent this new state.
+ Creates a new <classname>DateTimeImmutable</classname> object, and adds the
+ specified <classname>DateInterval</classname> object to this, to represent
+ the new value.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term>
<parameter>interval</parameter>
diff --git a/reference/datetime/datetimeimmutable/construct.xml
b/reference/datetime/datetimeimmutable/construct.xml
index 5eaeb452b49..1d8aae19f3f 100644
--- a/reference/datetime/datetimeimmutable/construct.xml
+++ b/reference/datetime/datetimeimmutable/construct.xml
@@ -57,7 +57,8 @@
<parameter>$datetime</parameter> parameter either
is a UNIX timestamp (e.g. <literal>@946684800</literal>)
or specifies a timezone
- (e.g. <literal>2010-01-28T15:00:00+02:00</literal>).
+ (e.g. <literal>2010-01-28T15:00:00+02:00</literal>, or
+ <literal>2010-07-05T06:00:00Z</literal>).
</para>
</note>
</listitem>
@@ -185,6 +186,48 @@ echo $date->format('Y-m-d H:i:sP') . "\n";
2010-04-25 02:24:16+12:00
2000-01-01 00:00:00+00:00
2000-03-01 00:00:00-05:00
+]]>
+ </screen>
+ </example>
+
+ <example>
+ <title>Changing the associated timezone</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timeZone = new \DateTimeZone('Asia/Tokyo');
+
+$time = new \DateTimeImmutable();
+$time = $time->setTimezone($timeZone);
+
+echo $time->format('Y/m/d H:i:s'), "\n";
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+2022/08/12 23:49:23
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <example>
+ <title>Using a relative date/time string</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$time = new \DateTimeImmutable("-1 year");
+
+echo $time->format('Y/m/d H:i:s'), "\n";
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+2021/08/12 15:43:51
]]>
</screen>
</example>
diff --git a/reference/datetime/datetimeimmutable/createfromformat.xml
b/reference/datetime/datetimeimmutable/createfromformat.xml
index 0cc2ea0ca37..262560fae6b 100644
--- a/reference/datetime/datetimeimmutable/createfromformat.xml
+++ b/reference/datetime/datetimeimmutable/createfromformat.xml
@@ -41,6 +41,15 @@
formatting options below. In most cases, the same letters as for the
<function>date</function> can be used.
</para>
+ <para>
+ ALl fields are initialised with the current date/time. In most cases you
+ would want to reset these to "zero" (the Unix epoch, <literal>1970-01-01
+ 00:00:00 UTC</literal>). You do that by including the
+ <literal>!</literal> character as first character in your
+ <parameter>format</parameter>, or <literal>|</literal> as your last.
+ Please see the documentation for each character below for more
+ information.
+ </para>
<para>
The format is parsed from left to right, which means that in some
situations the order in which the format characters are present effects
diff --git a/reference/datetime/datetimeimmutable/getlasterrors.xml
b/reference/datetime/datetimeimmutable/getlasterrors.xml
index fb27a3c0267..61f3603ba83 100644
--- a/reference/datetime/datetimeimmutable/getlasterrors.xml
+++ b/reference/datetime/datetimeimmutable/getlasterrors.xml
@@ -35,7 +35,6 @@
&reftitle.examples;
<example>
<title><function>DateTimeImmutable::getLastErrors</function>
example</title>
- <para>&style.oop;</para>
<programlisting role="php">
<![CDATA[
<?php
diff --git a/reference/datetime/datetimeimmutable/modify.xml
b/reference/datetime/datetimeimmutable/modify.xml
index 8f5b7f25870..e8d0469d592 100644
--- a/reference/datetime/datetimeimmutable/modify.xml
+++ b/reference/datetime/datetimeimmutable/modify.xml
@@ -21,7 +21,6 @@
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term><parameter>modifier</parameter></term>
<listitem>
diff --git a/reference/datetime/datetimeimmutable/setisodate.xml
b/reference/datetime/datetimeimmutable/setisodate.xml
index 92b9ff38550..b9554092419 100644
--- a/reference/datetime/datetimeimmutable/setisodate.xml
+++ b/reference/datetime/datetimeimmutable/setisodate.xml
@@ -23,7 +23,6 @@
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term><parameter>year</parameter></term>
<listitem>
diff --git a/reference/datetime/datetimeimmutable/settime.xml
b/reference/datetime/datetimeimmutable/settime.xml
index 8f247e283e8..8f8d0200945 100644
--- a/reference/datetime/datetimeimmutable/settime.xml
+++ b/reference/datetime/datetimeimmutable/settime.xml
@@ -23,7 +23,6 @@
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term><parameter>hour</parameter></term>
<listitem>
@@ -77,6 +76,13 @@
</row>
</thead>
<tbody>
+ <row>
+ <entry>8.1.0</entry>
+ <entry>The behaviour with double existing hours (during the fall-back
+ DST transition) changed. Previously PHP would pick the second occurrence
+ (after the DST transition), instead of the first occurrence (before DST
+ transition).
+ </row>
<row>
<entry>7.1.0</entry>
<entry>The <parameter>microsecond</parameter> parameter was
added.</entry>
diff --git a/reference/datetime/datetimeimmutable/settimestamp.xml
b/reference/datetime/datetimeimmutable/settimestamp.xml
index 7d3d2bc560a..9981b1a70b9 100644
--- a/reference/datetime/datetimeimmutable/settimestamp.xml
+++ b/reference/datetime/datetimeimmutable/settimestamp.xml
@@ -13,14 +13,14 @@
<methodparam><type>int</type><parameter>timestamp</parameter></methodparam>
</methodsynopsis>
<para>
- Returns a new DateTimeImmutable object with the date and time set based on an Unix timestamp.
+ Returns a new <type>DateTimeImmutable</type> object constructed from the
+ old one, with the date and time set based on an Unix timestamp.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term><parameter>timestamp</parameter></term>
<listitem>
diff --git a/reference/datetime/datetimeimmutable/settimezone.xml
b/reference/datetime/datetimeimmutable/settimezone.xml
index 418b553a26a..20ffaebc4e6 100644
--- a/reference/datetime/datetimeimmutable/settimezone.xml
+++ b/reference/datetime/datetimeimmutable/settimezone.xml
@@ -20,7 +20,6 @@
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term><parameter>timezone</parameter></term>
<listitem>
@@ -36,7 +35,9 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Returns a new modified <classname>DateTimeImmutable</classname> object for method
chaining.
+ Returns a new modified <classname>DateTimeImmutable</classname> object for
+ method chaining. The underlaying point-in-time is not changed when calling
+ this method.
</para>
</refsect1>
diff --git a/reference/datetime/datetimeimmutable/sub.xml
b/reference/datetime/datetimeimmutable/sub.xml
index cd4b8720f8a..509f4d88b03 100644
--- a/reference/datetime/datetimeimmutable/sub.xml
+++ b/reference/datetime/datetimeimmutable/sub.xml
@@ -15,7 +15,7 @@
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
</methodsynopsis>
<para>
- Returns a new DateTimeImmutable object, with the specified
+ Returns a new <classname>DateTimeImmutable</classname> object, with the specified
<classname>DateInterval</classname> object subtracted from the specified
DateTimeImmutable object.
</para>
@@ -24,7 +24,6 @@
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
- &date.datetime.description.modified;
<varlistentry>
<term>
<parameter>interval</parameter>
diff --git a/reference/datetime/datetimeinterface.xml b/reference/datetime/datetimeinterface.xml
index aa77f3a9ead..21eede6542d 100644
--- a/reference/datetime/datetimeinterface.xml
+++ b/reference/datetime/datetimeinterface.xml
@@ -13,10 +13,18 @@
<para>
<interfacename>DateTimeInterface</interfacename> was created
so that parameter, return, or property type declarations may accept either
- <classname>DateTime</classname> or
<classname>DateTimeImmutable</classname>
+ <classname>DateTimeImmutable</classname> or
<classname>DateTime</classname>
as a value. It is not possible to
implement this interface with userland classes.
</para>
+ <para>
+ Common constants that allow for formatting
+ <classname>DateTimeImmutable</classname> or
+ <classname>DateTime</classname> objects through
+ <methodname>DateTimeImmutable::format</methodname> and
+ <methodname>DateTime::format</methodname> are also defined on this
+ interface.
+ </para>
</section>
<!-- }}} -->
@@ -319,7 +327,7 @@
<entry>7.2.0</entry>
<entry>
The class constants of <classname>DateTime</classname> are now defined
- on <classname>DateTimeInterface</classname>.
+ on <interfacename>DateTimeInterface</interfacename>.
</entry>
</row>
</tbody>
diff --git a/reference/datetime/datetimeinterface/diff.xml
b/reference/datetime/datetimeinterface/diff.xml
index 84f3261b0b3..00357ad594f 100644
--- a/reference/datetime/datetimeinterface/diff.xml
+++ b/reference/datetime/datetimeinterface/diff.xml
@@ -2,9 +2,9 @@
<!-- $Revision$ -->
<refentry xml:id="datetime.diff" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
- <refname>DateTime::diff</refname>
- <refname>DateTimeImmutable::diff</refname>
<refname>DateTimeInterface::diff</refname>
+ <refname>DateTimeImmutable::diff</refname>
+ <refname>DateTime::diff</refname>
<refname>date_diff</refname>
<refpurpose>Returns the difference between two DateTime objects</refpurpose>
</refnamediv>
@@ -12,8 +12,8 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
- <methodsynopsis role="oop">
- <modifier>public</modifier>
<type>DateInterval</type><methodname>DateTime::diff</methodname>
+ <methodsynopsis role="DateTimeInterface">
+ <modifier>public</modifier>
<type>DateInterval</type><methodname>DateTimeInterface::diff</methodname>
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
<methodparam
choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
@@ -22,8 +22,8 @@
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
<methodparam
choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
- <methodsynopsis role="DateTimeInterface">
- <modifier>public</modifier>
<type>DateInterval</type><methodname>DateTimeInterface::diff</methodname>
+ <methodsynopsis role="oop">
+ <modifier>public</modifier>
<type>DateInterval</type><methodname>DateTime::diff</methodname>
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
<methodparam
choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
@@ -80,13 +80,13 @@
<refsect1 role="examples">
&reftitle.examples;
<example>
- <title><function>DateTime::diff</function> example</title>
+ <title><function>DateTimeImmutable::diff</function> example</title>
<para>&style.oop;</para>
<programlisting role="php">
<![CDATA[
<?php
-$origin = new DateTime('2009-10-11');
-$target = new DateTime('2009-10-13');
+$origin = new DateTimeImmutable('2009-10-11');
+$target = new DateTimeImmutable('2009-10-13');
$interval = $origin->diff($target);
echo $interval->format('%R%a days');
?>
@@ -114,7 +114,8 @@ echo $interval->format('%R%a days');
<title><classname>DateTime</classname> object comparison</title>
<note>
<para>
- DateTime objects can be compared using
+ <classname>DateTimeImmutable</classname> and
+ <classname>DateTime</classname> objects can be compared using
<link linkend="language.operators.comparison">comparison
operators</link>.
</para>
</note>
diff --git a/reference/datetime/datetimeinterface/format.xml
b/reference/datetime/datetimeinterface/format.xml
index e11441277dd..0cb8641999c 100644
--- a/reference/datetime/datetimeinterface/format.xml
+++ b/reference/datetime/datetimeinterface/format.xml
@@ -2,9 +2,9 @@
<!-- $Revision$ -->
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
- <refname>DateTime::format</refname>
- <refname>DateTimeImmutable::format</refname>
<refname>DateTimeInterface::format</refname>
+ <refname>DateTimeImmutable::format</refname>
+ <refname>DateTime::format</refname>
<refname>date_format</refname>
<refpurpose>Returns date formatted according to given format</refpurpose>
</refnamediv>
@@ -12,16 +12,16 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
- <methodsynopsis role="oop">
- <modifier>public</modifier>
<type>string</type><methodname>DateTime::format</methodname>
+ <methodsynopsis role="DateTimeInterface">
+ <modifier>public</modifier>
<type>string</type><methodname>DateTimeInterface::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier>
<type>string</type><methodname>DateTimeImmutable::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
- <methodsynopsis role="DateTimeInterface">
- <modifier>public</modifier>
<type>string</type><methodname>DateTimeInterface::format</methodname>
+ <methodsynopsis role="oop">
+ <modifier>public</modifier>
<type>string</type><methodname>DateTime::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
diff --git a/reference/datetime/datetimeinterface/getoffset.xml
b/reference/datetime/datetimeinterface/getoffset.xml
index 780b2229479..a5504695562 100644
--- a/reference/datetime/datetimeinterface/getoffset.xml
+++ b/reference/datetime/datetimeinterface/getoffset.xml
@@ -2,9 +2,9 @@
<!-- $Revision$ -->
<refentry xml:id="datetime.getoffset" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
- <refname>DateTime::getOffset</refname>
- <refname>DateTimeImmutable::getOffset</refname>
<refname>DateTimeInterface::getOffset</refname>
+ <refname>DateTimeImmutable::getOffset</refname>
+ <refname>DateTime::getOffset</refname>
<refname>date_offset_get</refname>
<refpurpose>Returns the timezone offset</refpurpose>
</refnamediv>
@@ -12,16 +12,16 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
- <methodsynopsis role="oop">
- <modifier>public</modifier>
<type>int</type><methodname>DateTime::getOffset</methodname>
+ <methodsynopsis role="DateTimeInterface">
+ <modifier>public</modifier>
<type>int</type><methodname>DateTimeInterface::getOffset</methodname>
<void/>
</methodsynopsis>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier>
<type>int</type><methodname>DateTimeImmutable::getOffset</methodname>
<void/>
</methodsynopsis>
- <methodsynopsis role="DateTimeInterface">
- <modifier>public</modifier>
<type>int</type><methodname>DateTimeInterface::getOffset</methodname>
+ <methodsynopsis role="oop">
+ <modifier>public</modifier>
<type>int</type><methodname>DateTime::getOffset</methodname>
<void/>
</methodsynopsis>
<para>&style.procedural;</para>
@@ -78,8 +78,8 @@
<programlisting role="php">
<![CDATA[
<?php
-$winter = new DateTime('2010-12-21', new DateTimeZone('America/New_York'));
-$summer = new DateTime('2008-06-21', new DateTimeZone('America/New_York'));
+$winter = new DateTimeImmutable('2010-12-21', new
DateTimeZone('America/New_York'));
+$summer = new DateTimeImmutable('2008-06-21', new
DateTimeZone('America/New_York'));
echo $winter->getOffset() . "\n";
echo $summer->getOffset() . "\n";
diff --git a/reference/datetime/datetimeinterface/gettimestamp.xml
b/reference/datetime/datetimeinterface/gettimestamp.xml
index a14783dc282..4093c211115 100644
--- a/reference/datetime/datetimeinterface/gettimestamp.xml
+++ b/reference/datetime/datetimeinterface/gettimestamp.xml
@@ -2,9 +2,9 @@
<!-- $Revision$ -->
<refentry xml:id="datetime.gettimestamp" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
- <refname>DateTime::getTimestamp</refname>
- <refname>DateTimeImmutable::getTimestamp</refname>
<refname>DateTimeInterface::getTimestamp</refname>
+ <refname>DateTimeImmutable::getTimestamp</refname>
+ <refname>DateTime::getTimestamp</refname>
<refname>date_timestamp_get</refname>
<refpurpose>Gets the Unix timestamp</refpurpose>
</refnamediv>
@@ -12,16 +12,16 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
- <methodsynopsis role="oop">
- <modifier>public</modifier>
<type>int</type><methodname>DateTime::getTimestamp</methodname>
+ <methodsynopsis role="DateTimeInterface">
+ <modifier>public</modifier>
<type>int</type><methodname>DateTimeInterface::getTimestamp</methodname>
<void/>
</methodsynopsis>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier>
<type>int</type><methodname>DateTimeImmutable::getTimestamp</methodname>
<void/>
</methodsynopsis>
- <methodsynopsis role="DateTimeInterface">
- <modifier>public</modifier>
<type>int</type><methodname>DateTimeInterface::getTimestamp</methodname>
+ <methodsynopsis role="oop">
+ <modifier>public</modifier>
<type>int</type><methodname>DateTime::getTimestamp</methodname>
<void/>
</methodsynopsis>
<para>&style.procedural;</para>
@@ -86,7 +86,7 @@
<programlisting role="php">
<![CDATA[
<?php
-$date = new DateTime();
+$date = new DateTimeImmutable();
echo $date->getTimestamp();
?>
]]>
diff --git a/reference/datetime/datetimeinterface/gettimezone.xml
b/reference/datetime/datetimeinterface/gettimezone.xml
index b4f9f80aafb..cb21e1323ed 100644
--- a/reference/datetime/datetimeinterface/gettimezone.xml
+++ b/reference/datetime/datetimeinterface/gettimezone.xml
@@ -3,9 +3,9 @@
<refentry xml:id="datetime.gettimezone" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
- <refname>DateTime::getTimezone</refname>
- <refname>DateTimeImmutable::getTimezone</refname>
<refname>DateTimeInterface::getTimezone</refname>
+ <refname>DateTimeImmutable::getTimezone</refname>
+ <refname>DateTime::getTimezone</refname>
<refname>date_timezone_get</refname>
<refpurpose>Return time zone relative to given DateTime</refpurpose>
</refnamediv>
@@ -13,16 +13,16 @@
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
- <methodsynopsis role="oop">
- <modifier>public</modifier> <type
class="union"><type>DateTimeZone</type><type>false</type></type><methodname>DateTime::getTimezone</methodname>
+ <methodsynopsis role="DateTimeInterface">
+ <modifier>public</modifier> <type
class="union"><type>DateTimeZone</type><type>false</type></type><methodname>DateTimeInterface::getTimezone</methodname>
<void/>
</methodsynopsis>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier> <type
class="union"><type>DateTimeZone</type><type>false</type></type><methodname>DateTimeImmutable::getTimezone</methodname>
<void/>
</methodsynopsis>
- <methodsynopsis role="DateTimeInterface">
- <modifier>public</modifier> <type
class="union"><type>DateTimeZone</type><type>false</type></type><methodname>DateTimeInterface::getTimezone</methodname>
+ <methodsynopsis role="oop">
+ <modifier>public</modifier> <type
class="union"><type>DateTimeZone</type><type>false</type></type><methodname>DateTime::getTimezone</methodname>
<void/>
</methodsynopsis>
<para>&style.procedural;</para>
@@ -58,7 +58,7 @@
<programlisting role="php">
<![CDATA[
<?php
-$date = new DateTime(null, new DateTimeZone('Europe/London'));
+$date = new DateTimeImmutable(null, new DateTimeZone('Europe/London'));
$tz = $date->getTimezone();
echo $tz->getName();
?>
diff --git a/reference/datetime/datetimezone/getlocation.xml
b/reference/datetime/datetimezone/getlocation.xml
index 3eac24c1f1e..af47c12158d 100644
--- a/reference/datetime/datetimezone/getlocation.xml
+++ b/reference/datetime/datetimezone/getlocation.xml
@@ -78,6 +78,14 @@ Array
</para>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><function>DateTimeZone::listIdentifiers</function> to get a full or
+ partial list of all supported timezone identifiers</member>
+ </simplelist>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/datetime/datetimezone/getname.xml
b/reference/datetime/datetimezone/getname.xml
index 0238c88f6c0..6b6d22df6cd 100644
--- a/reference/datetime/datetimezone/getname.xml
+++ b/reference/datetime/datetimezone/getname.xml
@@ -42,8 +42,13 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- One of the timezone names in the
- <link linkend="timezones">list of timezones</link>.
+ Depending on zone type, UTC offset (type 1), timezone abbreviation (type
+ 2), and timezone identifiers as published in the IANA timezone database
+ (type 3), the descriptor string to create a new
+ <classname>DateTimeZone</classname> object with the same offset and/or
+ rules. For example <literal>02:00</literal>, <literal>CEST</literal>, or
+ one of the timezone names in the <link linkend="timezones">list of
+ timezones</link>.
</para>
</refsect1>
diff --git a/reference/datetime/datetimezone/gettransitions.xml
b/reference/datetime/datetimezone/gettransitions.xml
index da53e350963..aff48d7e305 100644
--- a/reference/datetime/datetimezone/gettransitions.xml
+++ b/reference/datetime/datetimezone/gettransitions.xml
@@ -83,7 +83,9 @@
<row>
<entry><literal>time</literal></entry>
<entry><type>string</type></entry>
- <entry><constant>DateTimeInterface::ISO8601</constant> time
string</entry>
+ <entry><constant>DateTimeInterface::ISO8601_EXPANDED</constant> (PHP
+ 8.2 and later), or <constant>DateTimeInterface::ISO8601</constant> (PHP
+ 8.1 and lower) time string</entry>
</row>
<row>
<entry><literal>offset</literal></entry>
diff --git a/reference/datetime/datetimezone/listabbreviations.xml
b/reference/datetime/datetimezone/listabbreviations.xml
index 8c650704c4d..a4f66a30d6f 100644
--- a/reference/datetime/datetimezone/listabbreviations.xml
+++ b/reference/datetime/datetimezone/listabbreviations.xml
@@ -21,8 +21,8 @@
<para>
The returned list of abbreviations includes all historical use of
abbreviations, which can lead to correct, but confusing entries.
- There are also conflicts, as "pst" is used both in the US and in the
- Philippines.
+ There are also conflicts, as <literal>PST</literal> is used both in the US
+ and in the Philippines.
</para>
<para>
The list that this function returns is therefore not suitable for building
diff --git a/reference/datetime/datetimezone/listidentifiers.xml
b/reference/datetime/datetimezone/listidentifiers.xml
index a4eacd2d731..17be91ee37c 100644
--- a/reference/datetime/datetimezone/listidentifiers.xml
+++ b/reference/datetime/datetimezone/listidentifiers.xml
@@ -38,7 +38,7 @@
<term><parameter>countryCode</parameter></term>
<listitem>
<para>
- A two-letter ISO 3166-1 compatible country code.
+ A two-letter (uppercase) ISO 3166-1 compatible country code.
</para>
<note>
<simpara>
@@ -55,7 +55,10 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Returns the array of timezone identifiers.
+ Returns the array of timezone identifiers. Only non-outdated items are
+ returned. To get all, including outdated timezone identifiers, use the
+ <literal>DateTimeZone::ALL_WITH_BC</literal> as value for
+ <parameter>countryCode</parameter>.
</para>
</refsect1>
@@ -93,7 +96,7 @@
&reftitle.examples;
<para>
<example>
- <title>A <function>timezone_identifiers_list</function> example</title>
+ <title>A <methodname>DateTimeZone::listIdentifiers</methodname>
example</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -112,6 +115,102 @@ Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmara
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title>Listing identifiers for a specific region</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
+for ($i=0; $i < 5; $i++) {
+ echo "$timezone_identifiers[$i]\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Asia/Aden
+Asia/Almaty
+Asia/Amman
+Asia/Anadyr
+Asia/Aqtau
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title>Listing identifiers for multiple regions</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC
);
+echo join( ', ', $timezone_identifiers );
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
+Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
+Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
+Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
+Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
+Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
+Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
+Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
+Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
+Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
+Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
+Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
+Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
+Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
+Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
+Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
+Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
+Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
+Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
+Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
+Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
+Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
+Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
+Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
+Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
+Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title>Listing identifiers for a single country</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
+foreach( $timezone_identifiers as $identifier ) {
+ echo "$identifier\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs.similar;
+ <screen>
+<![CDATA[
+Europe/Kyiv
+Europe/Simferopol
+Europe/Uzhgorod
+Europe/Zaporozhye
]]>
</screen>
</example>
diff --git a/reference/datetime/formats.xml b/reference/datetime/formats.xml
index 4c3bf85c6f7..13fb2325d31 100644
--- a/reference/datetime/formats.xml
+++ b/reference/datetime/formats.xml
@@ -865,9 +865,10 @@ class DateTime#1 (3) {
</row>
<row>
<entry><literal>unit</literal></entry>
- <entry>(('sec' | 'second' | 'min' | 'minute' |
'hour' | 'day' |
- 'fortnight' | 'forthnight' | 'month' | 'year')
's'?) | 'weeks' |
- <literal>daytext</literal></entry>
+ <entry>'ms' | 'µs' | (( 'msec' | 'millisecond'
| 'µsec' | 'microsecond'
+ | 'usec' | 'sec' | 'second' | 'min' |
'minute' | 'hour' | 'day' |
+ 'fortnight' | 'forthnight' | 'month' | 'year')
's'?) | 'weeks' |
+ <literal>daytext</literal></entry>
</row>
</tbody>
</tgroup>
