reference/datetime/functions/date-sunset.xml
5c951013ca04161992efed8b86fb40f55669958e
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.date-sunset" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.date-sunset" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>date_sunset</refname>
6
6
<refpurpose>
...
...
@@ -8,17 +8,27 @@
8
8
</refpurpose>
9
9
</refnamediv>
10
10

11
+
<refsynopsisdiv>
12
+
<warning>
13
+
<para>
14
+
This function has been <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
15
+
Relying on this function is highly discouraged. Use
16
+
<function>date_sun_info</function> instead.
17
+
</para>
18
+
</warning>
19
+
</refsynopsisdiv>
20
+

11
21
<refsect1 role="description">
12
22
&reftitle.description;
13
23
<methodsynopsis>
14
-
<type>mixed</type><methodname>date_sunset</methodname>
24
+
<type class="union"><type>string</type><type>int</type><type>float</type><type>false</type></type><methodname>date_sunset</methodname>
15
25
<methodparam><type>int</type><parameter>timestamp</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>format</parameter><initializer>SUNFUNCS_RET_STRING</initializer></methodparam>
17
-
<methodparam choice="opt"><type>float</type><parameter>latitude</parameter><initializer>ini_get("date.default_latitude")</initializer></methodparam>
18
-
<methodparam choice="opt"><type>float</type><parameter>longitude</parameter><initializer>ini_get("date.default_longitude")</initializer></methodparam>
19
-
<methodparam choice="opt"><type>float</type><parameter>zenith</parameter><initializer>ini_get("date.sunset_zenith")</initializer></methodparam>
20
-
<methodparam choice="opt"><type>float</type><parameter>gmt_offset</parameter><initializer>0</initializer></methodparam>
21
-
</methodsynopsis>
26
+
<methodparam choice="opt"><type>int</type><parameter>returnFormat</parameter><initializer><constant>SUNFUNCS_RET_STRING</constant></initializer></methodparam>
27
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>latitude</parameter><initializer>&null;</initializer></methodparam>
28
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>longitude</parameter><initializer>&null;</initializer></methodparam>
29
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>zenith</parameter><initializer>&null;</initializer></methodparam>
30
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>utcOffset</parameter><initializer>&null;</initializer></methodparam>
31
+
</methodsynopsis>
22
32
<para>
23
33
<function>date_sunset</function> returns the sunset time for a given
24
34
day (specified as a <parameter>timestamp</parameter>) and location.
...
...
@@ -39,11 +49,11 @@
39
49
</listitem>
40
50
</varlistentry>
41
51
<varlistentry>
42
-
<term><parameter>format</parameter></term>
52
+
<term><parameter>returnFormat</parameter></term>
43
53
<listitem>
44
54
<para>
45
55
<table>
46
-
<title><parameter>format</parameter> constants</title>
56
+
<title><parameter>returnFormat</parameter> constants</title>
47
57
<tgroup cols="2">
48
58
<thead>
49
59
<row>
...
...
@@ -65,7 +75,7 @@
65
75
</row>
66
76
<row>
67
77
<entry>SUNFUNCS_RET_TIMESTAMP</entry>
68
-
<entry>returns the result as <type>integer</type> (timestamp)</entry>
78
+
<entry>returns the result as <type>int</type> (timestamp)</entry>
69
79
<entry>1095034606</entry>
70
80
</row>
71
81
</tbody>
...
...
@@ -79,7 +89,7 @@
79
89
<listitem>
80
90
<para>
81
91
Defaults to North, pass in a negative value for South.
82
-
See also: <literal>date.default_latitude</literal>
92
+
See also: <link linkend="ini.date.default-latitude">date.default_latitude</link>
83
93
</para>
84
94
</listitem>
85
95
</varlistentry>
...
...
@@ -88,7 +98,7 @@
88
98
<listitem>
89
99
<para>
90
100
Defaults to East, pass in a negative value for West.
91
-
See also: <literal>date.default_longitude</literal>
101
+
See also: <link linkend="ini.date.default-longitude">date.default_longitude</link>
92
102
</para>
93
103
</listitem>
94
104
</varlistentry>
...
...
@@ -96,15 +106,49 @@
96
106
<term><parameter>zenith</parameter></term>
97
107
<listitem>
98
108
<para>
99
-
Default: <literal>date.sunset_zenith</literal>
109
+
<parameter>zenith</parameter> is the angle between the center of the sun
110
+
and a line perpendicular to earth's surface. It defaults to
111
+
<link linkend="ini.date.sunset-zenith">date.sunset_zenith</link>
112
+
<table>
113
+
<title>Common <parameter>zenith</parameter> angles</title>
114
+
<tgroup cols="2">
115
+
<thead>
116
+
<row>
117
+
<entry>Angle</entry>
118
+
<entry>Description</entry>
119
+
</row>
120
+
</thead>
121
+
<tbody>
122
+
<row>
123
+
<entry>90°50'</entry>
124
+
<entry>Sunset: the point where the sun becomes invisible.</entry>
125
+
</row>
126
+
<row>
127
+
<entry>96°</entry>
128
+
<entry>Civil twilight: conventionally used to signify the end of dusk.</entry>
129
+
</row>
130
+
<row>
131
+
<entry>102°</entry>
132
+
<entry>Nautical twilight: the point at which the horizon ends being visible at sea.</entry>
133
+
</row>
134
+
<row>
135
+
<entry>108°</entry>
136
+
<entry>Astronomical twilight: the point at which the sun ends being the source of any illumination.</entry>
137
+
</row>
138
+
</tbody>
139
+
</tgroup>
140
+
</table>
100
141
</para>
101
142
</listitem>
102
143
</varlistentry>
103
144
<varlistentry>
104
-
<term><parameter>gmtoffset</parameter></term>
145
+
<term><parameter>utcOffset</parameter></term>
105
146
<listitem>
106
147
<para>
107
148
Specified in hours.
149
+
The <parameter>utcOffset</parameter> is ignored, if
150
+
<parameter>returnFormat</parameter> is
151
+
<constant>SUNFUNCS_RET_TIMESTAMP</constant>.
108
152
</para>
109
153
</listitem>
110
154
</varlistentry>
...
...
@@ -112,6 +156,16 @@
112
156
</para>
113
157
</refsect1>
114
158

