Skip to content

Commit 1a9ee81

Browse files
derickrderickr
committed
Incorporate useful information from notes (take #1)
1 parent b47f261 commit 1a9ee81

29 files changed

+336
-89
lines changed

‎language-snippets.ent

+2-2
Original file line numberDiff line numberDiff line change
@@ -1400,8 +1400,8 @@ The function modifies this object.</para></listitem></varlistentry>'>
14001400
<parameter>object</parameter></term><listitem><para>Procedural style only: A <classname>DateTimeZone</classname> object
14011401
returned by <function>timezone_open</function></para></listitem></varlistentry>'>
14021402

1403-
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1404-
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new modified <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object &return.falseforfailure;.'>
1403+
<!ENTITY date.datetime.return.modifiedobjectorfalseforfailure 'Returns the modified <classname xmlns="http://docbook.org/ns/docbook">DateTime</classname> object for method chaining&return.falseforfailure;.'>
1404+
<!ENTITY date.datetimeimmutable.return.modifiedobjectorfalseforfailure 'Returns a new <classname xmlns="http://docbook.org/ns/docbook">DateTimeImmutable</classname> object with the modified data &return.falseforfailure;.'>
14051405

14061406
<!ENTITY date.timezone.dbversion 'This list is based upon the timezone database version'>
14071407

‎reference/datetime/book.xml

+8-14
Original file line numberDiff line numberDiff line change
@@ -10,27 +10,21 @@
1010
<preface xml:id="intro.datetime">
1111
&reftitle.intro;
1212
<para>
13-
These functions allow you to get the date and time from the server
14-
where your PHP scripts are running. You can use these functions to format the
15-
date and time in many different ways.
13+
The <classname>DateTimeImmutable</classname> and related classes allow you
14+
represent date/time information. The objects can be created by passing in a
15+
string presentation of date/time information, or from the current system's
16+
time.
17+
</para>
18+
<para>
19+
A rich set of methods is supplied to modify and format this information
20+
as well, including handling timezones and DST transitions.
1621
</para>
1722
<para>
1823
The date and time information is internally stored as a 64-bit number so
1924
all conceivably useful dates (including negative years) are supported. The
2025
range is from about 292 billion years in the past to the same in the
2126
future.
2227
</para>
23-
<note>
24-
<simpara>
25-
Please keep in mind that these functions are dependent on
26-
the locale settings of your server. Make sure to take
27-
daylight saving time (use e.g.
28-
<literal>$date = $date->modify('+7 days')</literal> and not
29-
<literal>$date += 7*24*60*60</literal>)
30-
and leap years into consideration when working
31-
with these functions.
32-
</simpara>
33-
</note>
3428
<note>
3529
<simpara>
3630
The timezones referenced in this section can be found in the

‎reference/datetime/datetime.xml

+26-4
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,16 @@
1818
except objects are modified itself when modification methods such as
1919
<function>DateTime::modify</function> are called.
2020
</para>
21-
<para>
22-
Using <classname>DateTimeImmutable</classname> over this class is
23-
recommended.
24-
</para>
21+
<warning>
22+
<para>
23+
Calling methods on objects of the class <classname>DateTime</classname>
24+
will change the information encapsulated in these objects, if you want to
25+
prevent that you will have to use <literal>clone</literal> operator to
26+
create a new object. Use the <classname>DateTimeInterface</classname>
27+
instead of <classname>DateTime</classname> to obtain this recommended
28+
behaviour by default.
29+
</para>
30+
</warning>
2531
</section>
2632
<!-- }}} -->
2733

@@ -83,6 +89,22 @@
8389
on <classname>DateTimeInterface</classname>.
8490
</entry>
8591
</row>
92+
<row>
93+
<entry>7.1.0</entry>
94+
<entry>
95+
The <classname>DateTime</classname> constructor now includes the
96+
current microseconds in the constructed value. Before this, it would
97+
always initialise the microseconds to <literal>0</literal>.
98+
</entry>
99+
</row>
100+
<row>
101+
<entry>5.2.2</entry>
102+
<entry>
103+
Support for microseconds was added in both date/time parser, and
104+
<methodname>DateTime::format</methodname> through the
105+
<literal>'u'</literal> modifier.
106+
</entry>
107+
</row>
86108
</tbody>
87109
</tgroup>
88110
</informaltable>

‎reference/datetime/datetime/settime.xml

+27
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,33 @@
8686
</para>
8787
</refsect1>
8888

89+
<refsect1 role="changelog">
90+
&reftitle.changelog;
91+
<informaltable>
92+
<tgroup cols="2">
93+
<thead>
94+
<row>
95+
<entry>&Version;</entry>
96+
<entry>&Description;</entry>
97+
</row>
98+
</thead>
99+
<tbody>
100+
<row>
101+
<entry>8.1.0</entry>
102+
<entry>The behaviour with double existing hours (during the fall-back
103+
DST transition) changed. Previously PHP would pick the second occurrence
104+
(after the DST transition), instead of the first occurrence (before DST
105+
transition).
106+
</row>
107+
<row>
108+
<entry>7.1.0</entry>
109+
<entry>The <parameter>microsecond</parameter> parameter was added.</entry>
110+
</row>
111+
</tbody>
112+
</tgroup>
113+
</informaltable>
114+
</refsect1>
115+
89116
<refsect1 role="seealso">
90117
&reftitle.seealso;
91118
<simplelist>

