reference/datetime/functions/date-sun-info.xml
03b6583a4ade7a2b68b57fe958d2d9022b15a873
...
...
@@ -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>
...
...
@@ -50,7 +50,120 @@
50
50
<refsect1 role="returnvalues">
51
51
&reftitle.returnvalues;
52
52
<para>
53
-
Returns array on success&return.falseforfailure;.
53
+
Returns an array whose structure is detailed in the following list:
54
+
</para>
55
+
<para>
56
+
<variablelist>
57
+
<varlistentry>
58
+
<term><literal>sunrise</literal></term>
59
+
<listitem>
60
+
<simpara>
61
+
The timestamp of the sunrise (zenith angle = 90°35').
62
+
</simpara>
63
+
</listitem>
64
+
</varlistentry>
65
+
<varlistentry>
66
+
<term><literal>sunset</literal></term>
67
+
<listitem>
68
+
<simpara>
69
+
The timestamp of the sunset (zenith angle = 90°35').
70
+
</simpara>
71
+
</listitem>
72
+
</varlistentry>
73
+
<varlistentry>
74
+
<term><literal>transit</literal></term>
75
+
<listitem>
76
+
<simpara>
77
+
The timestamp when the sun is at its zenith, i.e. has reached its topmost
78
+
point.
79
+
</simpara>
80
+
</listitem>
81
+
</varlistentry>
82
+
<varlistentry>
83
+
<term><literal>civil_twilight_begin</literal></term>
84
+
<listitem>
85
+
<simpara>
86
+
The start of the civil dawn (zenith angle = 96°). It ends at
87
+
<literal>sunrise</literal>.
88
+
</simpara>
89
+
</listitem>
90
+
</varlistentry>
91
+
<varlistentry>
92
+
<term><literal>civil_twilight_end</literal></term>
93
+
<listitem>
94
+
<simpara>
95
+
The end of the civil dusk (zenith angle = 96°). It starts at
96
+
<literal>sunset</literal>.
97
+
</simpara>
98
+
</listitem>
99
+
</varlistentry>
100
+
<varlistentry>
101
+
<term><literal>nautical_twilight_begin</literal></term>
102
+
<listitem>
103
+
<simpara>
104
+
The start of the nautical dawn (zenith angle = 102°). It ends at
105
+
<literal>civil_twilight_begin</literal>.
106
+
</simpara>
107
+
</listitem>
108
+
</varlistentry>
109
+
<varlistentry>
110
+
<term><literal>nautical_twilight_end</literal></term>
111
+
<listitem>
112
+
<simpara>
113
+
The end of the nautical dusk (zenith angle = 102°). It starts at
114
+
<literal>civil_twilight_end</literal>.
115
+
</simpara>
116
+
</listitem>
117
+
</varlistentry>
118
+
<varlistentry>
119
+
<term><literal>astronomical_twilight_begin</literal></term>
120
+
<listitem>
121
+
<simpara>
122
+
The start of the astronomical dawn (zenith angle = 108°). It ends at
123
+
<literal>nautical_twilight_begin</literal>.
124
+
</simpara>
125
+
</listitem>
126
+
</varlistentry>
127
+
<varlistentry>
128
+
<term><literal>astronomical_twilight_end</literal></term>
129
+
<listitem>
130
+
<simpara>
131
+
The end of the astronomical dusk (zenith angle = 108°). It starts at
132
+
<literal>nautical_twilight_end</literal>.
133
+
</simpara>
134
+
</listitem>
135
+
</varlistentry>
136
+
</variablelist>
137
+
</para>
138
+
<para>
139
+
The values of the array elements are either UNIX timestamps, &false; if the
140
+
sun is below the respective zenith for the whole day, or &true; if the sun is
141
+
above the respective zenith for the whole day.
142
+
</para>
143
+
</refsect1>
144
+

145
+
<refsect1 role="changelog">
146
+
&reftitle.changelog;
147
+
<para>
148
+
<informaltable>
149
+
<tgroup cols="2">
150
+
<thead>
151
+
<row>
152
+
<entry>&Version;</entry>
153
+
<entry>&Description;</entry>
154
+
</row>
155
+
</thead>
156
+
<tbody>
157
+
<row>
158
+
<entry>7.2.0</entry>
159
+
<entry>
160
+
The calculation was fixed with regards to local midnight instead of
161
+
local noon, which changes the results slightly.
162
+
</entry>
163
+
</row>
164
+
</tbody>
165
+
</tgroup>
166
+
</informaltable>
54
167
</para>
55
168
</refsect1>
56
169

...
...
@@ -85,20 +198,102 @@ astronomical_twilight_end: 17:12:00
85
198
</screen>
86
199
</example>
87
200
</para>
88
-
</refsect1>
89
201

90
-
<refsect1 role="seealso">
91
-
&reftitle.seealso;
92
202
<para>
93
-
<simplelist>
94
-
<member><function>date_sunrise</function></member>
95
-
<member><function>date_sunset</function></member>
96
-
</simplelist>
203
+
<example>
204
+
<title>Polar night, with some processing</title>
205
+
<programlisting role="php">
206
+
<![CDATA[
207
+
<?php
208
+
$tz = new \DateTimeZone('America/Anchorage');
209
+

210
+
$si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
211
+
foreach ($si as $key => $value) {
212
+
echo
213
+
match ($value) {
214
+
true => 'always',
215
+
false => 'never',
216
+
default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
217
+
},
218
+
": {$key}",
219
+
"\n";
220
+
}
221
+
?>
222
+
]]>
223
+
</programlisting>
224
+
&example.outputs;
225
+
<screen>
226
+
<![CDATA[
227
+
never: sunrise
228
+
never: sunset
229
+
12:52:18 AKST: transit
230
+
10:53:19 AKST: civil_twilight_begin
231
+
14:51:17 AKST: civil_twilight_end
232
+
09:01:47 AKST: nautical_twilight_begin
233
+
16:42:48 AKST: nautical_twilight_end
234
+
07:40:47 AKST: astronomical_twilight_begin
235
+
18:03:49 AKST: astronomical_twilight_end
236
+
]]>
237
+
</screen>
238
+
</example>
239
+
</para>
240
+

241
+
<para>
242
+
<example>
243
+
<title>Midnight sun (Tromsø, Norway)</title>
244
+
<programlisting role="php">
245
+
<![CDATA[
246
+
<?php
247
+
$si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
248
+
print_r($si);
249
+
?>
250
+
]]>
251
+
</programlisting>
252
+
&example.outputs;
253
+
<screen>
254
+
<![CDATA[
255
+
Array
256
+
(
257
+
[sunrise] => 1
258
+
[sunset] => 1
259
+
[transit] => 1656240426
260
+
[civil_twilight_begin] => 1
261
+
[civil_twilight_end] => 1
262
+
[nautical_twilight_begin] => 1
263
+
[nautical_twilight_end] => 1
264
+
[astronomical_twilight_begin] => 1
265
+
[astronomical_twilight_end] => 1
266
+
)
267
+
]]>
268
+
</screen>
269
+
</example>
270
+
</para>
271
+

272
+
<para>
273
+
<example>
274
+
<title>Calculating length of day (Kyiv)</title>
275
+
<programlisting role="php">
276
+
<![CDATA[
277
+
<?php
278
+
$si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
279
+
$diff = $si['sunset'] - $si['sunrise'];
280
+
echo "Length of day: ",
281
+
floor($diff / 3600), "h ",
282
+
floor(($diff % 3600) / 60), "s\n";
283
+
?>
284
+
]]>
285
+
</programlisting>
286
+
&example.outputs;
287
+
<screen>
288
+
<![CDATA[
289
+
Length of day: 13h 56s
290
+
]]>
291
+
</screen>
292
+
</example>
97
293
</para>
98
294
</refsect1>
99
295

100
296
</refentry>
101
-

102
297
<!-- Keep this comment at the end of the file
103
298
Local variables:
104
299
mode: sgml
105
300



Translation status