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

4
3
<refentry xml:id="datetime.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>DateTime::__construct</refname>
7
-
<refname>date_create</refname>
8
6
<refpurpose>Returns new DateTime object</refpurpose>
9
7
</refnamediv>
10
8

11
9
<refsect1 role="description">
12
10
&reftitle.description;
13
-
<para>&style.oop;</para>
14
-
<constructorsynopsis role="oop">
11
+
<constructorsynopsis role="DateTime">
15
12
<modifier>public</modifier> <methodname>DateTime::__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>
13
+
<methodparam choice="opt"><type>string</type><parameter>datetime</parameter><initializer>"now"</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
18
15
</constructorsynopsis>
19
-
<para>&style.procedural;</para>
20
-
<methodsynopsis role="procedural">
21
-
<type>DateTime</type><methodname>date_create</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>
24
-
</methodsynopsis>
25
16
<para>
26
-
Returns new DateTime object.
17
+
Like <methodname>DateTimeImmutable::__construct</methodname> but works with
18
+
<classname>DateTime</classname>. Consider using the
19
+
<classname>DateTimeImmutable</classname> and features instead.
20
+
</para>
21
+
<para>
22
+
Returns a new DateTime object.
27
23
</para>
28
24
</refsect1>
29
25
...
...
@@ -31,11 +27,11 @@
31
27
&reftitle.parameters;
32
28
<variablelist>
33
29
<varlistentry>
34
-
<term><parameter>time</parameter></term>
30
+
<term><parameter>datetime</parameter></term>
35
31
<listitem>
36
32
<para>&date.formats.parameter;</para>
37
33
<para>
38
-
Enter &null; here to obtain the current time when using
34
+
Enter <literal>"now"</literal> here to obtain the current time when using
39
35
the <parameter>$timezone</parameter> parameter.
40
36
</para>
41
37
</listitem>
...
...
@@ -45,17 +41,17 @@
45
41
<listitem>
46
42
<para>
47
43
A <classname>DateTimeZone</classname> object representing the
48
-
timezone of <parameter>$time</parameter>.
44
+
timezone of <parameter>$datetime</parameter>.
49
45
</para>
50
46
<para>
51
-
If <parameter>$timezone</parameter> is omitted,
47
+
If <parameter>$timezone</parameter> is omitted or &null;,
52
48
the current timezone will be used.
53
49
</para>
54
50
<note>
55
51
<para>
56
52
The <parameter>$timezone</parameter> parameter
57
53
and the current timezone are ignored when the
58
-
<parameter>$time</parameter> parameter either
54
+
<parameter>$datetime</parameter> parameter either
59
55
is a UNIX timestamp (e.g. <literal>@946684800</literal>)
60
56
or specifies a timezone
61
57
(e.g. <literal>2010-01-28T15:00:00+02:00</literal>).
...
...
@@ -70,14 +66,15 @@
70
66
&reftitle.returnvalues;
71
67
<para>
72
68
Returns a new DateTime instance.
73
-
&return.falseforfailure.style.procedural;
74
69
</para>
75
70
</refsect1>
76
71

77
72
<refsect1 role="errors">
78
73
&reftitle.errors;
79
74
<para>
80
-
Emits <classname>Exception</classname> in case of an error.
75
+
If an invalid Date/Time string is passed,
76
+
<exceptionname>DateMalformedStringException</exceptionname> is thrown.
77
+
Previous to PHP 8.3, this was <exceptionname>Exception</exceptionname>.
81
78
</para>
82
79
</refsect1>
83
80

...
...
@@ -94,11 +91,12 @@
94
91
</thead>
95
92
<tbody>
96
93
<row>
97
-
<entry>5.3.0</entry>
94
+
<entry>8.3.0</entry>
98
95
<entry>
99
-
If <parameter>time</parameter> contains an invalid
100
-
<link linkend="datetime.formats">date/time format</link>, then an
101
-
exception is now thrown. Previously an error was emitted.
96
+
Now throws
97
+
<exceptionname>DateMalformedStringException</exceptionname> if an
98
+
invalid string is passed, instead of
99
+
<exceptionname>Exception</exceptionname>.
102
100
</entry>
103
101
</row>
104
102
</tbody>
...
...
@@ -107,109 +105,14 @@
107
105
</para>
108
106
</refsect1>
109
107

110
-
<refsect1 role="examples">
111
-
&reftitle.examples;
112
-
<example>
113
-
<title><function>DateTime::__construct</function> example</title>
114
-
<para>&style.oop;</para>
115
-
<programlisting role="php">
116
-
<![CDATA[
117
-
<?php
118
-
try {
119
-
$date = new DateTime('2000-01-01');
120
-
} catch (Exception $e) {
121
-
echo $e->getMessage();
122
-
exit(1);
123
-
}
124
-

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

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

162
-
// Specified date/time in the specified time zone.
163
-
$date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
164
-
echo $date->format('Y-m-d H:i:sP') . "\n";
165
-

166
-
// Current date/time in your computer's time zone.
167
-
$date = new DateTime();
168
-
echo $date->format('Y-m-d H:i:sP') . "\n";
169
-

170
-
// Current date/time in the specified time zone.
171
-
$date = new DateTime(null, new DateTimeZone('Pacific/Nauru'));
172
-
echo $date->format('Y-m-d H:i:sP') . "\n";
173
-

174
-
// Using a UNIX timestamp. Notice the result is in the UTC time zone.
175
-
$date = new DateTime('@946684800');
176
-
echo $date->format('Y-m-d H:i:sP') . "\n";
177
-

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

198
108
<refsect1 role="seealso">
199
109
&reftitle.seealso;
200
110
<simplelist>
201
-
<member><function>DateTime::createFromFormat</function></member>
202
-
<member><function>DateTimeZone::__construct</function></member>
203
-
<member><link linkend="datetime.formats">Date and Time Formats</link></member>
204
-
<member><link linkend="ini.date.timezone">date.timezone</link> ini setting</member>
205
-
<member><function>date_default_timezone_set</function></member>
206
-
<member><function>DateTime::getLastErrors</function></member>
207
-
<member><function>checkdate</function></member>
111
+
<member><methodname>DateTimeImmutable::__construct</methodname></member>
208
112
</simplelist>
209
113
</refsect1>
210
114

211
115
</refentry>
212
-

213
116
<!-- Keep this comment at the end of the file
214
117
Local variables:
215
118
mode: sgml
216
119