‎reference/datetime/datetime/settimezone.xml

+2-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@
5353
<refsect1 role="returnvalues">
5454
&reftitle.returnvalues;
5555
<para>
56-
Returns the <classname>DateTime</classname> object for method chaining.
56+
Returns the <classname>DateTime</classname> object for method chaining. The
57+
underlaying point-in-time is not changed when calling this method.
5758
</para>
5859
</refsect1>
5960

‎reference/datetime/datetime/sub.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@
2525
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
2626
</methodsynopsis>
2727
<para>
28-
Subtracts the specified <classname>DateInterval</classname> object from the specified DateTime
29-
object.
28+
Modifies the specified DateTime object, by subtracting the specified
29+
<classname>DateInterval</classname> object.
3030
</para>
3131
<para>
3232
Like <methodname>DateTimeImmutable::sub</methodname> but works with

‎reference/datetime/datetimeimmutable.xml

+25
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,31 @@
6060

6161
</section>
6262

63+
<section role="changelog" xml:id="datetimeimmutable.changelog"><!-- {{{ -->
64+
&reftitle.changelog;
65+
<para>
66+
<informaltable>
67+
<tgroup cols="2">
68+
<thead>
69+
<row>
70+
<entry>&Version;</entry>
71+
<entry>&Description;</entry>
72+
</row>
73+
</thead>
74+
<tbody>
75+
<row>
76+
<entry>7.1.0</entry>
77+
<entry>
78+
The <classname>DateTimeImmutable</classname> constructor now includes the
79+
current microseconds in the constructed value. Before this, it would
80+
always initialise the microseconds to <literal>0</literal>.
81+
</entry>
82+
</row>
83+
</tbody>
84+
</tgroup>
85+
</informaltable>
86+
</para>
87+
</section><!-- }}} -->
6388
</partintro>
6489

6590
&reference.datetime.entities.datetimeimmutable;

‎reference/datetime/datetimeimmutable/add.xml

+3-4
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,15 @@
1515
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
1616
</methodsynopsis>
1717
<para>
18-
Adds the specified <classname>DateInterval</classname> object to the
19-
specified <classname>DateTime</classname> object, and returns a new
20-
<classname>DateTimeImmutable</classname> object to represent this new state.
18+
Creates a new <classname>DateTimeImmutable</classname> object, and adds the
19+
specified <classname>DateInterval</classname> object to this, to represent
20+
the new value.
2121
</para>
2222
</refsect1>
2323

2424
<refsect1 role="parameters">
2525
&reftitle.parameters;
2626
<variablelist>
27-
&date.datetime.description.modified;
2827
<varlistentry>
2928
<term>
3029
<parameter>interval</parameter>

‎reference/datetime/datetimeimmutable/construct.xml

+44-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@
5757
<parameter>$datetime</parameter> parameter either
5858
is a UNIX timestamp (e.g. <literal>@946684800</literal>)
5959
or specifies a timezone
60-
(e.g. <literal>2010-01-28T15:00:00+02:00</literal>).
60+
(e.g. <literal>2010-01-28T15:00:00+02:00</literal>, or
61+
<literal>2010-07-05T06:00:00Z</literal>).
6162
</para>
6263
</note>
6364
</listitem>
@@ -185,6 +186,48 @@ echo $date->format('Y-m-d H:i:sP') . "\n";
185186
2010-04-25 02:24:16+12:00
186187
2000-01-01 00:00:00+00:00
187188
2000-03-01 00:00:00-05:00
189+
]]>
190+
</screen>
191+
</example>
192+
193+
<example>
194+
<title>Changing the associated timezone</title>
195+
<programlisting role="php">
196+
<![CDATA[
197+
<?php
198+
$timeZone = new \DateTimeZone('Asia/Tokyo');
199+
200+
$time = new \DateTimeImmutable();
201+
$time = $time->setTimezone($timeZone);
202+
203+
echo $time->format('Y/m/d H:i:s'), "\n";
204+
?>
205+
]]>
206+
</programlisting>
207+
&example.outputs.similar;
208+
<screen>
209+
<![CDATA[
210+
2022/08/12 23:49:23
211+
]]>
212+
</screen>
213+
</example>
214+
</refsect1>
215+
216+
<example>
217+
<title>Using a relative date/time string</title>
218+
<programlisting role="php">
219+
<![CDATA[
220+
<?php
221+
$time = new \DateTimeImmutable("-1 year");
222+
223+
echo $time->format('Y/m/d H:i:s'), "\n";
224+
?>
225+
]]>
226+
</programlisting>
227+
&example.outputs.similar;
228+
<screen>
229+
<![CDATA[
230+
2021/08/12 15:43:51
188231
]]>
189232
</screen>
190233
</example>

