repo_zf1/documentation/manual/en/module_specs/Zend_Date-Creation.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.date.creation">
    <title>Creation of Dates</title>

    <para>
        <classname>Zend_Date</classname> provides several different ways to create a new instance of
        itself. As there are different needs the most convenient ways will be shown in this chapter.
    </para>

    <sect2 id="zend.date.creation.actual">
        <title>Create the Actual Date</title>

        <para>
            The simplest way of creating a date object is to create the actual date. You can either
            create a new instance with <command>new Zend_Date()</command> or use the convenient
            static method <methodname>Zend_Date::now()</methodname> which both will return the
            actual date as new instance of <classname>Zend_Date</classname>. The actual date always
            include the actual date and time for the actual set timezone.
        </para>

        <example id="zend.date.creation.actual.example-1">
            <title>Date Creation by Instance</title>

            <para>
                Date creation by creating a new instance means that you do not need to give an
                parameter. Of course there are several parameters which will be described later but
                normally this is the simplest and most used way to get the actual date as
                <classname>Zend_Date</classname> instance.
            </para>

            <programlisting language="php"><![CDATA[
$date = new Zend_Date();
]]></programlisting>
        </example>

        <example id="zend.date.creation.actual.example-2">
            <title>Static Date Creation</title>

            <para>
                Sometimes it is easier to use a static method for date creation. Therefor you can
                use the <emphasis><methodname>now()</methodname></emphasis> method. It returns a
                new instance of <classname>Zend_Date</classname> the same way as if you would use
                <command>new Zend_Date()</command>. But it will always return the actual date and
                can not be changed by giving optional parameters.
            </para>

            <programlisting language="php"><![CDATA[
$date = Zend_Date::now();
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.creation.database">
        <title>Create a Date from Database</title>

        <para>
            Databases are often used to store date values. But the problem is, that every database
            outputs its date values in a different way. <emphasis>MsSQL</emphasis> databases use a
            quite different standard date output than <emphasis>MySQL</emphasis> databases. But for
            simplification <classname>Zend_Date</classname> makes it very easy to create a date
            from database date values.
        </para>

        <para>
            Of course each database can be said to convert the output of a defined column to a
            special value. For example you could convert a <emphasis>datetime</emphasis> value to
            output a minute value. But this is time expensive and often you are in need of handling
            dates in an other way than expected when creating the database query.
        </para>

        <para>
            So we have one quick and one convenient way of creating dates from database values.
        </para>

        <example id="zend.date.creation.database.example-1">
            <title>Quick Creation of Dates from Database Date Values</title>

            <para>
                All databases are known to handle queries as fast as possible. They are built to act
                and respond quick. The quickest way for handling dates is to get unix timestamps
                from the database. All databases store date values internal as timestamp (not unix
                timestamp). This means that the time for creating a timestamp through a query is
                much smaller than converting it to a specified format.
            </para>

            <programlisting language="php"><![CDATA[
// SELECT UNIX_TIMESTAMP(my_datetime_column) FROM my_table
$date = new Zend_Date($unixtimestamp, Zend_Date::TIMESTAMP);
]]></programlisting>
        </example>

        <example id="zend.date.creation.database.example-2">
            <title>Convenient Creation of Dates from Database Date Values</title>

            <para>
                The standard output of all databases is quite different even if it looks the same on
                the first eyecatch. But all are part of the <acronym>ISO</acronym> Standard and
                explained through it. So the easiest way of date creation is the usage of
                <constant>Zend_Date::ISO_8601</constant>. Databases which are known to be
                recognised by <constant>Zend_Date::ISO_8601</constant> are
                <emphasis>MySQL</emphasis>, <emphasis>MsSQL</emphasis> for example. But all
                databases are also able to return a <acronym>ISO-8601</acronym> representation of a
                date column. <acronym>ISO-8601</acronym> has the big advantage that it is human
                readable. The disadvantage is that <acronym>ISO-8601</acronym> needs more time for
                computation than a simple unix timestamp. But it should also be mentioned that unix
                timestamps are only supported for dates after 1 January 1970.
            </para>

            <programlisting language="php"><![CDATA[
// SELECT datecolumn FROM my_table
$date = new Zend_Date($datecolumn, Zend_Date::ISO_8601);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.creation.array">
        <title>Create Dates from an Array</title>

        <para>
            Dates can also be created by the usage of an array. This is a simple and easy way. The
            used array keys are:
        </para>

        <itemizedlist mark='opencircle'>
            <listitem><para><emphasis>day</emphasis>: day of the date as number</para></listitem>

            <listitem>
                <para><emphasis>month</emphasis>: month of the date as number</para>
            </listitem>

            <listitem><para><emphasis>year</emphasis>: full year of the date</para></listitem>
            <listitem><para><emphasis>hour</emphasis>: hour of the date</para></listitem>
            <listitem><para><emphasis>minute</emphasis>: minute of the date</para></listitem>
            <listitem><para><emphasis>second</emphasis>: second of the date</para></listitem>
        </itemizedlist>

        <example id="zend.date.creation.array.example">
            <title>Date Creation by Array</title>

            <para>
                Normally you will give a complete date array for creation of a new date instance.
                But when you do not give all values, the not given array values are zeroed. This
                means that if f.e. no hour is given the hour <emphasis>0</emphasis> is used.
            </para>

            <programlisting language="php"><![CDATA[
$datearray = array('year' => 2006,
                   'month' => 4,
                   'day' => 18,
                   'hour' => 12,
                   'minute' => 3,
                   'second' => 10);
$date = new Zend_Date($datearray);
]]></programlisting>

            <programlisting language="php"><![CDATA[
$datearray = array('year' => 2006, 'month' => 4, 'day' => 18);
$date = new Zend_Date($datearray);
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->