00001 <?php
00002 /* SVN FILE: $Id: time_8php-source.html 675 2008-12-26 00:27:14Z gwoo $ */
00003 /**
00004  * Time Helper class file.
00005  *
00006  * PHP versions 4 and 5
00007  *
00008  * CakePHP(tm) :  Rapid Development Framework <http://www.cakephp.org/>
00009  * Copyright 2005-2008, Cake Software Foundation, Inc.
00010  *                              1785 E. Sahara Avenue, Suite 490-204
00011  *                              Las Vegas, Nevada 89104
00012  *
00013  * Licensed under The MIT License
00014  * Redistributions of files must retain the above copyright notice.
00015  *
00016  * @filesource
00017  * @copyright       Copyright 2005-2008, Cake Software Foundation, Inc.
00018  * @link                http://www.cakefoundation.org/projects/info/cakephp CakePHP(tm) Project
00019  * @package         cake
00020  * @subpackage      cake.cake.libs.view.helpers
00021  * @since           CakePHP(tm) v 0.10.0.1076
00022  * @version         $Revision: 675 $
00023  * @modifiedby      $LastChangedBy: gwoo $
00024  * @lastmodified    $Date: 2008-12-25 16:27:14 -0800 (Thu, 25 Dec 2008) $
00025  * @license         http://www.opensource.org/licenses/mit-license.php The MIT License
00026  */
00027 /**
00028  * Time Helper class for easy use of time data.
00029  *
00030  * Manipulation of time data.
00031  *
00032  * @package     cake
00033  * @subpackage  cake.cake.libs.view.helpers
00034  */
00035 class TimeHelper extends Helper {
00036 /**
00037  * Returns given string trimmed to given length, adding an ending (default: "..") if necessary.
00038  *
00039  * @param string $string String to trim
00040  * @param integer $length Length of returned string, excluding ellipsis
00041  * @param string $ending Ending to be appended after trimmed string
00042  * @return string Trimmed string
00043  * @access public
00044  */
00045     function trim($string, $length, $ending = '..') {
00046         return substr($string, 0, $length) . (strlen($string) > $length ? $ending : null);
00047     }
00048 /**
00049  * Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
00050  *
00051  * @param string $date_string Datetime string
00052  * @return string Formatted date string
00053  * @access public
00054  */
00055     function fromString($date_string) {
00056         if (is_integer($date_string) || is_numeric($date_string)) {
00057             return intval($date_string);
00058         } else {
00059             return strtotime($date_string);
00060         }
00061     }
00062 /**
00063  * Returns a nicely formatted date string for given Datetime string.
00064  *
00065  * @param string $date_string Datetime string or Unix timestamp
00066  * @param  boolean $return  Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00067  * @return string Formatted date string
00068  * @access public
00069  */
00070     function nice($date_string = null, $return = false) {
00071         if ($date_string != null) {
00072             $date = $this->fromString($date_string);
00073         } else {
00074             $date = time();
00075         }
00076 
00077         $ret = date("D, M jS Y, H:i", $date);
00078         return $this->output($ret, $return);
00079     }
00080 /**
00081  * Returns a formatted descriptive date string for given datetime string.
00082  *
00083  * If the given date is today, the returned string could be "Today, 16:54".
00084  * If the given date was yesterday, the returned string could be "Yesterday, 16:54".
00085  * If $date_string's year is the current year, the returned string does not
00086  * include mention of the year.
00087  *
00088  * @param string $date_string Datetime string or Unix timestamp
00089  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00090  * @return string Described, relative date string
00091  * @access public
00092  */
00093     function niceShort($date_string = null, $return = false) {
00094         $date = $date_string ? $this->fromString($date_string) : time();
00095         $y = $this->isThisYear($date) ? '' : ' Y';
00096 
00097         if ($this->isToday($date)) {
00098             $ret = "Today, " . date("H:i", $date);
00099         } elseif ($this->wasYesterday($date)) {
00100             $ret = "Yesterday, " . date("H:i", $date);
00101         } else {
00102             $ret = date("M jS{$y}, H:i", $date);
00103         }
00104 
00105         return $this->output($ret, $return);
00106     }
00107 /**
00108  * Returns true if given datetime string is today.
00109  *
00110  * @param string $date_string Datetime string or Unix timestamp
00111  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00112  * @return boolean True if datetime string is today
00113  * @access public
00114  */
00115     function isToday($date_string, $return = false) {
00116         $date = $this->fromString($date_string);
00117         $ret = date('Y-m-d', $date) == date('Y-m-d', time());
00118         return $this->output($ret, $return);
00119     }
00120 /**
00121  * Returns a partial SQL string to search for all records between two dates.
00122  *
00123  * @param string $date_string Datetime string or Unix timestamp
00124  * @param string $end Datetime string or Unix timestamp
00125  * @param string $field_name Name of database field to compare with
00126  * @param  boolean $return Whether this method should return a value  or output it. This overrides AUTO_OUTPUT.
00127  * @return string Partial SQL string.
00128  * @access public
00129  */
00130     function daysAsSql($begin, $end, $field_name, $return = false) {
00131         $begin = $this->fromString($begin);
00132         $end = $this->fromString($end);
00133         $begin = date('Y-m-d', $begin) . ' 00:00:00';
00134         $end = date('Y-m-d', $end) . ' 23:59:59';
00135 
00136         return $this->output("($field_name >= '$begin') AND ($field_name <= '$end')", $return);
00137     }
00138 /**
00139  * Returns a partial SQL string to search for all records between two times
00140  * occurring on the same day.
00141  *
00142  * @param string $date_string Datetime string or Unix timestamp
00143  * @param string $field_name Name of database field to compare with
00144  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00145  * @return string Partial SQL string.
00146  * @access public
00147  */
00148     function dayAsSql($date_string, $field_name, $return = false) {
00149         $date = $this->fromString($date_string);
00150         $ret = $this->daysAsSql($date_string, $date_string, $field_name);
00151         return $this->output($ret, $return);
00152     }
00153 /**
00154  * Returns true if given datetime string is within current year.
00155  *
00156  * @param string $date_string Datetime string or Unix timestamp
00157  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00158  * @return boolean True if datetime string is within current year
00159  * @access public
00160  */
00161     function isThisYear($date_string, $return = false) {
00162         $date = $this->fromString($date_string);
00163         $ret = date('Y', $date) == date('Y', time());
00164         return $this->output($ret, $return);
00165     }
00166 /**
00167  * Returns true if given datetime string was yesterday.
00168  *
00169  * @param string $date_string Datetime string or Unix timestamp
00170  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00171  * @return boolean True if datetime string was yesterday
00172  * @access public
00173  */
00174     function wasYesterday($date_string, $return = false) {
00175         $date = $this->fromString($date_string);
00176         $ret = date('Y-m-d', $date) == date('Y-m-d', strtotime('yesterday'));
00177         return $this->output($ret, $return);
00178     }
00179 /**
00180  * Returns true if given datetime string is tomorrow.
00181  *
00182  * @param string $date_string Datetime string or Unix timestamp
00183  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00184  * @return boolean True if datetime string was yesterday
00185  * @access public
00186  */
00187     function isTomorrow($date_string, $return = false) {
00188         $date = $this->fromString($date_string);
00189         $ret = date('Y-m-d', $date) == date('Y-m-d', strtotime('tomorrow'));
00190         return $this->output($ret, $return);
00191     }
00192 /**
00193  * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
00194  *
00195  * @param string $date_string Datetime string to be represented as a Unix timestamp
00196  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00197  * @return int Unix timestamp
00198  * @access public
00199  */
00200     function toUnix($date_string, $return = false) {
00201         $ret = strtotime($date_string);
00202         return $this->output($ret, $return);
00203     }
00204 /**
00205  * Returns a date formatted for Atom RSS feeds.
00206  *
00207  * @param string $date_string Datetime string or Unix timestamp
00208  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00209  * @return string Formatted date string
00210  * @access public
00211  */
00212     function toAtom($date_string, $return = false) {
00213         $date = $this->fromString($date_string);
00214         $ret = date('Y-m-d\TH:i:s\Z', $date);
00215         return $this->output($ret, $return);
00216     }
00217 /**
00218  * Formats date for RSS feeds
00219  *
00220  * @param string $date_string Datetime string or Unix timestamp
00221  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00222  * @return string Formatted date string
00223  * @access public
00224  */
00225     function toRSS($date_string, $return = false) {
00226         $date = $this->fromString($date_string);
00227         $ret = date("r", $date);
00228         return $this->output($ret, $return);
00229     }
00230 /**
00231  * Returns either a relative date or a formatted date depending
00232  * on the difference between the current time and given datetime.
00233  * $datetime should be in a <i>strtotime</i>-parsable format, like MySQL's datetime datatype.
00234  *
00235  * Relative dates look something like this:
00236  *  3 weeks, 4 days ago
00237  *  15 seconds ago
00238  * Formatted dates look like this:
00239  *  on 02/18/2004
00240  *
00241  * The returned string includes 'ago' or 'on' and assumes you'll properly add a word
00242  * like 'Posted ' before the function output.
00243  *
00244  * @param string $date_string Datetime string or Unix timestamp
00245  * @param string $format Default format if timestamp is used in $date_string
00246  * @param string $backwards False if $date_string is in the past, true if in the future
00247  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00248  * @return string Relative time string.
00249  * @access public
00250  */
00251     function timeAgoInWords($datetime_string, $format = 'j/n/y', $backwards = false, $return = false) {
00252         $datetime = $this->fromString($datetime_string);
00253 
00254         $in_seconds = $datetime;
00255         if ($backwards) {
00256             $diff = $in_seconds - time();
00257         } else {
00258             $diff = time() - $in_seconds;
00259         }
00260 
00261         $months = floor($diff / 2419200);
00262         $diff -= $months * 2419200;
00263         $weeks = floor($diff / 604800);
00264         $diff -= $weeks * 604800;
00265         $days = floor($diff / 86400);
00266         $diff -= $days * 86400;
00267         $hours = floor($diff / 3600);
00268         $diff -= $hours * 3600;
00269         $minutes = floor($diff / 60);
00270         $diff -= $minutes * 60;
00271         $seconds = $diff;
00272 
00273         if ($months > 0) {
00274             // over a month old, just show date (mm/dd/yyyy format)
00275             $relative_date = 'on ' . date($format, $in_seconds);
00276             $old = true;
00277         } else {
00278             $relative_date = '';
00279             $old = false;
00280 
00281             if ($weeks > 0) {
00282                 // weeks and days
00283                 $relative_date .= ($relative_date ? ', ' : '') . $weeks . ' week' . ($weeks > 1 ? 's' : '');
00284                 $relative_date .= $days > 0 ? ($relative_date ? ', ' : '') . $days . ' day' . ($days > 1 ? 's' : '') : '';
00285             } elseif ($days > 0) {
00286                 // days and hours
00287                 $relative_date .= ($relative_date ? ', ' : '') . $days . ' day' . ($days > 1 ? 's' : '');
00288                 $relative_date .= $hours > 0 ? ($relative_date ? ', ' : '') . $hours . ' hour' . ($hours > 1 ? 's' : '') : '';
00289             } elseif ($hours > 0) {
00290                 // hours and minutes
00291                 $relative_date .= ($relative_date ? ', ' : '') . $hours . ' hour' . ($hours > 1 ? 's' : '');
00292                 $relative_date .= $minutes > 0 ? ($relative_date ? ', ' : '') . $minutes . ' minute' . ($minutes > 1 ? 's' : '') : '';
00293             } elseif ($minutes > 0) {
00294                 // minutes only
00295                 $relative_date .= ($relative_date ? ', ' : '') . $minutes . ' minute' . ($minutes > 1 ? 's' : '');
00296             } else {
00297                 // seconds only
00298                 $relative_date .= ($relative_date ? ', ' : '') . $seconds . ' second' . ($seconds != 1 ? 's' : '');
00299             }
00300         }
00301 
00302         $ret = $relative_date;
00303 
00304         // show relative date and add proper verbiage
00305         if (!$backwards && !$old) {
00306             $ret .= ' ago';
00307         }
00308         return $this->output($ret, $return);
00309     }
00310 /**
00311  * Alias for timeAgoInWords
00312  *
00313  * @param string $date_string Datetime string or Unix timestamp
00314  * @param string $format Default format if timestamp is used in $date_string
00315  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00316  * @return string Relative time string.
00317  * @see Time::timeAgoInWords()
00318  * @access public
00319  */
00320     function relativeTime($datetime_string, $format = 'j/n/y', $return = false) {
00321         $date = strtotime($datetime_string);
00322 
00323         if (strtotime("now") > $date) {
00324             $ret = $this->timeAgoInWords($datetime_string, $format, false);
00325         } else {
00326             $ret = $this->timeAgoInWords($datetime_string, $format, true);
00327         }
00328 
00329         return $this->output($ret, $return);
00330     }
00331 /**
00332  * Returns true if specified datetime was within the interval specified, else false.
00333  *
00334  * @param mixed $timeInterval the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.
00335  * @param mixed $date_string the datestring or unix timestamp to compare
00336  * @param  boolean $return Whether this method should return a value or output it. This overrides AUTO_OUTPUT.
00337  * @return boolean
00338  * @access public
00339  */
00340     function wasWithinLast($timeInterval, $date_string, $return = false) {
00341         $date = $this->fromString($date_string);
00342         $result = preg_split('/\\s/', $timeInterval);
00343         $numInterval = $result[0];
00344         $textInterval = $result[1];
00345         $currentTime = floor(time());
00346         $seconds = ($currentTime - floor($date));
00347 
00348         switch($textInterval) {
00349             case "seconds":
00350             case "second":
00351                 $timePeriod = $seconds;
00352                 $ret = $return;
00353             break;
00354             case "minutes":
00355             case "minute":
00356                 $minutes = floor($seconds / 60);
00357                 $timePeriod = $minutes;
00358             break;
00359             case "hours":
00360             case "hour":
00361                 $hours = floor($seconds / 3600);
00362                 $timePeriod = $hours;
00363             break;
00364             case "days":
00365             case "day":
00366                 $days = floor($seconds / 86400);
00367                 $timePeriod = $days;
00368             break;
00369             case "weeks":
00370             case "week":
00371                 $weeks = floor($seconds / 604800);
00372                 $timePeriod = $weeks;
00373             break;
00374             case "months":
00375             case "month":
00376                 $months = floor($seconds / 2629743.83);
00377                 $timePeriod = $months;
00378             break;
00379             case "years":
00380             case "year":
00381                 $years = floor($seconds / 31556926);
00382                 $timePeriod = $years;
00383             break;
00384             default:
00385                 $days = floor($seconds / 86400);
00386                 $timePeriod = $days;
00387             break;
00388         }
00389         if ($timePeriod <= $numInterval) {
00390                 $ret = true;
00391         } else {
00392                 $ret = false;
00393         }
00394         return $this->output($ret, $return);
00395     }
00396 }
00397 ?>