Source for file Date.class.php

Documentation is available at Date.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Date
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Date Interface
  22.  *
  23.  * @category Gumbo
  24.  * @package Date
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc Date Interface
  30.  * @version 0.0.1
  31.  */
  32.  
  33. interface Gumbo_Interface_Date {
  34.     
  35.     /** STATIC METHODS **/
  36.     /**
  37.      * Checks if the current year is a Leap Year
  38.      * @param int $year 
  39.      * @return bool 
  40.      * @throws Gumbo_Exception
  41.      */
  42.     public static function isLeapYear ($year);
  43.     
  44.     
  45.     
  46.     /** ACTION METHODS **/
  47.     /**
  48.      * Resets the state to the original time stamp
  49.      */
  50.     public function reset ();
  51.     
  52.     /**
  53.      * Sets the time to the zero hour
  54.      * @postcondition $hour=0
  55.      * @postcondition $minutes=0
  56.      * @postcondition $seconds=0
  57.      */
  58.     public function zeroHour ();
  59.     
  60.     /**
  61.      * Increases the Year by number
  62.      * @precondition $num > 0
  63.      * @param int $num 
  64.      * @throws Gumbo_Exception
  65.      */
  66.     public function nextYear ($num=1);
  67.     
  68.     /**
  69.      * Increases the Month by number.
  70.      * @precondition $num > 0
  71.      * @param int $num 
  72.      * @throws Gumbo_Exception
  73.      */
  74.     public function nextMonth ($num=1);
  75.     
  76.     /**
  77.      * Increases the Week
  78.      * @precondition $num > 0
  79.      * @param int $num 
  80.      * @throws Gumbo_Exception
  81.      */
  82.     public function nextWeek ($num=1);
  83.     
  84.     /**
  85.      * Increases the Day
  86.      * @precondition $num > 0
  87.      * @param int $num 
  88.      * @throws Gumbo_Exception
  89.      */
  90.     public function nextDay ($num=1);
  91.     
  92.     /**
  93.      * Increases the Hour
  94.      * @precondition $num > 0
  95.      * @param int $num 
  96.      * @throws Gumbo_Exception
  97.      */
  98.     public function nextHour ($num=1);
  99.     
  100.     /**
  101.      * Increases the Minutes
  102.      * @precondition $num > 0
  103.      * @param int $num 
  104.      * @throws Gumbo_Exception
  105.      */
  106.     public function nextMinute ($num=1);
  107.     
  108.     /**
  109.      * Increases the Seconds
  110.      * @precondition $num > 0
  111.      * @param int $num 
  112.      * @throws Gumbo_Exception
  113.      */
  114.     public function nextSecond ($num=1);
  115.     
  116.     /**
  117.      * Decreases the Year
  118.      * @precondition $num > 0
  119.      * @param int $num 
  120.      * @throws Gumbo_Exception
  121.      */
  122.     public function prevYear ($num=1);
  123.     
  124.     /**
  125.      * Decreases the Month
  126.      * @precondition $num > 0
  127.      * @param int $num 
  128.      * @throws Gumbo_Exception
  129.      */
  130.     public function prevMonth ($num=1);
  131.     
  132.     /**
  133.      * Decreases the Week
  134.      * @precondition $num > 0
  135.      * @param int $num 
  136.      * @throws Gumbo_Exception
  137.      */
  138.     public function prevWeek ($num=1);
  139.     
  140.     /**
  141.      * Decreases the Day
  142.      * @precondition $num > 0
  143.      * @param int $num 
  144.      * @throws Gumbo_Exception
  145.      */
  146.     public function prevDay ($num=1);
  147.     
  148.     /**
  149.      * Decreases the Hour
  150.      * @precondition $num > 0
  151.      * @param int $num 
  152.      * @throws Gumbo_Exception
  153.      */
  154.     public function prevHour ($num=1);
  155.     
  156.     /**
  157.      * Decreases the Minutes
  158.      * @precondition $num > 0
  159.      * @param int $num 
  160.      * @throws Gumbo_Exception
  161.      */
  162.     public function prevMinute ($num=1);
  163.     
  164.     /**
  165.      * Decreases the Seconds
  166.      * @precondition $num > 0
  167.      * @param int $num 
  168.      * @throws Gumbo_Exception
  169.      */
  170.     public function prevSecond ($num=1);
  171.     
  172.     
  173.     
  174.     /** MUTATOR METHODS **/
  175.     /**
  176.      * Marks the Date as a Holiday
  177.      * @param bool $val 
  178.      * @throws Gumbo_Exception
  179.      */
  180.     public function setHoliday ($val);
  181.     
  182.     /**
  183.      * Sets the Date values of the object
  184.      * @param int $year 
  185.      * @param int $month 
  186.      * @param int $day 
  187.      */
  188.     public function setDate ($year, $month, $day);
  189.     
  190.     /**
  191.      * Sets the Time values of object
  192.      * @param int $hour 
  193.      * @param int $minutes 
  194.      * @param int $seconds 
  195.      */
  196.     public function setTime ($hour, $minutes, $seconds);
  197.     
  198.     /**
  199.      * Sets the Date by a stamp parsed down to yyyymmdd[hhmmss] format
  200.      * @param mixed $stamp 
  201.      * @throws Gumbo_Exception
  202.      */
  203.     public function setDateStamp ($stamp);
  204.     
  205.     /**
  206.      * Sets the Date by the UNIX Epoch
  207.      * @param int $time 
  208.      * @throws Gumbo_Exception
  209.      */
  210.     public function setDateEpoch ($time);
  211.     
  212.     /**
  213.      * Sets the Year
  214.      * @precondition $val > 0
  215.      * @param int $year 
  216.      * @throws Gumbo_Exception
  217.      */
  218.     public function setYear ($year);
  219.     
  220.     /**
  221.      * Sets the Month
  222.      * 
  223.      * The value can be the numberical month, a three-letter abbreviation of the
  224.      * month name, or the full name.
  225.      * 
  226.      * @precondition if int, 0 < $val < 13
  227.      * @param int|string$month 
  228.      * @throws Gumbo_Exception
  229.      */
  230.     public function setMonth ($month);
  231.     
  232.     /**
  233.      * Sets the Day
  234.      * @precondition 0 < $val <= 31
  235.      * @param int $day 
  236.      * @throws Gumbo_Exception
  237.      */
  238.     public function setDay ($day);
  239.     
  240.     /**
  241.      * Sets the Hour
  242.      * @precondition 0 <= $val < 24
  243.      * @param int $hour 
  244.      * @throws Gumbo_Exception
  245.      */
  246.     public function setHour ($hour);
  247.     
  248.     /**
  249.      * Sets the Minute
  250.      * @precondition 0 <= $val < 60
  251.      * @param int $min 
  252.      * @throws Gumbo_Exception
  253.      */
  254.     public function setMinute ($min);
  255.     
  256.     /**
  257.      * Sets the Seconds
  258.      * @precondition 0 <= $val < 60
  259.      * @param int $sec 
  260.      * @throws Gumbo_Exception
  261.      */
  262.     public function setSeconds ($sec);
  263.     
  264.     
  265.     
  266.     /** ACCESSOR METHODS **/
  267.     /**
  268.      * Returns a Date string in predefined format
  269.      * Format Codes:
  270.      * - 0 => yyyy-mm-dd hh:mm:ss (MySQL DATETIME)
  271.      * - 1 => yyyymm
  272.      * - 2 => yyyymmdd
  273.      * - 3 => yyyymmddhh
  274.      * - 4 => yyyymmddhhmm
  275.      * - 5 => yyyymmddhhmmss
  276.      * - 6 => UNIX EPOCH
  277.      * 
  278.      * To use more complex combinations, use a combination of the
  279.      * getDate() and getTime() methods.
  280.      * 
  281.      * @param int $format format code
  282.      * @return int|string
  283.      * @throws Gumbo_Exception
  284.      */
  285.     public function get ($format=null);
  286.     
  287.     /**
  288.      * Returns a formatted Date string
  289.      * Date Formats:
  290.      * - 0 => yyyy-mm-dd (default)
  291.      * - 1 => yyyymm
  292.      * - 2 => yyyymmdd
  293.      * - 3 => mm/dd/yyyy
  294.      * - 4 => [m]m/[d]d/yyyy
  295.      * - 5 => Mon [d]d[suffix], yyyy
  296.      * - 6 => Month [d]d[suffix], yyyy
  297.      * - 7 => Day, [d]d Mon yyyy
  298.      * 
  299.      * The method also uses the date() and strftime() functions.  The format
  300.      * would have to be a string representing values the function will parse.
  301.      * If the percent sign (%) is found, it will use strftime(), else it will
  302.      * use date().
  303.      * 
  304.      * @param string|int$format pre-defined format code or string stamp
  305.      * @throws Gumbo_Exception
  306.      * @uses Gumbo_Number
  307.      */
  308.     public function getDate ($format=null);
  309.     
  310.     /**
  311.      * Returns a formatted Time string
  312.      * Time Format:
  313.      * - 0 => hh:mm:ss (default)
  314.      * - 1 => hh
  315.      * - 2 => hhmm
  316.      * - 3 => hhmmss
  317.      * - 4 => hh:mm
  318.      * - 5 => hh:mm [am|pm]
  319.      * - 6 => [h]h:mm
  320.      * - 7 => [h]h:mm [am|pm]
  321.      * - 8 => hh:mm:ss
  322.      * - 9 => hh:mm:ss [am|pm]
  323.      * - 10 => [h]h:mm:ss
  324.      * - 11 => [h]h:mm:ss [am|pm]
  325.      * @param int $format pre-defined time format
  326.      * @return string 
  327.      * @throws Gumbo_Exception
  328.      */
  329.     public function getTime ($format=null);
  330.     
  331.     /**
  332.      * Returns the Century
  333.      * @return int|string
  334.      * @throws Gumbo_Exception
  335.      * @uses Gumbo_Number
  336.      */
  337.     public function getCentury ($as_string=false);
  338.     
  339.     /**
  340.      * Returns the Year requested format
  341.      * 
  342.      * Formats:
  343.      * 0 -> yyyy
  344.      * 1 -> yy
  345.      * 
  346.      * @param int $format 
  347.      * @return int|string
  348.      * @throws Gumbo_Exception
  349.      */
  350.     public function getYear ($format=null);
  351.     
  352.     /**
  353.      * Returns the Month in the requested format
  354.      * 
  355.      * Formats:
  356.      * 0 -> [m]m
  357.      * 1 -> mm
  358.      * 2 -> Mon (abbreviation)
  359.      * 3 -> Month (full name)
  360.      * 
  361.      * @param int $format 
  362.      * @return int|string
  363.      * @throws Gumbo_Exception
  364.      */
  365.     public function getMonth ($format=null);
  366.     
  367.     /**
  368.      * Returns the Week
  369.      * @return int 
  370.      */
  371.     public function getWeek ();
  372.     
  373.     /**
  374.      * Returns the Day in the requested format
  375.      * 
  376.      * Formats:
  377.      * - 0 => [d]d
  378.      * - 1 => dd
  379.      * - 2 => ## (numerical day of week)
  380.      * - 3 => Day (abbreviation)
  381.      * - 4 => Day (full name)
  382.      * - 5 => ## (day of year)
  383.      * 
  384.      * @param int $format 
  385.      * @return int|string
  386.      * @throws Gumbo_Exception
  387.      */
  388.     public function getDay ($format=null);
  389.     
  390.     /**
  391.      * Returns the Hour in the requested format
  392.      * 
  393.      * Formats:
  394.      * - 0 => [h]h (24-hour format)
  395.      * - 1 => hh (24-hour format)
  396.      * - 2 => [h]h (12-hour format)
  397.      * - 3 => hh (12-hour format)
  398.      * 
  399.      * @param int $format 
  400.      * @return int|string
  401.      * @throws Gumbo_Exception
  402.      */
  403.     public function getHour ($format=null);
  404.     
  405.     /**
  406.      * Returns the Minutes in the requested format
  407.      * 
  408.      * Format:
  409.      * - 0 => [m]m
  410.      * - 1 => mm
  411.      * 
  412.      * @param int $format 
  413.      * @return int|string
  414.      * @throws Gumbo_Exception
  415.      */
  416.     public function getMinute ($format=null);
  417.     
  418.     /**
  419.      * Returns the Seconds in the requested format
  420.      * 
  421.      * Format:
  422.      * - 0 => [s]s
  423.      * - 1 => ss
  424.      * 
  425.      * @param int $format 
  426.      * @return int|string
  427.      * @throws Gumbo_Exception
  428.      */
  429.     public function getSecond ($format=null);
  430.     
  431.     
  432.     
  433.     /**
  434.      * Returns an array of factual months
  435.      * @return array 
  436.      */
  437.     public function getMonthFacts ();
  438.     
  439.     /**
  440.      * Returns the total days within a month
  441.      * @param int $month 
  442.      * @return int 
  443.      * @throws Gumbo_Exception
  444.      */
  445.     public function totalDays ($month=null);
  446.     
  447.     
  448.     
  449.     /**
  450.      * Returns if the current day is on the weekend
  451.      * @return bool 
  452.      */
  453.     public function isWeekend ();
  454.     
  455.     /**
  456.      * Returns if the current day is on the weekday
  457.      * @return bool 
  458.      */
  459.     public function isWeekday ();
  460.     
  461.     /**
  462.      * Returns if the current day is a holiday
  463.      * @return bool 
  464.      */
  465.     public function isHoliday ();
  466.     
  467.     
  468.     
  469.     /**
  470.      * Returns if a Sunday
  471.      * @return bool 
  472.      */
  473.     public function isSunday ();
  474.     
  475.     /**
  476.      * Returns if a Monday
  477.      * @return bool 
  478.      */
  479.     public function isMonday ();
  480.     
  481.     /**
  482.      * Returns if a Tuesday
  483.      * @return bool 
  484.      */
  485.     public function isTuesday ();
  486.     
  487.     /**
  488.      * Returns if a Wednesday
  489.      * @return bool 
  490.      */
  491.     public function isWednesday ();
  492.     
  493.     /**
  494.      * Returns if a Thursday
  495.      * @return bool 
  496.      */
  497.     public function isThursday ();
  498.     
  499.     /**
  500.      * Returns if a Friday
  501.      * @return bool 
  502.      */
  503.     public function isFriday ();
  504.     
  505.     /**
  506.      * Returns if a Saturday
  507.      * @return bool 
  508.      */
  509.     public function isSaturday ();
  510.     
  511.     
  512.     
  513.     /**
  514.      * Returns if January
  515.      * @return bool 
  516.      */
  517.     public function isJanuary ();
  518.     
  519.     /**
  520.      * Returns if February
  521.      * @return bool 
  522.      */
  523.     public function isFebruary ();
  524.     
  525.     /**
  526.      * Returns if March
  527.      * @return bool 
  528.      */
  529.     public function isMarch ();
  530.     
  531.     /**
  532.      * Returns if April
  533.      * @return bool 
  534.      */
  535.     public function isApril ();
  536.     
  537.     /**
  538.      * Returns if May
  539.      * @return bool 
  540.      */
  541.     public function isMay ();
  542.     
  543.     /**
  544.      * Returns if June
  545.      * @return bool 
  546.      */
  547.     public function isJune ();
  548.     
  549.     /**
  550.      * Returns if July
  551.      * @return bool 
  552.      */
  553.     public function isJuly ();
  554.     
  555.     /**
  556.      * Returns if August
  557.      * @return bool 
  558.      */
  559.     public function isAugust ();
  560.     
  561.     /**
  562.      * Returns if September
  563.      * @return bool 
  564.      */
  565.     public function isSeptember ();
  566.     
  567.     /**
  568.      * Returns if October
  569.      * @return bool 
  570.      */
  571.     public function isOctober ();
  572.     
  573.     /**
  574.      * Returns if November
  575.      * @return bool 
  576.      */
  577.     public function isNovember ();
  578.     
  579.     /**
  580.      * Returns if December
  581.      * @return bool 
  582.      */
  583.     public function isDecember ();
  584.     
  585.     
  586.     
  587.     /**
  588.      * Returns if Winter
  589.      * @return boolean 
  590.      */
  591.     public function isWinter ();
  592.     
  593.     /**
  594.      * Returns if Spring
  595.      * @return boolean 
  596.      */
  597.     public function isSpring ();
  598.     
  599.     /**
  600.      * Returns if Summer
  601.      * @return boolean 
  602.      */
  603.     public function isSummer ();
  604.     
  605.     /**
  606.      * Returns if Fall
  607.      * @return boolean 
  608.      */
  609.     public function isFall ();
  610.     
  611.     
  612.     
  613.     /**
  614.      * Returns the difference from the supplied Date
  615.      * @param Gumbo_Interface_Date $date 
  616.      * @return array [when|year|month|day|hour|minute|second]
  617.      */
  618.     public function diff (Gumbo_Interface_Date $date);
  619.     
  620.     /**
  621.      * Returns the number of Years difference
  622.      * @param int|Gumbo_Interface_Date$val 
  623.      * @return int 
  624.      */
  625.     public function diffYear ($val);
  626.     
  627.     /**
  628.      * Returns the number of Months difference
  629.      * @param Gumbo_Interface_Date $val 
  630.      * @return int 
  631.      */
  632.     public function diffMonth (Gumbo_Interface_Date $val);
  633.     
  634.     /**
  635.      * Returns the number of Weeks difference
  636.      * @param Gumbo_Interface_Date $val 
  637.      * @return int 
  638.      */
  639.     public function diffWeek (Gumbo_Interface_Date $val);
  640.     
  641.     /**
  642.      * Returns the number of Days difference
  643.      * @param Gumbo_Interface_Date $val 
  644.      * @return int 
  645.      */
  646.     public function diffDay (Gumbo_Interface_Date $val);
  647.     
  648.     
  649.     
  650.     /**
  651.      * Returns the AM/PM time value
  652.      * @param bool $in_caps returns value in caps
  653.      * @return string 
  654.      * @throws Gumbo_Exception
  655.      */
  656.     public function meridien ($in_caps=false);
  657.     
  658. }
  659.  
  660. ?>