reference/datetime/functions/date-sunrise.xml
5c951013ca04161992efed8b86fb40f55669958e
...
...
@@ -1,21 +1,31 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.date-sunrise" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.date-sunrise" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>date_sunrise</refname>
6
6
<refpurpose>Returns time of sunrise for a given day and location</refpurpose>
7
7
</refnamediv>
8
8

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

9
19
<refsect1 role="description">
10
20
&reftitle.description;
11
21
<methodsynopsis>
12
-
<type>mixed</type><methodname>date_sunrise</methodname>
22
+
<type class="union"><type>string</type><type>int</type><type>float</type><type>false</type></type><methodname>date_sunrise</methodname>
13
23
<methodparam><type>int</type><parameter>timestamp</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>format</parameter><initializer>SUNFUNCS_RET_STRING</initializer></methodparam>
15
-
<methodparam choice="opt"><type>float</type><parameter>latitude</parameter><initializer>ini_get("date.default_latitude")</initializer></methodparam>
16
-
<methodparam choice="opt"><type>float</type><parameter>longitude</parameter><initializer>ini_get("date.default_longitude")</initializer></methodparam>
17
-
<methodparam choice="opt"><type>float</type><parameter>zenith</parameter><initializer>ini_get("date.sunrise_zenith")</initializer></methodparam>
18
-
<methodparam choice="opt"><type>float</type><parameter>gmt_offset</parameter><initializer>0</initializer></methodparam>
24
+
<methodparam choice="opt"><type>int</type><parameter>returnFormat</parameter><initializer><constant>SUNFUNCS_RET_STRING</constant></initializer></methodparam>
25
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>latitude</parameter><initializer>&null;</initializer></methodparam>
26
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>longitude</parameter><initializer>&null;</initializer></methodparam>
27
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>zenith</parameter><initializer>&null;</initializer></methodparam>
28
+
<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>utcOffset</parameter><initializer>&null;</initializer></methodparam>
19
29
</methodsynopsis>
20
30
<para>
21
31
<function>date_sunrise</function> returns the sunrise time for a given
...
...
@@ -37,11 +47,11 @@
37
47
</listitem>
38
48
</varlistentry>
39
49
<varlistentry>
40
-
<term><parameter>format</parameter></term>
50
+
<term><parameter>returnFormat</parameter></term>
41
51
<listitem>
42
52
<para>
43
53
<table>
44
-
<title><parameter>format</parameter> constants</title>
54
+
<title><parameter>returnFormat</parameter> constants</title>
45
55
<tgroup cols="2">
46
56
<thead>
47
57
<row>
...
...
@@ -63,7 +73,7 @@
63
73
</row>
64
74
<row>
65
75
<entry>SUNFUNCS_RET_TIMESTAMP</entry>
66
-
<entry>returns the result as <type>integer</type> (timestamp)</entry>
76
+
<entry>returns the result as <type>int</type> (timestamp)</entry>
67
77
<entry>1095034606</entry>
68
78
</row>
69
79
</tbody>
...
...
@@ -77,7 +87,7 @@
77
87
<listitem>
78
88
<para>
79
89
Defaults to North, pass in a negative value for South.
80
-
See also: <literal>date.default_latitude</literal>
90
+
See also: <link linkend="ini.date.default-latitude">date.default_latitude</link>
81
91
</para>
82
92
</listitem>
83
93
</varlistentry>
...
...
@@ -86,7 +96,7 @@
86
96
<listitem>
87
97
<para>
88
98
Defaults to East, pass in a negative value for West.
89
-
See also: <literal>date.default_longitude</literal>
99
+
See also: <link linkend="ini.date.default-longitude">date.default_longitude</link>
90
100
</para>
91
101
</listitem>
92
102
</varlistentry>
...
...
@@ -94,15 +104,49 @@
94
104
<term><parameter>zenith</parameter></term>
95
105
<listitem>
96
106
<para>
97
-
Default: <literal>date.sunrise_zenith</literal>
107
+
<parameter>zenith</parameter> is the angle between the center of the sun
108
+
and a line perpendicular to earth's surface. It defaults to
109
+
<link linkend="ini.date.sunrise-zenith">date.sunrise_zenith</link>
110
+
<table>
111
+
<title>Common <parameter>zenith</parameter> angles</title>
112
+
<tgroup cols="2">
113
+
<thead>
114
+
<row>
115
+
<entry>Angle</entry>
116
+
<entry>Description</entry>
117
+
</row>
118
+
</thead>
119
+
<tbody>
120
+
<row>
121
+
<entry>90°50'</entry>
122
+
<entry>Sunrise: the point where the sun becomes visible.</entry>
123
+
</row>
124
+
<row>
125
+
<entry>96°</entry>
126
+
<entry>Civil twilight: conventionally used to signify the start of dawn.</entry>
127
+
</row>
128
+
<row>
129
+
<entry>102°</entry>
130
+
<entry>Nautical twilight: the point at which the horizon starts being visible at sea.</entry>
131
+
</row>
132
+
<row>
133
+
<entry>108°</entry>
134
+
<entry>Astronomical twilight: the point at which the sun starts being the source of any illumination.</entry>
135
+
</row>
136
+
</tbody>
137
+
</tgroup>
138
+
</table>
98
139
</para>
99
140
</listitem>
100
141
</varlistentry>
101
142
<varlistentry>
102
-
<term><parameter>gmtoffset</parameter></term>
143
+
<term><parameter>utcOffset</parameter></term>
103
144
<listitem>
104
145
<para>
105
146
Specified in hours.
147
+
The <parameter>utcOffset</parameter> is ignored, if
148
+
<parameter>returnFormat</parameter> is
149
+
<constant>SUNFUNCS_RET_TIMESTAMP</constant>.
106
150
</para>
107
151
</listitem>
108
152
</varlistentry>
...
...
@@ -113,8 +157,10 @@
113
157
<refsect1 role="returnvalues">
114
158
&reftitle.returnvalues;
115
159
<para>
116
-
Returns the sunrise time in a specified <parameter>format</parameter> on
117
-
success&return.falseforfailure;.
160
+
Returns the sunrise time in a specified <parameter>returnFormat</parameter> on
161
+
success&return.falseforfailure;. One potential reason for failure is that the
162
+
sun does not rise at all, which happens inside the polar circles for part of
163
+
the year.
118
164
</para>
119
165
</refsect1>
120
166

