archived-doc-en/reference/datetime/dateinterval/construct.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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>Creates a new DateInterval object</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>
   Creates a new DateInterval object.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>duration</parameter></term>
     <listitem>
      <para>
       An interval specification.
      </para>
      <para>
       The format starts with the letter <literal>P</literal>,
       for <quote>period.</quote>
       Each duration period is represented by an integer value
       followed by a period designator.
       If the duration contains time elements, that portion
       of the specification is preceded by the letter
       <literal>T</literal>.
      </para>
      <para>
       <table>
        <title>
         <parameter>duration</parameter> Period Designators
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Period Designator</entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>Y</literal></entry>
           <entry>years</entry>
          </row>
          <row>
           <entry><literal>M</literal></entry>
           <entry>months</entry>
          </row>
          <row>
           <entry><literal>D</literal></entry>
           <entry>days</entry>
          </row>
          <row>
           <entry><literal>W</literal></entry>
           <entry>
            weeks. Converted into days.
            Prior to PHP 8.0.0, can not be combined with <literal>D</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>H</literal></entry>
           <entry>hours</entry>
          </row>
          <row>
           <entry><literal>M</literal></entry>
           <entry>minutes</entry>
          </row>
          <row>
           <entry><literal>S</literal></entry>
           <entry>seconds</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Here are some simple examples.
       Two days is <literal>P2D</literal>.
       Two seconds is <literal>PT2S</literal>.
       Six years and five minutes is <literal>P6YT5M</literal>.
      </para>
      <note>
       <para>
        The unit types must be entered from the largest
        scale unit on the left to the smallest scale unit
        on the right.
        So years before months, months before days,
        days before minutes, etc.
        Thus one year and four days must be represented as
        <literal>P1Y4D</literal>, not <literal>P4D1Y</literal>.
       </para>
      </note>
      <para>
       The specification can also be represented as a date time.
       A sample of one year and four days would be
       <literal>P0001-00-04T00:00:00</literal>.
       But the values in this format can not exceed a given period's
       roll-over-point (e.g. <literal>25</literal> hours is invalid).
      </para>
      <para>
       These formats are based on the <link xlink:href="&url.iso-8601.duration;">ISO 8601 duration
       specification</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws an <classname>DateMalformedIntervalStringException</classname> when
   the <parameter>duration</parameter> cannot be parsed as an interval. Prior
   to PHP 8.3, this was <exceptionname>Exception</exceptionname>.
  </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>
       Now throws
       <exceptionname>DateMalformedIntervalStringException</exceptionname>
       instead of <exceptionname>Exception</exceptionname>.
      </entry>
     </row>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Only the <literal>y</literal> to <literal>f</literal>,
       <literal>invert</literal>, and <literal>days</literal> will be visible,
       including a new <literal>from_string</literal> boolean property.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <literal>W</literal> can be combined with <literal>D</literal>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Constructing and using <classname>DateInterval</classname> objects</title>
    <programlisting role="php">
<![CDATA[
<?php
// Create a specific date
$someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

// Create interval
$interval = new \DateInterval("P7D");

// Add interval
$someDate->add($interval);

// Convert interval to string
echo $interval->format("%d");
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
7
]]>
    </screen>
   </example>
  </para>

  <para>
   <example>
    <title><classname>DateInterval</classname> example</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
-->