Author: Derick Rethans (derickr)
Date: 2022-08-26T15:20:37+01:00
Commit: https://github.com/php/doc-en/commit/5c951013ca04161992efed8b86fb40f55669958e
Raw diff: https://github.com/php/doc-en/commit/5c951013ca04161992efed8b86fb40f55669958e.diff
Incorporate useful information from notes (take #3)
Changed paths:
M reference/datetime/datetime/createfromformat.xml
M reference/datetime/formats.xml
M reference/datetime/functions/date-parse-from-format.xml
M reference/datetime/functions/date-parse.xml
M reference/datetime/functions/date-sub.xml
M reference/datetime/functions/date-sun-info.xml
M reference/datetime/functions/date-sunrise.xml
M reference/datetime/functions/date-sunset.xml
M reference/datetime/functions/date.xml
M reference/datetime/functions/gmdate.xml
M reference/datetime/functions/gmmktime.xml
M reference/datetime/functions/gmstrftime.xml
M reference/datetime/functions/idate.xml
M reference/datetime/functions/microtime.xml
M reference/datetime/functions/mktime.xml
M reference/datetime/functions/strftime.xml
M reference/datetime/functions/strptime.xml
M reference/datetime/functions/strtotime.xml
M reference/datetime/functions/time.xml
M reference/datetime/functions/timezone-name-from-abbr.xml
M reference/datetime/functions/timezone-version-get.xml
Diff:
diff --git a/reference/datetime/datetime/createfromformat.xml
b/reference/datetime/datetime/createfromformat.xml
index d85efdb6c10..e1365e161ea 100644
--- a/reference/datetime/datetime/createfromformat.xml
+++ b/reference/datetime/datetime/createfromformat.xml
@@ -16,13 +16,6 @@
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
<methodparam choice="opt"><type
class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>&style.procedural;</para>
- <methodsynopsis role="procedural">
- <type
class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
-
<methodparam><type>string</type><parameter>format</parameter></methodparam>
-
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
- <methodparam choice="opt"><type
class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
- </methodsynopsis>
<para>
Returns a new DateTime object representing the date and time specified by the
@@ -33,6 +26,14 @@
Like <methodname>DateTimeImmutable::createFromFormat</methodname> but
creates an <classname>DateTime</classname> object.
</para>
+
+ <para>&style.procedural;</para>
+ <methodsynopsis role="procedural">
+ <type
class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
+
<methodparam><type>string</type><parameter>format</parameter></methodparam>
+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
+ <methodparam choice="opt"><type
class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
+ </methodsynopsis>
<para>
The procedural version takes the <classname>DateTime</classname> object as
its first argument.
diff --git a/reference/datetime/formats.xml b/reference/datetime/formats.xml
index b4cd4c7d214..6356c6025d9 100644
--- a/reference/datetime/formats.xml
+++ b/reference/datetime/formats.xml
@@ -778,6 +778,11 @@ object(DateTimeImmutable)#1 (3) {
<entry>"@" "-"? [0-9]+</entry>
<entry>"@1215282385"</entry>
</row>
+ <row>
+ <entry>Unix Timestamp with microseconds</entry>
+ <entry>"@" "-"? [0-9]+ "." [0-9]{0,6}</entry>
+ <entry>"@1607974647.503686"</entry>
+ </row>
<row>
<entry>XMLRPC</entry>
<entry><literal>YY</literal> <literal>MM</literal>
<literal>DD</literal> "T" <literal>hh</literal> ":"
<literal>II</literal> ":" <literal>SS</literal></entry>
diff --git a/reference/datetime/functions/date-parse-from-format.xml
b/reference/datetime/functions/date-parse-from-format.xml
index 86462d833fc..aeadb48123a 100644
--- a/reference/datetime/functions/date-parse-from-format.xml
+++ b/reference/datetime/functions/date-parse-from-format.xml
@@ -27,7 +27,7 @@
<term><parameter>format</parameter></term>
<listitem>
<para>
- Format accepted by <function>DateTime::createFromFormat</function>.
+ Format accepted by <function>DateTimeImmutable::createFromFormat</function>.
</para>
</listitem>
</varlistentry>
@@ -49,6 +49,48 @@
<para>
Returns associative array with detailed info about given date/time.
</para>
+ <para>
+ The returned array has keys for <literal>year</literal>,
+ <literal>month</literal>, <literal>day</literal>,
<literal>hour</literal>,
+ <literal>minute</literal>, <literal>second</literal>,
+ <literal>fraction</literal>, and <literal>is_localtime</literal>.
+ </para>
+ <para>
+ If <literal>is_localtime</literal> is present then
+ <literal>zone_type</literal> indicates the type of timezone. For type
+ <literal>1</literal> (UTC offset) the <literal>zone</literal>,
+ <literal>is_dst</literal> fields are added; for type
<literal>2</literal>
+ (abbreviation) the fields <literal>tz_abbr</literal>,
+ <literal>is_dst</literal> are added; and for type <literal>3</literal>
+ (timezone identifier) the <literal>tz_abbr</literal>,
+ <literal>tz_id</literal> are added.
+ </para>
+ <para>
+ The array includes <literal>warning_count</literal> and
+ <literal>warnings</literal> fields. The first one indicate how many
+ warnings there were.
+ The keys of elements <literal>warnings</literal> array indicate the
+ position in the given <parameter>datetime</parameter> where the warning
+ occurred, with the string value describing the warning itself. An example
+ below shows such a warning.
+ </para>
+ <para>
+ The array also contains <literal>error_count</literal> and
+ <literal>errors</literal> fields. The first one indicate how many errors
+ were found.
+ The keys of elements <literal>errors</literal> array indicate the
+ position in the given <parameter>datetime</parameter> where the error
+ occurred, with the string value describing the error itself. An example
+ below shows such an error.
+ </para>
+ <warning>
+ <para>
+ The number of array elements in the <literal>warnings</literal> and
+ <literal>errors</literal> arrays might be less than
+ <literal>warning_count</literal> or <literal>error_count</literal> if
they
+ occurred at the same position.
+ </para>
+ </warning>
</refsect1>
<refsect1 role="changelog">
@@ -115,16 +157,70 @@ Array
[zone] => 3600
[is_dst] =>
)
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title><function>date_parse_from_format</function> with warnings
example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$date = "26 August 2022 22:30 pm";
+$parsed = date_parse_from_format("j F Y G:i a", $date);
+
+echo "Warnings count: ", $parsed['warning_count'], "\n";
+foreach ($parsed['warnings'] as $position => $message) {
+ echo "\tOn position {$position}: {$message}\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Warnings count: 1
+ On position 23: The parsed time was invalid
+]]>
+ </screen>
+ </example>
+ </para>
+
+ <para>
+ <example>
+ <title><function>date_parse_from_format</function> with errors
example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$date = "26 August 2022 CEST";
+$parsed = date_parse_from_format("j F Y H:i", $date);
+
+echo "Errors count: ", $parsed['error_count'], "\n";
+foreach ($parsed['errors'] as $position => $message) {
+ echo "\tOn position {$position}: {$message}\n";
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Errors count: 3
+ On position 15: A two digit hour could not be found
+ On position 19: Data missing
]]>
</screen>
</example>
</para>
</refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
- <member><function>DateTime::createFromFormat</function></member>
+
<member><function>DateTimeImmutable::createFromFormat</function></member>
<member><function>checkdate</function></member>
</simplelist>
</para>
diff --git a/reference/datetime/functions/date-parse.xml
b/reference/datetime/functions/date-parse.xml
index e5bfdb8ea7e..318e0d9e1a7 100644
--- a/reference/datetime/functions/date-parse.xml
+++ b/reference/datetime/functions/date-parse.xml
@@ -54,6 +54,56 @@
Returns <type>array</type> with information about the parsed date/time
on success&return.falseforfailure;.
</para>
+ <para>
+ The returned array has keys for <literal>year</literal>,
+ <literal>month</literal>, <literal>day</literal>,
<literal>hour</literal>,
+ <literal>minute</literal>, <literal>second</literal>,
+ <literal>fraction</literal>, and <literal>is_localtime</literal>.
+ </para>
+ <para>
+ If <literal>is_localtime</literal> is present then
+ <literal>zone_type</literal> indicates the type of timezone. For type
+ <literal>1</literal> (UTC offset) the <literal>zone</literal>,
+ <literal>is_dst</literal> fields are added; for type
<literal>2</literal>
+ (abbreviation) the fields <literal>tz_abbr</literal>,
+ <literal>is_dst</literal> are added; and for type <literal>3</literal>
+ (timezone identifier) the <literal>tz_abbr</literal>,
+ <literal>tz_id</literal> are added.
+ </para>
+ <para>
+ If relative time elements are present in the
+ <parameter>datetime</parameter> string such as <literal>+3
days</literal>,
+ the then returned array includes a nested array with the key
+ <literal>relative</literal>. This array then contains the keys
+ <literal>year</literal>, <literal>month</literal>,
<literal>day</literal>,
+ <literal>hour</literal>, <literal>minute</literal>,
+ <literal>second</literal>, and if necessary <literal>weekday</literal>,
and
+ <literal>weekdays</literal>, depending on the string that was passed in.
+ </para>
+ <para>
+ The array includes <literal>warning_count</literal> and
+ <literal>warnings</literal> fields. The first one indicate how many
+ warnings there were.
+ The keys of elements <literal>warnings</literal> array indicate the
+ position in the given <parameter>datetime</parameter> where the warning
+ occurred, with the string value describing the warning itself.
+ </para>
+ <para>
+ The array also contains <literal>error_count</literal> and
+ <literal>errors</literal> fields. The first one indicate how many errors
+ were found.
+ The keys of elements <literal>errors</literal> array indicate the
+ position in the given <parameter>datetime</parameter> where the error
+ occurred, with the string value describing the error itself.
+ </para>
+ <warning>
+ <para>
+ The number of array elements in the <literal>warnings</literal> and
+ <literal>errors</literal> arrays might be less than
+ <literal>warning_count</literal> or <literal>error_count</literal> if
they
+ occurred at the same position.
+ </para>
+ </warning>
</refsect1>
<refsect1 role="errors">
@@ -335,7 +385,7 @@ array(13) {
<simplelist>
<member><function>date_parse_from_format</function> for
parsing a <parameter>datetime</parameter> with a specific given
format</member>
- <member><function>checkdate</function></member>
+ <member><function>checkdate</function> for Gregorian date
validation</member>
<member><function>getdate</function></member>
</simplelist>
</para>
diff --git a/reference/datetime/functions/date-sub.xml b/reference/datetime/functions/date-sub.xml
index 849be4bfb34..72cedc256bb 100644
--- a/reference/datetime/functions/date-sub.xml
+++ b/reference/datetime/functions/date-sub.xml
@@ -13,6 +13,16 @@
</para>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>DateTimeImmutable::sub</function></member>
+ <member><function>DateTime::sub</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/datetime/functions/date-sun-info.xml
b/reference/datetime/functions/date-sun-info.xml
index b83236c9e52..1195f65ef7f 100644
--- a/reference/datetime/functions/date-sun-info.xml
+++ b/reference/datetime/functions/date-sun-info.xml
@@ -84,7 +84,8 @@
<term><literal>civil_twilight_begin</literal></term>
<listitem>
<simpara>
- The start of the civil dawn (zenith angle = 96°). It ends at
<literal>sunrise</literal>.
+ The start of the civil dawn (zenith angle = 96°). It ends at
+ <literal>sunrise</literal>.
</simpara>
</listitem>
</varlistentry>
@@ -92,7 +93,8 @@
<term><literal>civil_twilight_end</literal></term>
<listitem>
<simpara>
- The end of the civil dusk (zenith angle = 96°). It starts at
<literal>sunset</literal>.
+ The end of the civil dusk (zenith angle = 96°). It starts at
+ <literal>sunset</literal>.
</simpara>
</listitem>
</varlistentry>
@@ -196,86 +198,99 @@ astronomical_twilight_end: 17:12:00
]]>
</screen>
</example>
+ </para>
+
+ <para>
<example>
- <title>Polar night</title>
+ <title>Polar night, with some processing</title>
<programlisting role="php">
<![CDATA[
<?php
-var_dump(date_sun_info(strtotime("2017-12-21"), 90, 0));
+$tz = new \DateTimeZone('America/Anchorage');
+
+$si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
+foreach ($si as $key => $value) {
+ echo
+ match ($value) {
+ true => 'always',
+ false => 'never',
+ default => date_create("@{$value}")->setTimeZone($tz)->format(
'H:i:s T' ),
+ },
+ ": {$key}",
+ "\n";
+}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
-array(9) {
- ["sunrise"]=>
- bool(false)
- ["sunset"]=>
- bool(false)
- ["transit"]=>
- int(1513857490)
- ["civil_twilight_begin"]=>
- bool(false)
- ["civil_twilight_end"]=>
- bool(false)
- ["nautical_twilight_begin"]=>
- bool(false)
- ["nautical_twilight_end"]=>
- bool(false)
- ["astronomical_twilight_begin"]=>
- bool(false)
- ["astronomical_twilight_end"]=>
- bool(false)
-}
+never: sunrise
+never: sunset
+12:52:18 AKST: transit
+10:53:19 AKST: civil_twilight_begin
+14:51:17 AKST: civil_twilight_end
+09:01:47 AKST: nautical_twilight_begin
+16:42:48 AKST: nautical_twilight_end
+07:40:47 AKST: astronomical_twilight_begin
+18:03:49 AKST: astronomical_twilight_end
]]>
</screen>
</example>
+ </para>
+
+ <para>
<example>
- <title>Midnight sun</title>
+ <title>Midnight sun (Tromsø, Norway)</title>
<programlisting role="php">
<![CDATA[
<?php
-var_dump(date_sun_info(strtotime("2017-06-21"), 90, 0));
+$si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
+print_r($si);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
-array(9) {
- ["sunrise"]=>
- bool(true)
- ["sunset"]=>
- bool(true)
- ["transit"]=>
- int(1498046510)
- ["civil_twilight_begin"]=>
- bool(true)
- ["civil_twilight_end"]=>
- bool(true)
- ["nautical_twilight_begin"]=>
- bool(true)
- ["nautical_twilight_end"]=>
- bool(true)
- ["astronomical_twilight_begin"]=>
- bool(true)
- ["astronomical_twilight_end"]=>
- bool(true)
-}
+Array
+(
+ [sunrise] => 1
+ [sunset] => 1
+ [transit] => 1656240426
+ [civil_twilight_begin] => 1
+ [civil_twilight_end] => 1
+ [nautical_twilight_begin] => 1
+ [nautical_twilight_end] => 1
+ [astronomical_twilight_begin] => 1
+ [astronomical_twilight_end] => 1
+)
]]>
</screen>
</example>
</para>
- </refsect1>
- <refsect1 role="seealso">
- &reftitle.seealso;
<para>
- <simplelist>
- <member><function>date_sunrise</function></member>
- <member><function>date_sunset</function></member>
- </simplelist>
+ <example>
+ <title>Calculating length of day (Kyiv)</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
+$diff = $si['sunset'] - $si['sunrise'];
+echo "Length of day: ",
+ floor($diff / 3600), "h ",
+ floor(($diff % 3600) / 60), "s\n";
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Length of day: 13h 56s
+]]>
+ </screen>
+ </example>
</para>
</refsect1>
diff --git a/reference/datetime/functions/date-sunrise.xml
b/reference/datetime/functions/date-sunrise.xml
index e04c2fc4c53..63495bb3092 100644
--- a/reference/datetime/functions/date-sunrise.xml
+++ b/reference/datetime/functions/date-sunrise.xml
@@ -7,7 +7,13 @@
</refnamediv>
<refsynopsisdiv>
- &warn.deprecated.function-8-1-0;
+ <warning>
+ <para>
+ This function has been <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
+ Relying on this function is highly discouraged. Use
+ <function>date_sun_info</function> instead.
+ </para>
+ </warning>
</refsynopsisdiv>
<refsect1 role="description">
@@ -248,7 +254,6 @@ bool(false)
&reftitle.seealso;
<para>
<simplelist>
- <member><function>date_sunset</function></member>
<member><function>date_sun_info</function></member>
</simplelist>
</para>
diff --git a/reference/datetime/functions/date-sunset.xml
b/reference/datetime/functions/date-sunset.xml
index ae06d909274..9cd0608ea29 100644
--- a/reference/datetime/functions/date-sunset.xml
+++ b/reference/datetime/functions/date-sunset.xml
@@ -9,7 +9,13 @@
</refnamediv>
<refsynopsisdiv>
- &warn.deprecated.function-8-1-0;
+ <warning>
+ <para>
+ This function has been <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
+ Relying on this function is highly discouraged. Use
+ <function>date_sun_info</function> instead.
+ </para>
+ </warning>
</refsynopsisdiv>
<refsect1 role="description">
@@ -250,7 +256,6 @@ bool(false)
&reftitle.seealso;
<para>
<simplelist>
- <member><function>date_sunrise</function></member>
<member><function>date_sun_info</function></member>
</simplelist>
</para>
diff --git a/reference/datetime/functions/date.xml b/reference/datetime/functions/date.xml
index c61c0c41d4a..13136e7e9ce 100644
--- a/reference/datetime/functions/date.xml
+++ b/reference/datetime/functions/date.xml
@@ -19,12 +19,14 @@
if no timestamp is given. In other words, <parameter>timestamp</parameter>
is optional and defaults to the value of <function>time</function>.
</para>
- <para>
- Unix timestamps do not handle timezones. Use the
- <classname>DateTimeImmutable</classname> class, and its
- <methodname>DateTimeInterface::format</methodname> formatting method to
- format date/time information with a timezone attached.
- </para>
+ <warning>
+ <para>
+ Unix timestamps do not handle timezones. Use the
+ <classname>DateTimeImmutable</classname> class, and its
+ <methodname>DateTimeInterface::format</methodname> formatting method to
+ format date/time information with a timezone attached.
+ </para>
+ </warning>
</refsect1>
<refsect1 role="parameters">
diff --git a/reference/datetime/functions/gmdate.xml b/reference/datetime/functions/gmdate.xml
index bd1fcc4026a..90c4dbcab11 100644
--- a/reference/datetime/functions/gmdate.xml
+++ b/reference/datetime/functions/gmdate.xml
@@ -95,6 +95,8 @@ echo gmdate("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
&reftitle.seealso;
<para>
<simplelist>
+
<member><methodname>DateTimeImmutable::__construct</methodname></member>
+ <member><methodname>DateTimeInterface::format</methodname></member>
<member><function>date</function></member>
<member><function>mktime</function></member>
<member><function>gmmktime</function></member>
diff --git a/reference/datetime/functions/gmmktime.xml b/reference/datetime/functions/gmmktime.xml
index 1c968c82fca..dbae60ddf33 100644
--- a/reference/datetime/functions/gmmktime.xml
+++ b/reference/datetime/functions/gmmktime.xml
@@ -161,6 +161,7 @@ echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0,
7, 1, 2000));
&reftitle.seealso;
<para>
<simplelist>
+ <member>The <classname>DateTimeImmutable</classname> class</member>
<member><function>mktime</function></member>
<member><function>date</function></member>
<member><function>time</function></member>
diff --git a/reference/datetime/functions/gmstrftime.xml
b/reference/datetime/functions/gmstrftime.xml
index 7c4d793313e..03c5d130ffc 100644
--- a/reference/datetime/functions/gmstrftime.xml
+++ b/reference/datetime/functions/gmstrftime.xml
@@ -28,6 +28,13 @@
"Dec 31 1998 20:00:00", while the second prints "Jan 01 1999
01:00:00".
</para>
+ <warning>
+ <para>
+ This function depends on operating system locale information, which might
+ be inconsistent with each other, or not available at all. Instead use the
+ <methodname>IntlDateFormatter::format</methodname> method.
+ </para>
+ </warning>
</refsect1>
<refsect1 role="parameters">
@@ -105,6 +112,8 @@ echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) .
"\n";
&reftitle.seealso;
<para>
<simplelist>
+ <member><methodname>IntlDateFormatter::format</methodname></member>
+ <member><methodname>DateTimeInterface::format</methodname></member>
<member><function>strftime</function></member>
</simplelist>
</para>
diff --git a/reference/datetime/functions/idate.xml b/reference/datetime/functions/idate.xml
index ea5d62549f2..4cff3c0e30f 100644
--- a/reference/datetime/functions/idate.xml
+++ b/reference/datetime/functions/idate.xml
@@ -3,7 +3,7 @@
<refentry xml:id="function.idate" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>idate</refname>
- <refpurpose>Format a local time/date as integer</refpurpose>
+ <refpurpose>Format a local time/date part as integer</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -213,6 +213,7 @@ echo idate('y', $timestamp);
&reftitle.seealso;
<para>
<simplelist>
+ <member><methodname>DateTimeInterface::format</methodname></member>
<member><function>date</function></member>
<member><function>getdate</function></member>
<member><function>time</function></member>
diff --git a/reference/datetime/functions/microtime.xml b/reference/datetime/functions/microtime.xml
index c176a9635de..73413d84955 100644
--- a/reference/datetime/functions/microtime.xml
+++ b/reference/datetime/functions/microtime.xml
@@ -47,7 +47,7 @@
the form "msec sec", where <literal>sec</literal> is the number of seconds
since the Unix epoch (0:00:00 January 1,1970 GMT), and <literal>msec</literal>
measures microseconds that have elapsed since <literal>sec</literal>
- and is also expressed in seconds.
+ and is also expressed in seconds as a decimal fraction.
</para>
<para>
If <parameter>as_float</parameter> is set to &true;, then
diff --git a/reference/datetime/functions/mktime.xml b/reference/datetime/functions/mktime.xml
index a61b23d5cbd..276905e25a3 100644
--- a/reference/datetime/functions/mktime.xml
+++ b/reference/datetime/functions/mktime.xml
@@ -28,6 +28,15 @@
arguments omitted or &null; will be set to the current value according
to the local date and time.
</para>
+ <warning>
+ <para>
+ Please note that the ordering of arguments is in an odd order:
+ <parameter>month</parameter>, <parameter>day</parameter>,
+ <parameter>year</parameter>, and not in the more reasonable order of
+ <parameter>year</parameter>, <parameter>month</parameter>,
+ <parameter>day</parameter>.
+ </para>
+ </warning>
<simpara>
Calling <function>mktime</function> without arguments is deprecated.
<function>time</function> can be used to get the current timestamp.
@@ -215,6 +224,7 @@ echo strftime("Last day in Feb 2000 is: %d", $lastday);
&reftitle.seealso;
<para>
<simplelist>
+ <member>The <classname>DateTimeImmutable</classname> class</member>
<member><function>checkdate</function></member>
<member><function>gmmktime</function></member>
<member><function>date</function></member>
diff --git a/reference/datetime/functions/strftime.xml b/reference/datetime/functions/strftime.xml
index 73439725271..43ca443c899 100644
--- a/reference/datetime/functions/strftime.xml
+++ b/reference/datetime/functions/strftime.xml
@@ -26,17 +26,21 @@
names and other language-dependent strings respect the current locale set
with <function>setlocale</function>.
</para>
- <para>
- Not all conversion specifiers may be supported by your C library, in which
- case they will not be supported by PHP's <function>strftime</function>.
- Additionally, not all platforms support negative timestamps, so your
- date range may be limited to no earlier than the Unix epoch. This means that
- %e, %T, %R and, %D (and possibly others) - as well as dates prior to
- <literal>Jan 1, 1970</literal> - will not work on Windows, some Linux
- distributions, and a few other operating systems. For Windows systems, a
- complete overview of supported conversion specifiers can be found at
- <link
xlink:href="&url.strftime.win32;"><acronym>MSDN</acronym></link>.
- </para>
+ <warning>
+ <para>
+ Not all conversion specifiers may be supported by your C library, in which
+ case they will not be supported by PHP's <function>strftime</function>.
+ Additionally, not all platforms support negative timestamps, so your
+ date range may be limited to no earlier than the Unix epoch. This means that
+ %e, %T, %R and, %D (and possibly others) - as well as dates prior to
+ <literal>Jan 1, 1970</literal> - will not work on Windows, some Linux
+ distributions, and a few other operating systems. For Windows systems, a
+ complete overview of supported conversion specifiers can be found at
+ <link
xlink:href="&url.strftime.win32;"><acronym>MSDN</acronym></link>.
+ Instead use the
+ <methodname>IntlDateFormatter::format</methodname> method.
+ </para>
+ </warning>
</refsect1>
<refsect1 role="parameters">
@@ -674,6 +678,8 @@ Unknown format : 'v'
&reftitle.seealso;
<para>
<simplelist>
+ <member><methodname>IntlDateFormatter::format</methodname></member>
+ <member><methodname>DateTimeInterface::format</methodname></member>
<member><link xlink:href="&url.strftime.format.designer;">Online
strftime() format design tool</link></member>
<member><function>setlocale</function></member>
<member><function>mktime</function></member>
diff --git a/reference/datetime/functions/strptime.xml b/reference/datetime/functions/strptime.xml
index e0fe0c84792..a29974e8886 100644
--- a/reference/datetime/functions/strptime.xml
+++ b/reference/datetime/functions/strptime.xml
@@ -215,10 +215,11 @@ Array
&reftitle.seealso;
<para>
<simplelist>
+ <member><methodname>IntlDateFormatter::parse</methodname></member>
+ <member><methodname>DateTime::createFromFormat</methodname></member>
<member><function>checkdate</function></member>
<member><function>strftime</function></member>
<member><function>date_parse_from_format</function></member>
- <member><function>DateTime::createFromFormat</function></member>
</simplelist>
</para>
</refsect1>
diff --git a/reference/datetime/functions/strtotime.xml b/reference/datetime/functions/strtotime.xml
index cfbefd72acc..ad8a33c2a04 100644
--- a/reference/datetime/functions/strtotime.xml
+++ b/reference/datetime/functions/strtotime.xml
@@ -188,8 +188,9 @@ if (($timestamp = strtotime($str)) === false) {
&reftitle.seealso;
<para>
<simplelist>
+ <member><classname>DateTimeImmutable</classname></member>
+
<member><methodname>DateTimeImmutable::createFromFormat</methodname></member>
<member><link linkend="datetime.formats">Date and Time
Formats</link></member>
- <member><methodname>DateTime::createFromFormat</methodname></member>
<member><function>checkdate</function></member>
<member><function>strptime</function></member>
</simplelist>
diff --git a/reference/datetime/functions/time.xml b/reference/datetime/functions/time.xml
index c81979c4149..500de7170f7 100644
--- a/reference/datetime/functions/time.xml
+++ b/reference/datetime/functions/time.xml
@@ -75,6 +75,7 @@ Now: 1660338149
&reftitle.seealso;
<para>
<simplelist>
+ <member><classname>DateTimeImmutable</classname></member>
<member><function>date</function></member>
<member><function>microtime</function></member>
</simplelist>
diff --git a/reference/datetime/functions/timezone-name-from-abbr.xml
b/reference/datetime/functions/timezone-name-from-abbr.xml
index a707cca6ff6..bc0fbd1c1da 100644
--- a/reference/datetime/functions/timezone-name-from-abbr.xml
+++ b/reference/datetime/functions/timezone-name-from-abbr.xml
@@ -3,7 +3,7 @@
<refentry xml:id="function.timezone-name-from-abbr" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>timezone_name_from_abbr</refname>
- <refpurpose>Returns the timezone name from abbreviation</refpurpose>
+ <refpurpose>Returns a timezone name by guessing from abbreviation and UTC
offset</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
diff --git a/reference/datetime/functions/timezone-version-get.xml
b/reference/datetime/functions/timezone-version-get.xml
index 9add0a0d9d6..0125bc23302 100644
--- a/reference/datetime/functions/timezone-version-get.xml
+++ b/reference/datetime/functions/timezone-version-get.xml
@@ -26,7 +26,21 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Returns a <type>string</type>.
+ Returns a <type>string</type> in the format
+ <literal>YYYY.increment</literal>, such as <literal>2022.2</literal>.
+ </para>
+ <para>
+ If you have a timezone database version that is old (for example, it shows
+ not the current year), then you can update the timezone information by
+ either upgrading your PHP version, or installing the <link
+ xlink:href="&url.pecl.package;timezonedb">timezonedb</link> PECL package.
+ </para>
+ <para>
+ Some Linux distributions patch PHP's date/time support to use an
+ alternative source for timezone information. In which case this function
+ will return <literal>0.system</literal>. You are encouraged to install the
+ <link xlink:href="&url.pecl.package;timezonedb">timezonedb</link> PECL
+ package in that case as well.
</para>
</refsect1>
@@ -45,7 +59,7 @@ echo timezone_version_get();
&example.outputs.similar;
<screen>
<![CDATA[
-2009.7
+2022.2
]]>
</screen>
</example>