reference/datetime/datetimeimmutable/construct.xml
8b4c3d8dc5e190fbd5d84eede38a4da13537043d
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="datetimeimmutable.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>DateTimeImmutable::__construct</refname>
...
...
@@ -11,25 +10,240 @@
11
10
<refsect1 role="description">
12
11
&reftitle.description;
13
12
<para>&style.oop;</para>
14
-
<constructorsynopsis role="oop">
13
+
<constructorsynopsis role="DateTimeImmutable">
15
14
<modifier>public</modifier> <methodname>DateTimeImmutable::__construct</methodname>
16
-
<methodparam choice="opt"><type>string</type><parameter>time</parameter><initializer>"now"</initializer></methodparam>
17
-
<methodparam choice="opt"><type>DateTimeZone</type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
15
+
<methodparam choice="opt"><type>string</type><parameter>datetime</parameter><initializer>"now"</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
18
17
</constructorsynopsis>
19
18
<para>&style.procedural;</para>
20
-
<methodsynopsis role="procedural">
21
-
<type>DateTimeImmutable</type><methodname>date_create_immutable</methodname>
22
-
<methodparam choice="opt"><type>string</type><parameter>time</parameter><initializer>"now"</initializer></methodparam>
23
-
<methodparam choice="opt"><type>DateTimeZone</type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
19
+
<methodsynopsis>
20
+
<type class="union"><type>DateTimeImmutable</type><type>false</type></type><methodname>date_create_immutable</methodname>
21
+
<methodparam choice="opt"><type>string</type><parameter>datetime</parameter><initializer>"now"</initializer></methodparam>
22
+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
24
23
</methodsynopsis>
25
24
<para>
26
-
Like <methodname>DateTime::__construct</methodname> but works with
27
-
<classname>DateTimeImmutable</classname>.
25
+
Returns new a DateTimeImmutable object.
28
26
</para>
29
27
</refsect1>
30
28

31
-
</refentry>
29
+
<refsect1 role="parameters">
30
+
&reftitle.parameters;
31
+
<variablelist>
32
+
<varlistentry>
33
+
<term><parameter>datetime</parameter></term>
34
+
<listitem>
35
+
<para>&date.formats.parameter;</para>
36
+
<para>
37
+
Enter <literal>"now"</literal> here to obtain the current time when using
38
+
the <parameter>$timezone</parameter> parameter.
39
+
</para>
40
+
</listitem>
41
+
</varlistentry>
42
+
<varlistentry>
43
+
<term><parameter>timezone</parameter></term>
44
+
<listitem>
45
+
<para>
46
+
A <classname>DateTimeZone</classname> object representing the
47
+
timezone of <parameter>$datetime</parameter>.
48
+
</para>
49
+
<para>
50
+
If <parameter>$timezone</parameter> is omitted or &null;,
51
+
the current timezone will be used.
52
+
</para>
53
+
<note>
54
+
<para>
55
+
The <parameter>$timezone</parameter> parameter
56
+
and the current timezone are ignored when the
57
+
<parameter>$datetime</parameter> parameter either
58
+
is a UNIX timestamp (e.g. <literal>@946684800</literal>)
59
+
or specifies a timezone
60
+
(e.g. <literal>2010-01-28T15:00:00+02:00</literal>, or
61
+
<literal>2010-07-05T06:00:00Z</literal>).
62
+
</para>
63
+
</note>
64
+
</listitem>
65
+
</varlistentry>
66
+
</variablelist>
67
+
</refsect1>
68
+

69
+
<refsect1 role="returnvalues">
70
+
&reftitle.returnvalues;
71
+
<para>
72
+
Returns a new DateTimeImmutable instance.
73
+
</para>
74
+
</refsect1>
75
+

76
+
<refsect1 role="errors">
77
+
&reftitle.errors;
78
+
<para>
79
+
If an invalid Date/Time string is passed,
80
+
<exceptionname>DateMalformedStringException</exceptionname> is thrown.
81
+
Previous to PHP 8.3, this was <exceptionname>Exception</exceptionname>.
82
+
</para>
83
+
</refsect1>
84
+

85
+
<refsect1 role="changelog">
86
+
&reftitle.changelog;
87
+
<para>
88
+
<informaltable>
89
+
<tgroup cols="2">
90
+
<thead>
91
+
<row>
92
+
<entry>&Version;</entry>
93
+
<entry>&Description;</entry>
94
+
</row>
95
+
</thead>
96
+
<tbody>
97
+
<row>
98
+
<entry>8.3.0</entry>
99
+
<entry>
100
+
Now throws
101
+
<exceptionname>DateMalformedStringException</exceptionname> if an
102
+
invalid string is passed, instead of
103
+
<exceptionname>Exception</exceptionname>.
104
+
</entry>
105
+
</row>
106
+
<row>
107
+
<entry>7.1.0</entry>
108
+
<entry>From now on microseconds are filled with actual value. Not with '00000'.</entry>
109
+
</row>
110
+
</tbody>
111
+
</tgroup>
112
+
</informaltable>
113
+
</para>
114
+
</refsect1>
115
+

