Add a note about the timezone gotcha in easter_date().

Fixes doc bug #63597 (easter_date ignores PHP's timezone and uses the TZ env
variable).


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328495 c90b9560-bf6c-de11-be94-00142212c4b1

reference/calendar/functions/easter-date.xml

@@ -107,6 +107,56 @@ echo date("M-d-Y", easter_date(2001));        // Apr-15-2001
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    <function>easter_date</function> relies on your system's C library time
+    functions, rather than using PHP's internal date and time functions. As a
+    consequence, <function>easter_date</function> uses the
+    <literal>TZ</literal> environment variable to determine the time zone it
+    should operate in, rather than using PHP's
+    <link linkend="ini.date.timezone">default time zone</link>, which may
+    result in unexpected behaviour when using this function in conjunction
+    with other date functions in PHP.
+   </para>
+   <para>
+    As a workaround, you can use the <function>easter_days</function> with
+    <classname>DateTime</classname> and <classname>DateInterval</classname> to
+    calculate the start of Easter in your PHP time zone as follows:
+   </para>
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function get_easter_datetime($year) {
+    $base = new DateTime("$year-03-21");
+    $days = easter_days($year);
+
+    return $base->add(new DateInterval("P{$days}D"));
+}
+
+foreach (range(2012, 2015) as $year) {
+    printf("Easter in %d is on %s\n",
+           $year,
+           get_easter_datetime($year)->format('F j'));
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+Easter in 2012 is on April 8
+Easter in 2013 is on March 31
+Easter in 2014 is on April 20
+Easter in 2015 is on April 5
+]]>
+    </screen>
+   </informalexample>
+  </note>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>