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 <emphasis>new Zend_Date()</emphasis> or use the convenient static method
            <emphasis>Zend_Date::now()</emphasis> 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><code>now()</code></emphasis> method. It returns a new instance of
                <classname>Zend_Date</classname> the same way as if you would use <code>new Zend_Date()</code>. 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. <code>MsSQL</code> databases use a quite different standard date
            output than <code>MySQL</code> 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 <code>datetime</code> 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 <code>ISO</code> Standard and explained through it. So the
                easiest way of date creation is the usage of <classname>Zend_Date::ISO_8601</classname>. Databases which are
                known to be recognised by <classname>Zend_Date::ISO_8601</classname> are <code>MySQL</code>,
                <code>MsSQL</code> for example. But all databases are also able to return a <code>ISO 8601</code>
                representation of a date column. <code>ISO 8601</code> has the big advantage that it is human
                readable. The disadvantage is that <code>ISO 8601</code> 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>

        <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>
        </para>

        <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:
-->