easter-date.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: a0fcdcb58023bd4cb017fdba511df29b9f7a25f5 Maintainer: hholzgra Status: ready -->
<refentry xml:id="function.easter-date" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>easter_date</refname>
  <refpurpose>Zeitpunkt des Osterfestes (0 Uhr) als Unix-Timestamp</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>easter_date</methodname>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>year</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>CAL_EASTER_DEFAULT</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   Diese Funktion gibt den Unix-Timestamp (in Sekunden seit 1970) zurück,
   der dem Begin des Ostersonntag im durch <parameter>year</parameter>
   spezifizierten Jahr entspricht.
  </para>
  <para>
   Das Datum des Osterfestes wurde im Jahre 325 auf dem Konzil von Nicaea auf
   den ersten Sonntag nach Frühlingsvollmond, also dem Vollmond während oder
   direkt nach der Tagundnachtgleiche am 21. März, festgelegt. Der hier
   genutzte Algorithmus wurde um das Jahr 532 von Dionysius Exiguus
   eingeführt. Bis zum Jahr 1752 wird nach dem Julianischen Kalender ein
   einfacher 19jähriger Zyklus für die Bestimmung der Mondphasen benutzt. Im
   September 1752 übernahmen dann auch Britannien und seine Kolonien den von
   Clavius und Lilius vorgeschlagenen und im Oktober 1582 von Papst Gregor dem
   XIII. eingeführten Gregorianischen Kalender. Hierdurch wurden zwei
   Korrekturfaktoren eingeführt, um den Zyklus genauer abzubilden.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>year</parameter></term>
     <listitem>
      <para>
       Das Jahr muss auf 32-Bit-Systemen eine Zahl zwischen 1970 und 2037 sein
       und auf 64-Bit-Systemen eine Zahl zwischen 1970 und 2.000.000.000. Wenn
       nicht angegeben oder &null;, wird das aktuelle Jahr gemäß der lokalen
       Zeit verwendet.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Ermöglicht die Berechnung des Osterdatums basierend auf dem Julianischen
       Kalender, wenn auf <constant>CAL_EASTER_ALWAYS_JULIAN</constant> gesetzt.
       Siehe auch <link linkend="calendar.constants">Kalender-Konstanten</link>.
       </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Das Osterdatum als Unix-Timestamp.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Wenn auf einem 32-bit System eine Jahreszahl vor 1970 oder nach 2037 oder
   auf einem 64-Bit-System eine Jahreszahl nach 2.000.000.000 angegeben wird,
   wird ein <classname>ValueError</classname> geworfen.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.3.0</entry>
      <entry>
       Auf 64-Bit-Systemen akzeptiert der Parameter <parameter>Jahr</parameter>
       nun Werte innerhalb des Bereichs von 1970 bis 2.000.000.000.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>year</parameter> ist jetzt nullbar.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Wenn <parameter>year</parameter> außerhalb des zulässigen Bereichs
       liegt, wird nun ein <classname>ValueError</classname> geworfen; zuvor
       wurde ein Fehler der Stufe <constant>E_WARNING</constant> ausgegeben
       und die Funktion gab &false; zurück.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>easter_date</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php

echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
echo date("M-d-Y", easter_date(2001));        // Apr-15-2001

?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Verwendung von <function>easter_date</function> mit <classname>DateTime</classname></title>
    <programlisting role="php">
<![CDATA[
<?php

$timestamp = easter_date(2023);

$datetime = new \DateTime();
$datetime->setTimestamp($timestamp);

echo $datetime->format('M-d-Y'); // Apr-09-2023

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    <function>easter_date</function> verlässt sich auf die Zeitfunktionen der
    C-Bibliothek des Systems, anstatt die internen Datums- und Zeitfunktionen
    von PHP zu verwenden. Infolgedessen verwendet
    <function>easter_date</function> die Umgebungsvariable
    <literal>TZ</literal>, um die Zeitzone zu bestimmen, in der sie arbeiten
    soll, anstatt die <link linkend="ini.date.timezone">Standardzeitzone</link>
    von PHP zu verwenden. Dies kann unerwartetes Verhalten zur Folge haben,
    wenn diese Funktion in Verbindung mit anderen Datumsfunktionen in PHP
    verwendet wird.
   </para>
   <para>
    Als Workaround kann <function>easter_days</function> mit
    <classname>DateTime</classname> und <classname>DateInterval</classname>
    verwendet werden, um den Beginn von Ostern in der von PHP eingestellten
    Zeitzone wie folgt zu berechnen:
   </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("Ostern %d ist am %s\n",
           $year,
           get_easter_datetime($year)->format('j.n.'));
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Ostern 2012 ist am 8.4.
Ostern 2013 ist am 31.3.
Ostern 2014 ist am 20.4.
Ostern 2015 ist am 5.4.
]]>
    </screen>
   </informalexample>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     <function>easter_days</function> zur Berechnung des Osterdatums vor 1970
     oder nach 2037
    </member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->