‎reference/datetime/datetimeimmutable/createfromformat.xml

+9
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,15 @@
4141
formatting options below. In most cases, the same letters as for the
4242
<function>date</function> can be used.
4343
</para>
44+
<para>
45+
ALl fields are initialised with the current date/time. In most cases you
46+
would want to reset these to "zero" (the Unix epoch, <literal>1970-01-01
47+
00:00:00 UTC</literal>). You do that by including the
48+
<literal>!</literal> character as first character in your
49+
<parameter>format</parameter>, or <literal>|</literal> as your last.
50+
Please see the documentation for each character below for more
51+
information.
52+
</para>
4453
<para>
4554
The format is parsed from left to right, which means that in some
4655
situations the order in which the format characters are present effects

‎reference/datetime/datetimeimmutable/getlasterrors.xml

-1
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@
3535
&reftitle.examples;
3636
<example>
3737
<title><function>DateTimeImmutable::getLastErrors</function> example</title>
38-
<para>&style.oop;</para>
3938
<programlisting role="php">
4039
<![CDATA[
4140
<?php

‎reference/datetime/datetimeimmutable/modify.xml

-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,6 @@
2121
<refsect1 role="parameters">
2222
&reftitle.parameters;
2323
<variablelist>
24-
&date.datetime.description.modified;
2524
<varlistentry>
2625
<term><parameter>modifier</parameter></term>
2726
<listitem>

‎reference/datetime/datetimeimmutable/setisodate.xml

-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
<refsect1 role="parameters">
2424
&reftitle.parameters;
2525
<variablelist>
26-
&date.datetime.description.modified;
2726
<varlistentry>
2827
<term><parameter>year</parameter></term>
2928
<listitem>

‎reference/datetime/datetimeimmutable/settime.xml

+7-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
<refsect1 role="parameters">
2424
&reftitle.parameters;
2525
<variablelist>
26-
&date.datetime.description.modified;
2726
<varlistentry>
2827
<term><parameter>hour</parameter></term>
2928
<listitem>
@@ -77,6 +76,13 @@
7776
</row>
7877
</thead>
7978
<tbody>
79+
<row>
80+
<entry>8.1.0</entry>
81+
<entry>The behaviour with double existing hours (during the fall-back
82+
DST transition) changed. Previously PHP would pick the second occurrence
83+
(after the DST transition), instead of the first occurrence (before DST
84+
transition).
85+
</row>
8086
<row>
8187
<entry>7.1.0</entry>
8288
<entry>The <parameter>microsecond</parameter> parameter was added.</entry>

‎reference/datetime/datetimeimmutable/settimestamp.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,14 @@
1313
<methodparam><type>int</type><parameter>timestamp</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
16-
Returns a new DateTimeImmutable object with the date and time set based on an Unix timestamp.
16+
Returns a new <type>DateTimeImmutable</type> object constructed from the
17+
old one, with the date and time set based on an Unix timestamp.
1718
</para>
1819
</refsect1>
1920

2021
<refsect1 role="parameters">
2122
&reftitle.parameters;
2223
<variablelist>
23-
&date.datetime.description.modified;
2424
<varlistentry>
2525
<term><parameter>timestamp</parameter></term>
2626
<listitem>

‎reference/datetime/datetimeimmutable/settimezone.xml

+3-2
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
<refsect1 role="parameters">
2121
&reftitle.parameters;
2222
<variablelist>
23-
&date.datetime.description.modified;
2423
<varlistentry>
2524
<term><parameter>timezone</parameter></term>
2625
<listitem>
@@ -36,7 +35,9 @@
3635
<refsect1 role="returnvalues">
3736
&reftitle.returnvalues;
3837
<para>
39-
Returns a new modified <classname>DateTimeImmutable</classname> object for method chaining.
38+
Returns a new modified <classname>DateTimeImmutable</classname> object for
39+
method chaining. The underlaying point-in-time is not changed when calling
40+
this method.
4041
</para>
4142
</refsect1>
4243

‎reference/datetime/datetimeimmutable/sub.xml

+1-2
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
<methodparam><type>DateInterval</type><parameter>interval</parameter></methodparam>
1616
</methodsynopsis>
1717
<para>
18-
Returns a new DateTimeImmutable object, with the specified
18+
Returns a new <classname>DateTimeImmutable</classname> object, with the specified
1919
<classname>DateInterval</classname> object subtracted from the specified
2020
DateTimeImmutable object.
2121
</para>
@@ -24,7 +24,6 @@
2424
<refsect1 role="parameters">
2525
&reftitle.parameters;
2626
<variablelist>
27-
&date.datetime.description.modified;
2827
<varlistentry>
2928
<term>
3029
<parameter>interval</parameter>

0 commit comments

Comments
 (0)