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 PHP's <code>time()</code> function to obtain the
            <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamp</ulink>
            for the object. Make sure your PHP 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 role="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
                <code>get()</code> 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 role="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 <code>set()</code> 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 role="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 <code>add()</code> 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
                <code>add()</code> and <code>sub()</code> use the same set of options as <code>set()</code>, which will
                be explained later.
            </para>

            <example id="zend.date.simple.functions.add.example-1">
                <title>add() - Adding Dates</title>
                <programlisting role="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
                <code>compare()</code>, as in the example below.
            </para>

            <example id="zend.date.simple.functions.compare.example-1">
                <title>compare() - Compare Dates</title>
                <programlisting role="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 <code>equals()</code>, which returns a boolean.
            </para>

            <example id="zend.date.simple.functions.compare.example-2">
                <title>equals() - Identify a Date or Date Part</title>
                <programlisting role="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:
-->