reference/datetime/functions/date-sun-info.xml
5c951013ca04161992efed8b86fb40f55669958e
5c951013ca04161992efed8b86fb40f55669958e
...
...
@@ -9,7 +9,7 @@
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
11
<type>array</type><methodname>date_sun_info</methodname>
12
-
<methodparam><type>int</type><parameter>time</parameter></methodparam>
12
+
<methodparam><type>int</type><parameter>timestamp</parameter></methodparam>
13
13
<methodparam><type>float</type><parameter>latitude</parameter></methodparam>
14
14
<methodparam><type>float</type><parameter>longitude</parameter></methodparam>
15
15
</methodsynopsis>
...
...
@@ -20,10 +20,10 @@
20
20
<para>
21
21
<variablelist>
22
22
<varlistentry>
23
-
<term><parameter>time</parameter></term>
23
+
<term><parameter>timestamp</parameter></term>
24
24
<listitem>
25
25
<para>
26
-
Timestamp.
26
+
Unix timestamp.
27
27
</para>
28
28
</listitem>
29
29
</varlistentry>
...
...
@@ -51,6 +51,120 @@
51
51
&reftitle.returnvalues;
52
52
<para>
53
53
Returns array on success&return.falseforfailure;.
54
+
The structure of the array is detailed in the following list:
55
+
</para>
56
+
<para>
57
+
<variablelist>
58
+
<varlistentry>
59
+
<term><literal>sunrise</literal></term>
60
+
<listitem>
61
+
<simpara>
62
+
The timestamp of the sunrise (zenith angle = 90°35').
63
+
</simpara>
64
+
</listitem>
65
+
</varlistentry>
66
+
<varlistentry>
67
+
<term><literal>sunset</literal></term>
68
+
<listitem>
69
+
<simpara>
70
+
The timestamp of the sunset (zenith angle = 90°35').
71
+
</simpara>
72
+
</listitem>
73
+
</varlistentry>
74
+
<varlistentry>
75
+
<term><literal>transit</literal></term>
76
+
<listitem>
77
+
<simpara>
78
+
The timestamp when the sun is at its zenith, i.e. has reached its topmost
79
+
point.
80
+
</simpara>
81
+
</listitem>
82
+
</varlistentry>
83
+
<varlistentry>
84
+
<term><literal>civil_twilight_begin</literal></term>
85
+
<listitem>
86
+
<simpara>
87
+
The start of the civil dawn (zenith angle = 96°). It ends at
88
+
<literal>sunrise</literal>.
89
+
</simpara>
90
+
</listitem>
91
+
</varlistentry>
92
+
<varlistentry>
93
+
<term><literal>civil_twilight_end</literal></term>
94
+
<listitem>
95
+
<simpara>
96
+
The end of the civil dusk (zenith angle = 96°). It starts at
97
+
<literal>sunset</literal>.
98
+
</simpara>
99
+
</listitem>
100
+
</varlistentry>
101
+
<varlistentry>
102
+
<term><literal>nautical_twilight_begin</literal></term>
103
+
<listitem>
104
+
<simpara>
105
+
The start of the nautical dawn (zenith angle = 102°). It ends at
106
+
<literal>civil_twilight_begin</literal>.
107
+
</simpara>
108
+
</listitem>
109
+
</varlistentry>
110
+
<varlistentry>
111
+
<term><literal>nautical_twilight_end</literal></term>
112
+
<listitem>
113
+
<simpara>
114
+
The end of the nautical dusk (zenith angle = 102°). It starts at
115
+
<literal>civil_twilight_end</literal>.
116
+
</simpara>
117
+
</listitem>
118
+
</varlistentry>
119
+
<varlistentry>
120
+
<term><literal>astronomical_twilight_begin</literal></term>
121
+
<listitem>
122
+
<simpara>
123
+
The start of the astronomical dawn (zenith angle = 108°). It ends at
124
+
<literal>nautical_twilight_begin</literal>.
125
+
</simpara>
126
+
</listitem>
127
+
</varlistentry>
128
+
<varlistentry>
129
+
<term><literal>astronomical_twilight_end</literal></term>
130
+
<listitem>
131
+
<simpara>
132
+
The end of the astronomical dusk (zenith angle = 108°). It starts at
133
+
<literal>nautical_twilight_end</literal>.
134
+
</simpara>
135
+
</listitem>
136
+
</varlistentry>
137
+
</variablelist>
138
+
</para>
139
+
<para>
140
+
The values of the array elements are either UNIX timestamps, &false; if the
141
+
sun is below the respective zenith for the whole day, or &true; if the sun is
142
+
above the respective zenith for the whole day.
143
+
</para>
144
+
</refsect1>
145
+
146
+
<refsect1 role="changelog">
147
+
&reftitle.changelog;
148
+
<para>
149
+
<informaltable>
150
+
<tgroup cols="2">
151
+
<thead>
152
+
<row>
153
+
<entry>&Version;</entry>
154
+
<entry>&Description;</entry>
155
+
</row>
156
+
</thead>
157
+
<tbody>
158
+
<row>
159
+
<entry>7.2.0</entry>
160
+
<entry>
161
+
The calculation was fixed with regards to local midnight instead of
162
+
local noon, which changes the results slightly.
163
+
</entry>
164
+
</row>
165
+
</tbody>
166
+
</tgroup>
167
+
</informaltable>
54
168
</para>
55
169
</refsect1>
56
170
...
...
@@ -85,20 +199,102 @@ astronomical_twilight_end: 17:12:00
85
199
</screen>
86
200
</example>
87
201
</para>
88
-
</refsect1>
89
202
90
-
<refsect1 role="seealso">
91
-
&reftitle.seealso;
92
203
<para>
93
-
<simplelist>
94
-
<member><function>date_sunrise</function></member>
95
-
<member><function>date_sunset</function></member>
96
-
</simplelist>
204
+
<example>
205
+
<title>Polar night, with some processing</title>
206
+
<programlisting role="php">
207
+
<![CDATA[
208
+
<?php
209
+
$tz = new \DateTimeZone('America/Anchorage');
210
+
211
+
$si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
212
+
foreach ($si as $key => $value) {
213
+
echo
214
+
match ($value) {
215
+
true => 'always',
216
+
false => 'never',
217
+
default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
218
+
},
219
+
": {$key}",
220
+
"\n";
221
+
}
222
+
?>
223
+
]]>
224
+
</programlisting>
225
+
&example.outputs;
226
+
<screen>
227
+
<![CDATA[
228
+
never: sunrise
229
+
never: sunset
230
+
12:52:18 AKST: transit
231
+
10:53:19 AKST: civil_twilight_begin
232
+
14:51:17 AKST: civil_twilight_end
233
+
09:01:47 AKST: nautical_twilight_begin
234
+
16:42:48 AKST: nautical_twilight_end
235
+
07:40:47 AKST: astronomical_twilight_begin
236
+
18:03:49 AKST: astronomical_twilight_end
237
+
]]>
238
+
</screen>
239
+
</example>
240
+
</para>
241
+
242
+
<para>
243
+
<example>
244
+
<title>Midnight sun (Tromsø, Norway)</title>
245
+
<programlisting role="php">
246
+
<![CDATA[
247
+
<?php
248
+
$si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
249
+
print_r($si);
250
+
?>
251
+
]]>
252
+
</programlisting>
253
+
&example.outputs;
254
+
<screen>
255
+
<![CDATA[
256
+
Array
257
+
(
258
+
[sunrise] => 1
259
+
[sunset] => 1
260
+
[transit] => 1656240426
261
+
[civil_twilight_begin] => 1
262
+
[civil_twilight_end] => 1
263
+
[nautical_twilight_begin] => 1
264
+
[nautical_twilight_end] => 1
265
+
[astronomical_twilight_begin] => 1
266
+
[astronomical_twilight_end] => 1
267
+
)
268
+
]]>
269
+
</screen>
270
+
</example>
271
+
</para>
272
+
273
+
<para>
274
+
<example>
275
+
<title>Calculating length of day (Kyiv)</title>
276
+
<programlisting role="php">
277
+
<![CDATA[
278
+
<?php
279
+
$si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
280
+
$diff = $si['sunset'] - $si['sunrise'];
281
+
echo "Length of day: ",
282
+
floor($diff / 3600), "h ",
283
+
floor(($diff % 3600) / 60), "s\n";
284
+
?>
285
+
]]>
286
+
</programlisting>
287
+
&example.outputs;
288
+
<screen>
289
+
<![CDATA[
290
+
Length of day: 13h 56s
291
+
]]>
292
+
</screen>
293
+
</example>
97
294
</para>
98
295
</refsect1>
99
296
100
297
</refentry>
101
-
102
298
<!-- Keep this comment at the end of the file
103
299
Local variables:
104
300
mode: sgml
105
301