construct.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 71692b6f4cace8dca72a18ccd80d4cd7305e5d4e Maintainer: cmb Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 4586854a24b1ca532b5c9ba2410db1f1eee338ed Reviewer: samesch -->
<!-- CREDITS: Yannic Schnetz -->
<refentry xml:id="dateinterval.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>DateInterval::__construct</refname>
  <refpurpose>Erstellt ein neues DateInterval-Objekt</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <constructorsynopsis role="DateInterval">
   <modifier>public</modifier> <methodname>DateInterval::__construct</methodname>
   <methodparam><type>string</type><parameter>duration</parameter></methodparam>
  </constructorsynopsis>
  <para>
   Erstellt ein neues DateInterval-Objekt.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>duration</parameter></term>
     <listitem>
      <para>
       Eine Intervall-Spezifikation
      </para>
      <para>
       Das Format beginnt mit dem Buchstaben <literal>P</literal> für
       <quote>period</quote>. Jede Periodendauer wird als Integer-Wert,
       gefolgt von einem Perioden-Bezeichner, repräsentiert. Enthält die
       Dauer Zeitelemente, wird diesem Teil der Spezifikation der Buchstabe
       <literal>T</literal> vorangestellt.
      </para>
      <para>
       <table>
        <title>
         Perioden-Bezeichner für <parameter>duration</parameter>
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Perioden-Bezeichner</entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>Y</literal></entry>
           <entry>Jahre</entry>
          </row>
          <row>
           <entry><literal>M</literal></entry>
           <entry>Monate</entry>
          </row>
          <row>
           <entry><literal>D</literal></entry>
           <entry>Tage</entry>
          </row>
          <row>
           <entry><literal>W</literal></entry>
           <entry>
            Wochen. Diese werden in Tage umgerechnet.
            Vor PHP 8.0.0 konnte es nicht mit <literal>D</literal> kombiniert werden.
           </entry>
          </row>
          <row>
           <entry><literal>H</literal></entry>
           <entry>Stunden</entry>
          </row>
          <row>
           <entry><literal>M</literal></entry>
           <entry>Minuten</entry>
          </row>
          <row>
           <entry><literal>S</literal></entry>
           <entry>Sekunden</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Hier sind ein paar einfache Beispiele:
       Zwei Tage entsprechen <literal>P2D</literal>.
       Zwei Sekunden entsprechen <literal>PT2S</literal>.
       Sechs Jahre und fünf Minuten entsprechen <literal>P6YT5M</literal>.
       </para>
      <note>
       <para>
        Die Einheitstypen müssen von der größten Einheit links bis zur
        kleinsten Einheit rechts angegeben werden. Also Jahre vor Monaten,
        Monate vor Tagen, Tage vor Minuten etc. Also muss ein Jahr und vier
        Tage als <literal>P1Y4D</literal> dargestellt werden, nicht als
        <literal>P4D1Y</literal>.
       </para>
      </note>
      <para>
       Die Spezifikation kann aber auch als Zeitstempel angegeben werden.
       Ein Beispiel für ein Jahr und vier Tage wäre also
       <literal>P0001-00-04T00:00:00</literal>.
       Die Werte in diesem Format können allerdings den jeweiligen
       Übersprungspunkt der Periode nicht überschreiten
       (&zb; ist <literal>25</literal> Stunden ungültig).
      </para>
      <para>
       Diese Formate basieren auf der
       <link xlink:href="&url.iso-8601.duration;">ISO 8601-Spezifikation für die Dauer</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Wenn <parameter>duration</parameter> nicht als Intervall geparst werden
   kann, wird eine <classname>DateMalformedIntervalStringException</classname>
   geworfen. Vor PHP 8.3 wird eine <exceptionname>Exception</exceptionname>
   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>
       Wirft nun eine
       <exceptionname>DateMalformedIntervalStringException</exceptionname>
       anstelle von <exceptionname>Exception</exceptionname>.
      </entry>
     </row>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Nur die Eigenschaften <literal>y</literal> bis <literal>f</literal>,
       <literal>invert</literal> und <literal>days</literal> sowie die neue
       boolesche Eigenschaft <literal>from_string</literal> sind sichtbar.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <literal>W</literal> kann mit <literal>D</literal> kombiniert werden.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Erstellen und Verwenden von <classname>DateInterval</classname>-Objekten</title>
    <programlisting role="php">
<![CDATA[
<?php
// Ein konkretes Datum erstellen
$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

// Ein Intervall erstellen
$interval = new \DateInterval("P7D");

// Das Intervall hinzufügen
$someDate->add($interval);

// Das Intervall in eine Zeichenkette umwandeln
echo $interval->format("%d");
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
7
    </screen>
   </example>
  </para>

  <para>
   <example>
    <title><classname>DateInterval</classname>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php

$interval = new DateInterval('P1W2D');
var_dump($interval);

?>
]]>
    </programlisting>
    &example.outputs.82;
    <screen role="php">
<![CDATA[
object(DateInterval)#1 (10) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(9)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["from_string"]=>
  bool(false)
}
]]>
    </screen>
    &example.outputs.8;
    <screen role="php">
<![CDATA[
object(DateInterval)#1 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(9)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(0)
  ["special_amount"]=>
  int(0)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(0)
}
]]>
    </screen>
    &example.outputs.7;
    <screen role="php">
     <![CDATA[
object(DateInterval)#1 (16) {
  ["y"]=>
  int(0)
  ["m"]=>
  int(0)
  ["d"]=>
  int(2)
  ["h"]=>
  int(0)
  ["i"]=>
  int(0)
  ["s"]=>
  int(0)
  ["f"]=>
  float(0)
  ["weekday"]=>
  int(0)
  ["weekday_behavior"]=>
  int(0)
  ["first_last_day_of"]=>
  int(0)
  ["invert"]=>
  int(0)
  ["days"]=>
  bool(false)
  ["special_type"]=>
  int(0)
  ["special_amount"]=>
  int(0)
  ["have_weekday_relative"]=>
  int(0)
  ["have_special_relative"]=>
  int(0)
}
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>DateInterval::format</function></member>
    <member><function>DateTime::add</function></member>
    <member><function>DateTime::sub</function></member>
    <member><function>DateTime::diff</function></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
-->