Fixed bug #81319: Unfortunate example on time() man page

This commit is contained in:
Derick Rethans 2022-06-04 17:41:23 +01:00
parent f0c9bb04d7
commit 532a253c43
2 changed files with 30 additions and 19 deletions

View file

@ -3,9 +3,9 @@
<refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>date</refname>
<refpurpose>Format a local time/date</refpurpose>
<refpurpose>Format a Unix timestamp</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
@ -15,10 +15,16 @@
</methodsynopsis>
<para>
Returns a string formatted according to the given format string using the
given integer <parameter>timestamp</parameter> or the current time
if no timestamp is given. In other words, <parameter>timestamp</parameter>
given integer <parameter>Unix timestamp</parameter> or the current time
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>
</refsect1>
<refsect1 role="parameters">
@ -28,30 +34,30 @@
<term><parameter>format</parameter></term>
<listitem>
<para>
Format accepted by <function>DateTimeInterface::format</function>.
Format accepted by <methodname>DateTimeInterface::format</methodname>.
</para>
</listitem>
</varlistentry>
&date.timestamp.description;
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a formatted date string. If a non-numeric value is used for
<parameter>timestamp</parameter>, &false; is returned and an
Returns a formatted date string. If a non-numeric value is used for
<parameter>timestamp</parameter>, &false; is returned and an
<constant>E_WARNING</constant> level error is emitted.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&date.timezone.errors.description;
</refsect1>
<refsect1 role="changelog">
@ -211,6 +217,8 @@ $today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (the MySQ
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>DateTimeImmutable::__construct</methodname></member>
<member><methodname>DateTimeInterface::format</methodname></member>
<member><function>gmdate</function></member>
<member><function>idate</function></member>
<member><function>getdate</function></member>
@ -218,7 +226,6 @@ $today = date("Y-m-d H:i:s"); // 2001-03-10 17:16:18 (the MySQ
<member><function>mktime</function></member>
<member><methodname>IntlDateFormatter::format</methodname></member>
<member><function>time</function></member>
<member><function>DateTimeImmutable::__construct</function></member>
<member><link linkend="datetime.constants.types">Predefined DateTime Constants</link></member>
</simplelist>
</para>

View file

@ -16,6 +16,15 @@
Returns the current time measured in the number of seconds since
the Unix Epoch (January 1 1970 00:00:00 GMT).
</para>
<note>
<para>
Unix timestamps do not contain any information with regards to any local
timezone. It is recommended to use the
<classname>DateTimeImmutable</classname> class for handling date and time
information in order to avoid the pitfalls that come with just Unix
timestamps.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
@ -38,11 +47,7 @@
<programlisting role="php">
<![CDATA[
<?php
$nextWeek = time() + (7 * 24 * 60 * 60);
// 7 days; 24 hours; 60 mins; 60 secs
echo 'Now: '. date('Y-m-d') ."\n";
echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n";
// or using strtotime():
echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
?>
]]>
@ -50,9 +55,8 @@ echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
&example.outputs.similar;
<screen>
<![CDATA[
Now: 2005-03-30
Next Week: 2005-04-06
Next Week: 2005-04-06
Now: 2022-06-04
Next Week: 2022-06-11
]]>
</screen>
</example>