116
+
<refsect1 role="examples">
117
+
&reftitle.examples;
118
+
<example>
119
+
<title><function>DateTimeImmutable::__construct</function> example</title>
120
+
<para>&style.oop;</para>
121
+
<programlisting role="php">
122
+
<![CDATA[
123
+
<?php
124
+
try {
125
+
$date = new DateTimeImmutable('2000-01-01');
126
+
} catch (Exception $e) {
127
+
echo $e->getMessage();
128
+
exit(1);
129
+
}
32
130

131
+
echo $date->format('Y-m-d');
132
+
?>
133
+
]]>
134
+
</programlisting>
135
+
<para>&style.procedural;</para>
136
+
<programlisting role="php">
137
+
<![CDATA[
138
+
<?php
139
+
$date = date_create('2000-01-01');
140
+
if (!$date) {
141
+
$e = date_get_last_errors();
142
+
foreach ($e['errors'] as $error) {
143
+
echo "$error\n";
144
+
}
145
+
exit(1);
146
+
}
147
+

148
+
echo date_format($date, 'Y-m-d');
149
+
?>
150
+
]]>
151
+
</programlisting>
152
+
&examples.outputs;
153
+
<screen>
154
+
<![CDATA[
155
+
2000-01-01
156
+
]]>
157
+
</screen>
158
+
</example>
159
+
<example>
160
+
<title>Intricacies of <function>DateTimeImmutable::__construct</function></title>
161
+
<programlisting role="php">
162
+
<![CDATA[
163
+
<?php
164
+
// Specified date/time in your computer's time zone.
165
+
$date = new DateTimeImmutable('2000-01-01');
166
+
echo $date->format('Y-m-d H:i:sP') . "\n";
167
+

168
+
// Specified date/time in the specified time zone.
169
+
$date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
170
+
echo $date->format('Y-m-d H:i:sP') . "\n";
171
+

172
+
// Current date/time in your computer's time zone.
173
+
$date = new DateTimeImmutable();
174
+
echo $date->format('Y-m-d H:i:sP') . "\n";
175
+

176
+
// Current date/time in the specified time zone.
177
+
$date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
178
+
echo $date->format('Y-m-d H:i:sP') . "\n";
179
+

180
+
// Using a UNIX timestamp. Notice the result is in the UTC time zone.
181
+
$date = new DateTimeImmutable('@946684800');
182
+
echo $date->format('Y-m-d H:i:sP') . "\n";
183
+

184
+
// Non-existent values roll over.
185
+
$date = new DateTimeImmutable('2000-02-30');
186
+
echo $date->format('Y-m-d H:i:sP') . "\n";
187
+
?>
188
+
]]>
189
+
</programlisting>
190
+
&example.outputs.similar;
191
+
<screen>
192
+
<![CDATA[
193
+
2000-01-01 00:00:00-05:00
194
+
2000-01-01 00:00:00+12:00
195
+
2010-04-24 10:24:16-04:00
196
+
2010-04-25 02:24:16+12:00
197
+
2000-01-01 00:00:00+00:00
198
+
2000-03-01 00:00:00-05:00
199
+
]]>
200
+
</screen>
201
+
</example>
202
+

203
+
<example>
204
+
<title>Changing the associated timezone</title>
205
+
<programlisting role="php">
206
+
<![CDATA[
207
+
<?php
208
+
$timeZone = new \DateTimeZone('Asia/Tokyo');
209
+

210
+
$time = new \DateTimeImmutable();
211
+
$time = $time->setTimezone($timeZone);
212
+

213
+
echo $time->format('Y/m/d H:i:s'), "\n";
214
+
?>
215
+
]]>
216
+
</programlisting>
217
+
&example.outputs.similar;
218
+
<screen>
219
+
<![CDATA[
220
+
2022/08/12 23:49:23
221
+
]]>
222
+
</screen>
223
+
</example>
224
+

225
+
<example>
226
+
<title>Using a relative date/time string</title>
227
+
<programlisting role="php">
228
+
<![CDATA[
229
+
<?php
230
+
$time = new \DateTimeImmutable("-1 year");
231
+

232
+
echo $time->format('Y/m/d H:i:s'), "\n";
233
+
?>
234
+
]]>
235
+
</programlisting>
236
+
&example.outputs.similar;
237
+
<screen>
238
+
<![CDATA[
239
+
2021/08/12 15:43:51
240
+
]]>
241
+
</screen>
242
+
</example>
243
+
</refsect1>
244
+

245
+

246
+
</refentry>
33
247
<!-- Keep this comment at the end of the file
34
248
Local variables:
35
249
mode: sgml
36
250