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

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

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

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
208
<refsect1 role="examples">
152
209
&reftitle.examples;
153
210
<para>
...
...
@@ -173,6 +230,23 @@ echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRIN
173
230
<screen>
174
231
<![CDATA[
175
232
Mon Dec 20 2004, sunset time : 18:13
233
+
]]>
234
+
</screen>
235
+
</example>
236
+
<example>
237
+
<title>No sunset</title>
238
+
<programlisting role="php">
239
+
<![CDATA[
240
+
<?php
241
+
$solstice = strtotime('2017-12-21');
242
+
var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
243
+
?>
244
+
]]>
245
+
</programlisting>
246
+
&example.outputs;
247
+
<screen>
248
+
<![CDATA[
249
+
bool(false)
176
250
]]>
177
251
</screen>
178
252
</example>
...
...
@@ -183,13 +257,11 @@ Mon Dec 20 2004, sunset time : 18:13
183
257
&reftitle.seealso;
184
258
<para>
185
259
<simplelist>
186
-
<member><function>date_sunrise</function></member>
260
+
<member><function>date_sun_info</function></member>
187
261
</simplelist>
188
262
</para>
189
263
</refsect1>
190
264
</refentry>
191
-

192
-

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



Translation status