159
+
<refsect1 role="returnvalues">
160
+
&reftitle.returnvalues;
161
+
<para>
162
+
Returns the sunset time in a specified <parameter>returnFormat</parameter> on
163
+
success&return.falseforfailure;. One potential reason for failure is that the
164
+
sun does not set at all, which happens inside the polar circles for part of
165
+
the year.
166
+
</para>
167
+
</refsect1>
168
+

115
169
<refsect1 role="errors">
116
170
&reftitle.errors;
117
171
...
...
@@ -131,23 +185,25 @@
131
185
</row>
132
186
</thead>
133
187
<tbody>
134
-
135
-
&date.timezone.errors.changelog;
136
-
188
+
<row>
189
+
<entry>8.1.0</entry>
190
+
<entry>
191
+
This function has been deprecated in favor of <function>date_sun_info</function>.
192
+
</entry>
193
+
</row>
194
+
<row>
195
+
<entry>8.0.0</entry>
196
+
<entry>
197
+
<parameter>latitude</parameter>, <parameter>longitude</parameter>,
198
+
<parameter>zenith</parameter> and <parameter>utcOffset</parameter> are nullable now.
199
+
</entry>
200
+
</row>
137
201
</tbody>
138
202
</tgroup>
139
203
</informaltable>
140
204
</para>
141
205
</refsect1>
142
206

143
-
<refsect1 role="returnvalues">
144
-
&reftitle.returnvalues;
145
-
<para>
146
-
Returns the sunset time in a specified <parameter>format</parameter> on
147
-
success&return.falseforfailure;.
148
-
</para>
149
-
</refsect1>
150
-
151
207
<refsect1 role="examples">
152
208
&reftitle.examples;
153
209
<para>
...
...
@@ -176,6 +232,23 @@ Mon Dec 20 2004, sunset time : 18:13
176
232
]]>
177
233
</screen>
178
234
</example>
235
+
<example>
236
+
<title>No sunset</title>
237
+
<programlisting role="php">
238
+
<![CDATA[
239
+
<?php
240
+
$solstice = strtotime('2017-12-21');
241
+
var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
242
+
?>
243
+
]]>
244
+
</programlisting>
245
+
&example.outputs;
246
+
<screen>
247
+
<![CDATA[
248
+
bool(false)
249
+
]]>
250
+
</screen>
251
+
</example>
179
252
</para>
180
253
</refsect1>
181
254

...
...
@@ -183,13 +256,11 @@ Mon Dec 20 2004, sunset time : 18:13
183
256
&reftitle.seealso;
184
257
<para>
185
258
<simplelist>
186
-
<member><function>date_sunrise</function></member>
259
+
<member><function>date_sun_info</function></member>
187
260
</simplelist>
188
261
</para>
189
262
</refsect1>
190
263
</refentry>
191
-

192
-

193
264
<!-- Keep this comment at the end of the file
194
265
Local variables:
195
266
mode: sgml
196
267