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

4
3
<refentry xml:id="datetimezone.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>DateTimeZone::__construct</refname>
...
...
@@ -11,17 +10,29 @@
11
10
<refsect1 role="description">
12
11
&reftitle.description;
13
12
<para>&style.oop;</para>
14
-
<constructorsynopsis role="oop">
13
+
<constructorsynopsis role="DateTimeZone">
15
14
<modifier>public</modifier> <methodname>DateTimeZone::__construct</methodname>
16
15
<methodparam><type>string</type><parameter>timezone</parameter></methodparam>
17
16
</constructorsynopsis>
18
17
<para>&style.procedural;</para>
19
-
<methodsynopsis role="procedural">
20
-
<type>DateTimeZone</type><methodname>timezone_open</methodname>
18
+
<methodsynopsis>
19
+
<type class="union"><type>DateTimeZone</type><type>false</type></type><methodname>timezone_open</methodname>
21
20
<methodparam><type>string</type><parameter>timezone</parameter></methodparam>
22
21
</methodsynopsis>
23
22
<para>
24
-
Creates new DateTimeZone object.
23
+
Creates a new DateTimeZone object.
24
+
</para>
25
+
<para>
26
+
A DateTimeZone object provides access to three different types of timezone
27
+
rules: UTC offset (type <literal>1</literal>), timezone abbreviation (type
28
+
<literal>2</literal>), and <link linkend="timezones">timezone
29
+
identifiers</link> as published in the IANA timezone database
30
+
(type <literal>3</literal>).
31
+
</para>
32
+
<para>
33
+
The DateTimeZone object can be attached to <classname>DateTime</classname> and
34
+
<classname>DateTimeImmutable</classname> objects to be able to render the
35
+
timezone encapsulated by these objects in a local timezone.
25
36
</para>
26
37
</refsect1>
27
38

...
...
@@ -33,8 +44,8 @@
33
44
<term><parameter>timezone</parameter></term>
34
45
<listitem>
35
46
<para>
36
-
One of the supported <link linkend="timezones">timezone names</link>
37
-
or an offset value (+0200).
47
+
One of the supported <link linkend="timezones">timezone names</link>,
48
+
an offset value (+0200), or a timezone abbreviation (BST).
38
49
</para>
39
50
</listitem>
40
51
</varlistentry>
...
...
@@ -53,8 +64,10 @@
53
64
<refsect1 role="errors">
54
65
&reftitle.errors;
55
66
<para>
56
-
This method throws <classname>Exception</classname> if the timezone supplied is not
57
-
recognised as a valid timezone.
67
+
This method throws
68
+
<exceptionname>DateInvalidTimeZoneException</exceptionname> if the timezone supplied is not
69
+
recognised as a valid timezone. Prior to PHP 8.3, this was an
70
+
<exceptionname>Exception</exceptionname> instead.
58
71
</para>
59
72
</refsect1>
60
73

...
...
@@ -71,9 +84,11 @@
71
84
</thead>
72
85
<tbody>
73
86
<row>
74
-
<entry>5.5.10</entry>
87
+
<entry>8.3.0</entry>
75
88
<entry>
76
-
The <parameter>timezone</parameter> parameter accepts offset values.
89
+
Invalid values now return a
90
+
<exceptionname>DateInvalidTimeZoneException</exceptionname> instead of
91
+
a generic <exceptionname>Exception</exceptionname>.
77
92
</entry>
78
93
</row>
79
94
</tbody>
...
...
@@ -86,6 +101,35 @@
86
101
&reftitle.examples;
87
102
<para>
88
103
<example>
104
+
<title>Creating and attaching DateTimeZone to a DateTimeImmutable</title>
105
+
<programlisting role="php">
106
+
<![CDATA[
107
+
<?php
108
+
$d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");
109
+

110
+
$timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];
111
+

112
+
foreach ($timezones as $tz) {
113
+
$tzo = new DateTimeZone($tz);
114
+

115
+
$local = $d->setTimezone($tzo);
116
+
echo $local->format(DateTimeInterface::RFC2822 . ' — e'), "\n";
117
+
}
118
+
?>
119
+
]]>
120
+
</programlisting>
121
+
&example.outputs;
122
+
<screen>
123
+
Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
124
+
Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
125
+
Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
126
+
Thu, 02 Jun 2022 17:44:48 +0200 — CEST
127
+
</screen>
128
+
</example>
129
+
</para>
130
+

131
+
<para>
132
+
<example>
89
133
<title>Catching errors when instantiating <classname>DateTimeZone</classname></title>
90
134
<programlisting role="php">
91
135
<![CDATA[
...
...
@@ -115,7 +159,6 @@ DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone
115
159
</refsect1>
116
160

117
161
</refentry>
118
-

119
162
<!-- Keep this comment at the end of the file
120
163
Local variables:
121
164
mode: sgml
122
165