...
...
@@ -137,9 +183,19 @@
137
183
</row>
138
184
</thead>
139
185
<tbody>
140
-
141
-
&date.timezone.errors.changelog;
142
-
186
+
<row>
187
+
<entry>8.1.0</entry>
188
+
<entry>
189
+
This function has been deprecated in favor of <function>date_sun_info</function>.
190
+
</entry>
191
+
</row>
192
+
<row>
193
+
<entry>8.0.0</entry>
194
+
<entry>
195
+
<parameter>latitude</parameter>, <parameter>longitude</parameter>,
196
+
<parameter>zenith</parameter> and <parameter>utcOffset</parameter> are nullable now.
197
+
</entry>
198
+
</row>
143
199
</tbody>
144
200
</tgroup>
145
201
</informaltable>
...
...
@@ -174,6 +230,23 @@ Mon Dec 20 2004, sunrise time : 08:54
174
230
]]>
175
231
</screen>
176
232
</example>
233
+
<example>
234
+
<title>No sunrise</title>
235
+
<programlisting role="php">
236
+
<![CDATA[
237
+
<?php
238
+
$solstice = strtotime('2017-12-21');
239
+
var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));
240
+
?>
241
+
]]>
242
+
</programlisting>
243
+
&example.outputs;
244
+
<screen>
245
+
<![CDATA[
246
+
bool(false)
247
+
]]>
248
+
</screen>
249
+
</example>
177
250
</para>
178
251
</refsect1>
179
252

...
...
@@ -181,12 +254,11 @@ Mon Dec 20 2004, sunrise time : 08:54
181
254
&reftitle.seealso;
182
255
<para>
183
256
<simplelist>
184
-
<member><function>date_sunset</function></member>
257
+
<member><function>date_sun_info</function></member>
185
258
</simplelist>
186
259
</para>
187
260
</refsect1>
188
261
</refentry>
189
-

190
262
<!-- Keep this comment at the end of the file
191
263
Local variables:
192
264
mode: sgml
193
265