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

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

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



Translation status