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,7 +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>.
47
+
One of the supported <link linkend="timezones">timezone names</link>,
48
+
an offset value (+0200), or a timezone abbreviation (BST).
37
49
</para>
38
50
</listitem>
39
51
</varlistentry>
...
...
@@ -52,8 +64,36 @@
52
64
<refsect1 role="errors">
53
65
&reftitle.errors;
54
66
<para>
55
-
This method throws <classname>Exception</classname> if the timezone supplied is not
56
-
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.
71
+
</para>
72
+
</refsect1>
73
+

74
+
<refsect1 role="changelog">
75
+
&reftitle.changelog;
76
+
<para>
77
+
<informaltable>
78
+
<tgroup cols="2">
79
+
<thead>
80
+
<row>
81
+
<entry>&Version;</entry>
82
+
<entry>&Description;</entry>
83
+
</row>
84
+
</thead>
85
+
<tbody>
86
+
<row>
87
+
<entry>8.3.0</entry>
88
+
<entry>
89
+
Invalid values now return a
90
+
<exceptionname>DateInvalidTimeZoneException</exceptionname> instead of
91
+
a generic <exceptionname>Exception</exceptionname>.
92
+
</entry>
93
+
</row>
94
+
</tbody>
95
+
</tgroup>
96
+
</informaltable>
57
97
</para>
58
98
</refsect1>
59
99
...
...
@@ -61,6 +101,35 @@
61
101
&reftitle.examples;
62
102
<para>
63
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>
64
133
<title>Catching errors when instantiating <classname>DateTimeZone</classname></title>
65
134
<programlisting role="php">
66
135
<![CDATA[
...
...
@@ -90,7 +159,6 @@ DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone
90
159
</refsect1>
91
160

92
161
</refentry>
93
-

94
162
<!-- Keep this comment at the end of the file
95
163
Local variables:
96
164
mode: sgml
97
165