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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.date.basic">
    <title>Basic Methods</title>

    <para>
        The following sections show basic usage of <classname>Zend_Date</classname> primarily by
        example. For this manual, "dates" always imply a calendar date with a time, even when not
        explicitly mentioned, and vice-versa. The part not specified defaults to an internal
        representation of "zero". Thus, adding a date having no calendar date and a time value of 12
        hours to another date consisting only of a calendar date would result in a date having that
        calendar date and a time of "noon".
    </para>

    <para>
        Setting only a specific date, with no time part, implies a time set to 00:00:00. Conversely,
        setting only a specific time implies a date internally set to 01.01.1970 plus the number of
        seconds equal to the elapsed hours, minutes, and seconds identified by the time. Normally,
        people measure things from a starting point, such as the year 0 A.D. However, many software
        systems use the first second of the year 1970 as the starting point, and denote times as a
        timestamp offset counting the number of seconds elapsed from this starting point.
    </para>

    <sect2 id="zend.date.basic.creation">
        <title>Current Date</title>

        <para>
            Without any arguments, constructing an instance returns an object in the default locale
            with the current, local date using <acronym>PHP</acronym>'s
            <methodname>time()</methodname> function to obtain the <ulink
                url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamp</ulink>
            for the object. Make sure your <acronym>PHP</acronym> environment has the correct
            <link linkend="zend.date.setdefaulttimezone">default timezone</link>.
        </para>

        <example id="zend.date.basic.creation.example-1">
            <title>Creating the Current Date</title>

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

// Output of the current timestamp
print $date;
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.date.basic.functions">
        <title>Zend_Date by Example</title>

        <para>
            Reviewing basic methods of <classname>Zend_Date</classname> is a good place to start for
            those unfamiliar with date objects in other languages or frameworks. A small example
            will be provided for each method below.
        </para>

        <sect3 id="zend.date.simple.functions.get">
            <title>Output a Date</title>

            <para>
                The date in a <classname>Zend_Date</classname> object may be obtained as a localized
                integer or string using the <methodname>get()</methodname> method. There are many
                available options, which will be explained in later sections.
            </para>

            <example id="zend.date.simple.functions.get.example-1">
                <title>get() - Output a Date</title>

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

// Output of the desired date
print $date->get();
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.date.simple.functions.set">
            <title>Setting a Date</title>

            <para>
                The <methodname>set()</methodname> method alters the date stored in the object, and
                returns the final date value as a timestamp (not an object). Again, there are many
                options which will be explored in later sections.
            </para>

            <example id="zend.date.simple.functions.set.example-1">
                <title>set() - Set a Date</title>

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

// Setting of a new time
$date->set('13:00:00',Zend_Date::TIMES);
print $date->get(Zend_Date::W3C);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.date.simple.functions.add">
            <title>Adding and Subtracting Dates</title>

            <para>
                Adding two dates with <methodname>add()</methodname> usually involves adding a real
                date in time with an artificial timestramp representing a date part, such as 12
                hours, as shown in the example below. Both <methodname>add()</methodname> and
                <methodname>sub()</methodname> use the same set of options as
                <methodname>set()</methodname>, which will be explained later.
            </para>

            <example id="zend.date.simple.functions.add.example-1">
                <title>add() - Adding Dates</title>

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

// changes $date by adding 12 hours
$date->add('12:00:00', Zend_Date::TIMES);

echo "Date via get() = ", $date->get(Zend_Date::W3C), "\n";

// use magic __toString() method to call Zend_Date's toString()
echo "Date via toString() = ", $date, "\n";
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.date.simple.functions.compare">
            <title>Comparison of Dates</title>

            <para>
                All basic <classname>Zend_Date</classname> methods can operate on entire dates
                contained in the objects, or can operate on date parts, such as comparing the
                minutes value in a date to an absolute value. For example, the current minutes in
                the current time may be compared with a specific number of minutes using
                <methodname>compare()</methodname>, as in the example below.
            </para>

            <example id="zend.date.simple.functions.compare.example-1">
                <title>compare() - Compare Dates</title>

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

// Comparation of both times
if ($date->compare(10, Zend_Date::MINUTE) == -1) {
    print "This hour is less than 10 minutes old";
} else {
    print "This hour is at least 10 minutes old";
}
]]></programlisting>
            </example>

            <para>
                For simple equality comparisons, use <methodname>equals()</methodname>, which
                returns a boolean.
            </para>

            <example id="zend.date.simple.functions.compare.example-2">
                <title>equals() - Identify a Date or Date Part</title>

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

// Comparation of the two dates
if ($date->equals(10, Zend_Date::HOUR)) {
    print "It's 10 o'clock. Time to get to work.";
} else {
    print "It is not 10 o'clock. You can keep sleeping.";
}
]]></programlisting>
            </example>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->