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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.date.basic">
   4     <title>Basic Methods</title>
   5
   6     <para>
   7         The following sections show basic usage of <classname>Zend_Date</classname> primarily by
   8         example. For this manual, "dates" always imply a calendar date with a time, even when not
   9         explicitly mentioned, and vice-versa. The part not specified defaults to an internal
  10         representation of "zero". Thus, adding a date having no calendar date and a time value of 12
  11         hours to another date consisting only of a calendar date would result in a date having that
  12         calendar date and a time of "noon".
  13     </para>
  14
  15     <para>
  16         Setting only a specific date, with no time part, implies a time set to 00:00:00. Conversely,
  17         setting only a specific time implies a date internally set to 01.01.1970 plus the number of
  18         seconds equal to the elapsed hours, minutes, and seconds identified by the time. Normally,
  19         people measure things from a starting point, such as the year 0 A.D. However, many software
  20         systems use the first second of the year 1970 as the starting point, and denote times as a
  21         timestamp offset counting the number of seconds elapsed from this starting point.
  22     </para>
  23
  24     <sect2 id="zend.date.basic.creation">
  25         <title>Current Date</title>
  26
  27         <para>
  28             Without any arguments, constructing an instance returns an object in the default locale
  29             with the current, local date using <acronym>PHP</acronym>'s
  30             <methodname>time()</methodname> function to obtain the <ulink
  31                 url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamp</ulink>
  32             for the object. Make sure your <acronym>PHP</acronym> environment has the correct
  33             <link linkend="zend.date.setdefaulttimezone">default timezone</link>.
  34         </para>
  35
  36         <example id="zend.date.basic.creation.example-1">
  37             <title>Creating the Current Date</title>
  38
  39             <programlisting language="php"><![CDATA[
  40 $date = new Zend_Date();
  41
  42 // Output of the current timestamp
  43 print $date;
  44 ]]></programlisting>
  45         </example>
  46     </sect2>
  47
  48     <sect2 id="zend.date.basic.functions">
  49         <title>Zend_Date by Example</title>
  50
  51         <para>
  52             Reviewing basic methods of <classname>Zend_Date</classname> is a good place to start for
  53             those unfamiliar with date objects in other languages or frameworks. A small example
  54             will be provided for each method below.
  55         </para>
  56
  57         <sect3 id="zend.date.simple.functions.get">
  58             <title>Output a Date</title>
  59
  60             <para>
  61                 The date in a <classname>Zend_Date</classname> object may be obtained as a localized
  62                 integer or string using the <methodname>get()</methodname> method. There are many
  63                 available options, which will be explained in later sections.
  64             </para>
  65
  66             <example id="zend.date.simple.functions.get.example-1">
  67                 <title>get() - Output a Date</title>
  68
  69                 <programlisting language="php"><![CDATA[
  70 $date = new Zend_Date();
  71
  72 // Output of the desired date
  73 print $date->get();
  74 ]]></programlisting>
  75             </example>
  76         </sect3>
  77
  78         <sect3 id="zend.date.simple.functions.set">
  79             <title>Setting a Date</title>
  80
  81             <para>
  82                 The <methodname>set()</methodname> method alters the date stored in the object, and
  83                 returns the final date value as a timestamp (not an object). Again, there are many
  84                 options which will be explored in later sections.
  85             </para>
  86
  87             <example id="zend.date.simple.functions.set.example-1">
  88                 <title>set() - Set a Date</title>
  89
  90                 <programlisting language="php"><![CDATA[
  91 $date = new Zend_Date();
  92
  93 // Setting of a new time
  94 $date->set('13:00:00',Zend_Date::TIMES);
  95 print $date->get(Zend_Date::W3C);
  96 ]]></programlisting>
  97             </example>
  98         </sect3>
  99
 100         <sect3 id="zend.date.simple.functions.add">
 101             <title>Adding and Subtracting Dates</title>
 102
 103             <para>
 104                 Adding two dates with <methodname>add()</methodname> usually involves adding a real
 105                 date in time with an artificial timestramp representing a date part, such as 12
 106                 hours, as shown in the example below. Both <methodname>add()</methodname> and
 107                 <methodname>sub()</methodname> use the same set of options as
 108                 <methodname>set()</methodname>, which will be explained later.
 109             </para>
 110
 111             <example id="zend.date.simple.functions.add.example-1">
 112                 <title>add() - Adding Dates</title>
 113
 114                 <programlisting language="php"><![CDATA[
 115 $date = new Zend_Date();
 116
 117 // changes $date by adding 12 hours
 118 $date->add('12:00:00', Zend_Date::TIMES);
 119
 120 echo "Date via get() = ", $date->get(Zend_Date::W3C), "\n";
 121
 122 // use magic __toString() method to call Zend_Date's toString()
 123 echo "Date via toString() = ", $date, "\n";
 124 ]]></programlisting>
 125             </example>
 126         </sect3>
 127
 128         <sect3 id="zend.date.simple.functions.compare">
 129             <title>Comparison of Dates</title>
 130
 131             <para>
 132                 All basic <classname>Zend_Date</classname> methods can operate on entire dates
 133                 contained in the objects, or can operate on date parts, such as comparing the
 134                 minutes value in a date to an absolute value. For example, the current minutes in
 135                 the current time may be compared with a specific number of minutes using
 136                 <methodname>compare()</methodname>, as in the example below.
 137             </para>
 138
 139             <example id="zend.date.simple.functions.compare.example-1">
 140                 <title>compare() - Compare Dates</title>
 141
 142                 <programlisting language="php"><![CDATA[
 143 $date = new Zend_Date();
 144
 145 // Comparation of both times
 146 if ($date->compare(10, Zend_Date::MINUTE) == -1) {
 147     print "This hour is less than 10 minutes old";
 148 } else {
 149     print "This hour is at least 10 minutes old";
 150 }
 151 ]]></programlisting>
 152             </example>
 153
 154             <para>
 155                 For simple equality comparisons, use <methodname>equals()</methodname>, which
 156                 returns a boolean.
 157             </para>
 158
 159             <example id="zend.date.simple.functions.compare.example-2">
 160                 <title>equals() - Identify a Date or Date Part</title>
 161
 162                 <programlisting language="php"><![CDATA[
 163 $date = new Zend_Date();
 164
 165 // Comparation of the two dates
 166 if ($date->equals(10, Zend_Date::HOUR)) {
 167     print "It's 10 o'clock. Time to get to work.";
 168 } else {
 169     print "It is not 10 o'clock. You can keep sleeping.";
 170 }
 171 ]]></programlisting>
 172             </example>
 173         </sect3>
 174     </sect2>
 175 </sect1>
 176 <!--
 177 vim:se ts=4 sw=4 et:
 178 -->