1: <?php
  2: /* SVN FILE: $Id$ */
  3: /**
  4:  * Time Helper class file.
  5:  *
  6:  * PHP versions 4 and 5
  7:  *
  8:  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  9:  * Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
 10:  *
 11:  * Licensed under The MIT License
 12:  * Redistributions of files must retain the above copyright notice.
 13:  *
 14:  * @copyright     Copyright 2005-2012, Cake Software Foundation, Inc. (http://cakefoundation.org)
 15:  * @link          http://cakephp.org CakePHP(tm) Project
 16:  * @package       cake
 17:  * @subpackage    cake.cake.libs.view.helpers
 18:  * @since         CakePHP(tm) v 0.10.0.1076
 19:  * @version       $Revision$
 20:  * @modifiedby    $LastChangedBy$
 21:  * @lastmodified  $Date$
 22:  * @license       http://www.opensource.org/licenses/mit-license.php The MIT License
 23:  */
 24: /**
 25:  * Time Helper class for easy use of time data.
 26:  *
 27:  * Manipulation of time data.
 28:  *
 29:  * @package       cake
 30:  * @subpackage    cake.cake.libs.view.helpers
 31:  */
 32: class TimeHelper extends AppHelper {
 33: /**
 34:  * Converts given time (in server's time zone) to user's local time, given his/her offset from GMT.
 35:  *
 36:  * @param string $serverTime UNIX timestamp
 37:  * @param int $userOffset User's offset from GMT (in hours)
 38:  * @return string UNIX timestamp
 39:  */
 40:     function convert($serverTime, $userOffset) {
 41:         $serverOffset = $this->serverOffset();
 42:         $gmtTime = $serverTime - $serverOffset;
 43:         $userTime = $gmtTime + $userOffset * (60*60);
 44:         return $userTime;
 45:     }
 46: /**
 47:  * Returns server's offset from GMT in seconds.
 48:  *
 49:  * @return int Offset
 50:  */
 51:     function serverOffset() {
 52:         return date('Z', time());
 53:     }
 54: /**
 55:  * Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
 56:  *
 57:  * @param string $dateString Datetime string
 58:  * @param int $userOffset User's offset from GMT (in hours)
 59:  * @return string Parsed timestamp
 60:  */
 61:     function fromString($dateString, $userOffset = null) {
 62:         if (empty($dateString)) {
 63:             return false;
 64:         }
 65:         if (is_int($dateString) || is_numeric($dateString)) {
 66:             $date = intval($dateString);
 67:         } else {
 68:             $date = strtotime($dateString);
 69:         }
 70:         if ($userOffset !== null) {
 71:             return $this->convert($date, $userOffset);
 72:         }
 73:         return $date;
 74:     }
 75: /**
 76:  * Returns a nicely formatted date string for given Datetime string.
 77:  *
 78:  * @param string $dateString Datetime string or Unix timestamp
 79:  * @param int $userOffset User's offset from GMT (in hours)
 80:  * @return string Formatted date string
 81:  */
 82:     function nice($dateString = null, $userOffset = null) {
 83:         if ($dateString != null) {
 84:             $date = $this->fromString($dateString, $userOffset);
 85:         } else {
 86:             $date = time();
 87:         }
 88: 
 89:         $ret = date("D, M jS Y, H:i", $date);
 90:         return $this->output($ret);
 91:     }
 92: /**
 93:  * Returns a formatted descriptive date string for given datetime string.
 94:  *
 95:  * If the given date is today, the returned string could be "Today, 16:54".
 96:  * If the given date was yesterday, the returned string could be "Yesterday, 16:54".
 97:  * If $dateString's year is the current year, the returned string does not
 98:  * include mention of the year.
 99:  *
100:  * @param string $dateString Datetime string or Unix timestamp
101:  * @param int $userOffset User's offset from GMT (in hours)
102:  * @return string Described, relative date string
103:  */
104:     function niceShort($dateString = null, $userOffset = null) {
105:         $date = $dateString ? $this->fromString($dateString, $userOffset) : time();
106: 
107:         $y = $this->isThisYear($date) ? '' : ' Y';
108: 
109:         if ($this->isToday($dateString, $userOffset)) {
110:             $ret = sprintf(__('Today, %s',true), date("H:i", $date));
111:         } elseif ($this->wasYesterday($dateString, $userOffset)) {
112:             $ret = sprintf(__('Yesterday, %s',true), date("H:i", $date));
113:         } else {
114:             $ret = date("M jS{$y}, H:i", $date);
115:         }
116: 
117:         return $this->output($ret);
118:     }
119: /**
120:  * Returns a partial SQL string to search for all records between two dates.
121:  *
122:  * @param string $dateString Datetime string or Unix timestamp
123:  * @param string $end Datetime string or Unix timestamp
124:  * @param string $fieldName Name of database field to compare with
125:  * @param int $userOffset User's offset from GMT (in hours)
126:  * @return string Partial SQL string.
127:  */
128:     function daysAsSql($begin, $end, $fieldName, $userOffset = null) {
129:         $begin = $this->fromString($begin, $userOffset);
130:         $end = $this->fromString($end, $userOffset);
131:         $begin = date('Y-m-d', $begin) . ' 00:00:00';
132:         $end = date('Y-m-d', $end) . ' 23:59:59';
133: 
134:         $ret  ="($fieldName >= '$begin') AND ($fieldName <= '$end')";
135:         return $this->output($ret);
136:     }
137: /**
138:  * Returns a partial SQL string to search for all records between two times
139:  * occurring on the same day.
140:  *
141:  * @param string $dateString Datetime string or Unix timestamp
142:  * @param string $fieldName Name of database field to compare with
143:  * @param int $userOffset User's offset from GMT (in hours)
144:  * @return string Partial SQL string.
145:  */
146:     function dayAsSql($dateString, $fieldName, $userOffset = null) {
147:         $date = $this->fromString($dateString, $userOffset);
148:         $ret = $this->daysAsSql($dateString, $dateString, $fieldName);
149:         return $this->output($ret);
150:     }
151: /**
152:  * Returns true if given datetime string is today.
153:  *
154:  * @param string $dateString Datetime string or Unix timestamp
155:  * @param int $userOffset User's offset from GMT (in hours)
156:  * @return boolean True if datetime string is today
157:  */
158:     function isToday($dateString, $userOffset = null) {
159:         $date = $this->fromString($dateString, $userOffset);
160:         return date('Y-m-d', $date) == date('Y-m-d', time());
161:     }
162: /**
163:  * Returns true if given datetime string is within this week
164:  * @param string $dateString
165:  * @param int $userOffset User's offset from GMT (in hours)
166:  * @return boolean True if datetime string is within current week
167:  */
168:     function isThisWeek($dateString, $userOffset = null) {
169:         $date = $this->fromString($dateString, $userOffset);
170:         return date('W Y', $date) == date('W Y', time());
171:     }
172: /**
173:  * Returns true if given datetime string is within this month
174:  * @param string $dateString
175:  * @param int $userOffset User's offset from GMT (in hours)
176:  * @return boolean True if datetime string is within current month
177:  */
178:     function isThisMonth($dateString, $userOffset = null) {
179:         $date = $this->fromString($dateString);
180:         return date('m Y',$date) == date('m Y', time());
181:     }
182: /**
183:  * Returns true if given datetime string is within current year.
184:  *
185:  * @param string $dateString Datetime string or Unix timestamp
186:  * @return boolean True if datetime string is within current year
187:  */
188:     function isThisYear($dateString, $userOffset = null) {
189:         $date = $this->fromString($dateString, $userOffset);
190:         return  date('Y', $date) == date('Y', time());
191:     }
192: /**
193:  * Returns true if given datetime string was yesterday.
194:  *
195:  * @param string $dateString Datetime string or Unix timestamp
196:  * @param int $userOffset User's offset from GMT (in hours)
197:  * @return boolean True if datetime string was yesterday
198:  */
199:     function wasYesterday($dateString, $userOffset = null) {
200:         $date = $this->fromString($dateString, $userOffset);
201:         return date('Y-m-d', $date) == date('Y-m-d', strtotime('yesterday'));
202:     }
203: /**
204:  * Returns true if given datetime string is tomorrow.
205:  *
206:  * @param string $dateString Datetime string or Unix timestamp
207:  * @param int $userOffset User's offset from GMT (in hours)
208:  * @return boolean True if datetime string was yesterday
209:  */
210:     function isTomorrow($dateString, $userOffset = null) {
211:         $date = $this->fromString($dateString, $userOffset);
212:         return date('Y-m-d', $date) == date('Y-m-d', strtotime('tomorrow'));
213:     }
214: /**
215:  * Returns the quart
216:  * @param string $dateString
217:  * @param boolean $range if true returns a range in Y-m-d format
218:  * @return boolean True if datetime string is within current week
219:  */
220:     function toQuarter($dateString, $range = false) {
221:         $time = $this->fromString($dateString);
222:         $date = ceil(date('m', $time) / 3);
223: 
224:         if ($range === true) {
225:             $range = 'Y-m-d';
226:         }
227: 
228:         if ($range !== false) {
229:             $year = date('Y', $time);
230: 
231:             switch ($date) {
232:                 case 1:
233:                     $date = array($year.'-01-01', $year.'-03-31');
234:                     break;
235:                 case 2:
236:                     $date = array($year.'-04-01', $year.'-06-30');
237:                     break;
238:                 case 3:
239:                     $date = array($year.'-07-01', $year.'-09-30');
240:                     break;
241:                 case 4:
242:                     $date = array($year.'-10-01', $year.'-12-31');
243:                     break;
244:             }
245:         }
246:         return $this->output($date);
247:     }
248: /**
249:  * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
250:  *
251:  * @param string $dateString Datetime string to be represented as a Unix timestamp
252:  * @param int $userOffset User's offset from GMT (in hours)
253:  * @return integer Unix timestamp
254:  */
255:     function toUnix($dateString, $userOffset = null) {
256:         $ret = $this->fromString($dateString, $userOffset);
257:         return $this->output($ret);
258:     }
259: /**
260:  * Returns a date formatted for Atom RSS feeds.
261:  *
262:  * @param string $dateString Datetime string or Unix timestamp
263:  * @param int $userOffset User's offset from GMT (in hours)
264:  * @return string Formatted date string
265:  */
266:     function toAtom($dateString, $userOffset = null) {
267:         $date = $this->fromString($dateString, $userOffset);
268:         $ret = date('Y-m-d\TH:i:s\Z', $date);
269:         return $this->output($ret);
270:     }
271: /**
272:  * Formats date for RSS feeds
273:  *
274:  * @param string $dateString Datetime string or Unix timestamp
275:  * @param int $userOffset User's offset from GMT (in hours)
276:  * @return string Formatted date string
277:  */
278:     function toRSS($dateString, $userOffset = null) {
279:         $date = $this->fromString($dateString, $userOffset);
280:         $ret = date("r", $date);
281:         return $this->output($ret);
282:     }
283: /**
284:  * Returns either a relative date or a formatted date depending
285:  * on the difference between the current time and given datetime.
286:  * $datetime should be in a <i>strtotime</i> - parsable format, like MySQL's datetime datatype.
287:  *
288:  * Options:
289:  *
290:  * - 'format' => a fall back format if the relative time is longer than the duration specified by end
291:  * - 'end' => The end of relative time telling
292:  * - 'userOffset' => Users offset from GMT (in hours)
293:  *
294:  * Relative dates look something like this:
295:  *  3 weeks, 4 days ago
296:  *  15 seconds ago
297:  *
298:  * Default date formatting is d/m/yy e.g: on 18/2/09
299:  *
300:  * The returned string includes 'ago' or 'on' and assumes you'll properly add a word
301:  * like 'Posted ' before the function output.
302:  *
303:  * @param string $dateString Datetime string or Unix timestamp
304:  * @param array $options Default format if timestamp is used in $dateString
305:  * @return string Relative time string.
306:  */
307:     function timeAgoInWords($dateTime, $options = array()) {
308:         $userOffset = null;
309:         if (is_array($options) && isset($options['userOffset'])) {
310:             $userOffset = $options['userOffset'];
311:         }
312:         $now = time();
313:         if (!is_null($userOffset)) {
314:             $now =  $this->convert(time(), $userOffset);
315:         }
316:         $inSeconds = $this->fromString($dateTime, $userOffset);
317:         $backwards = ($inSeconds > $now);
318: 
319:         $format = 'j/n/y';
320:         $end = '+1 month';
321: 
322:         if (is_array($options)) {
323:             if (isset($options['format'])) {
324:                 $format = $options['format'];
325:                 unset($options['format']);
326:             }
327:             if (isset($options['end'])) {
328:                 $end = $options['end'];
329:                 unset($options['end']);
330:             }
331:         } else {
332:             $format = $options;
333:         }
334: 
335:         if ($backwards) {
336:             $futureTime = $inSeconds;
337:             $pastTime = $now;
338:         } else {
339:             $futureTime = $now;
340:             $pastTime = $inSeconds;
341:         }
342:         $diff = $futureTime - $pastTime;
343: 
344:         // If more than a week, then take into account the length of months
345:         if ($diff >= 604800) {
346:             $current = array();
347:             $date = array();
348: 
349:             list($future['H'], $future['i'], $future['s'], $future['d'], $future['m'], $future['Y']) = explode('/', date('H/i/s/d/m/Y', $futureTime));
350: 
351:             list($past['H'], $past['i'], $past['s'], $past['d'], $past['m'], $past['Y']) = explode('/', date('H/i/s/d/m/Y', $pastTime));
352:             $years = $months = $weeks = $days = $hours = $minutes = $seconds = 0;
353: 
354:             if ($future['Y'] == $past['Y'] && $future['m'] == $past['m']) {
355:                 $months = 0;
356:                 $years = 0;
357:             } else {
358:                 if ($future['Y'] == $past['Y']) {
359:                     $months = $future['m'] - $past['m'];
360:                 } else {
361:                     $years = $future['Y'] - $past['Y'];
362:                     $months = $future['m'] + ((12 * $years) - $past['m']);
363: 
364:                     if ($months >= 12) {
365:                         $years = floor($months / 12);
366:                         $months = $months - ($years * 12);
367:                     }
368: 
369:                     if ($future['m'] < $past['m'] && $future['Y'] - $past['Y'] == 1) {
370:                         $years --;
371:                     }
372:                 }
373:             }
374: 
375:             if ($future['d'] >= $past['d']) {
376:                 $days = $future['d'] - $past['d'];
377:             } else {
378:                 $daysInPastMonth = date('t', $pastTime);
379:                 $daysInFutureMonth = date('t', mktime(0, 0, 0, $future['m'] - 1, 1, $future['Y']));
380: 
381:                 if (!$backwards) {
382:                     $days = ($daysInPastMonth - $past['d']) + $future['d'];
383:                 } else {
384:                     $days = ($daysInFutureMonth - $past['d']) + $future['d'];
385:                 }
386: 
387:                 if ($future['m'] != $past['m']) {
388:                     $months --;
389:                 }
390:             }
391: 
392:             if ($months == 0 && $years >= 1 && $diff < ($years * 31536000)) {
393:                 $months = 11;
394:                 $years --;
395:             }
396: 
397:             if ($months >= 12) {
398:                 $years = $years + 1;
399:                 $months = $months - 12;
400:             }
401: 
402:             if ($days >= 7) {
403:                 $weeks = floor($days / 7);
404:                 $days = $days - ($weeks * 7);
405:             }
406:         } else {
407:             $years = $months = $weeks = 0;
408:             $days = floor($diff / 86400);
409: 
410:             $diff = $diff - ($days * 86400);
411: 
412:             $hours = floor($diff / 3600);
413:             $diff = $diff - ($hours * 3600);
414: 
415:             $minutes = floor($diff / 60);
416:             $diff = $diff - ($minutes * 60);
417:             $seconds = $diff;
418:         }
419:         $relativeDate = '';
420:         $diff = $futureTime - $pastTime;
421: 
422:         if ($diff > abs($now - $this->fromString($end))) {
423:             $relativeDate = sprintf(__('on %s',true), date($format, $inSeconds));
424:         } else {
425:             if ($years > 0) {
426:                 // years and months and days
427:                 $relativeDate .= ($relativeDate ? ', ' : '') . $years . ' ' . __n('year', 'years', $years, true);
428:                 $relativeDate .= $months > 0 ? ($relativeDate ? ', ' : '') . $months . ' ' . __n('month', 'months', $months, true) : '';
429:                 $relativeDate .= $weeks > 0 ? ($relativeDate ? ', ' : '') . $weeks . ' ' . __n('week', 'weeks', $weeks, true) : '';
430:                 $relativeDate .= $days > 0 ? ($relativeDate ? ', ' : '') . $days . ' ' . __n('day', 'days', $days, true) : '';
431:             } elseif (abs($months) > 0) {
432:                 // months, weeks and days
433:                 $relativeDate .= ($relativeDate ? ', ' : '') . $months . ' ' . __n('month', 'months', $months, true);
434:                 $relativeDate .= $weeks > 0 ? ($relativeDate ? ', ' : '') . $weeks . ' ' . __n('week', 'weeks', $weeks, true) : '';
435:                 $relativeDate .= $days > 0 ? ($relativeDate ? ', ' : '') . $days . ' ' . __n('day', 'days', $days, true) : '';
436:             } elseif (abs($weeks) > 0) {
437:                 // weeks and days
438:                 $relativeDate .= ($relativeDate ? ', ' : '') . $weeks . ' ' . __n('week', 'weeks', $weeks, true);
439:                 $relativeDate .= $days > 0 ? ($relativeDate ? ', ' : '') . $days . ' ' . __n('day', 'days', $days, true) : '';
440:             } elseif (abs($days) > 0) {
441:                 // days and hours
442:                 $relativeDate .= ($relativeDate ? ', ' : '') . $days . ' ' . __n('day', 'days', $days, true);
443:                 $relativeDate .= $hours > 0 ? ($relativeDate ? ', ' : '') . $hours . ' ' . __n('hour', 'hours', $hours, true) : '';
444:             } elseif (abs($hours) > 0) {
445:                 // hours and minutes
446:                 $relativeDate .= ($relativeDate ? ', ' : '') . $hours . ' ' . __n('hour', 'hours', $hours, true);
447:                 $relativeDate .= $minutes > 0 ? ($relativeDate ? ', ' : '') . $minutes . ' ' . __n('minute', 'minutes', $minutes, true) : '';
448:             } elseif (abs($minutes) > 0) {
449:                 // minutes only
450:                 $relativeDate .= ($relativeDate ? ', ' : '') . $minutes . ' ' . __n('minute', 'minutes', $minutes, true);
451:             } else {
452:                 // seconds only
453:                 $relativeDate .= ($relativeDate ? ', ' : '') . $seconds . ' ' . __n('second', 'seconds', $seconds, true);
454:             }
455: 
456:             if (!$backwards) {
457:                 $relativeDate = sprintf(__('%s ago', true), $relativeDate);
458:             }
459:         }
460:         return $this->output($relativeDate);
461:     }
462: /**
463:  * Alias for timeAgoInWords
464:  *
465:  * @param mixed $dateTime Datetime string (strtotime-compatible) or Unix timestamp
466:  * @param mixed $options Default format string, if timestamp is used in $dateTime, or an array of options to be passed
467:  *   on to timeAgoInWords().
468:  * @return string Relative time string.
469:  * @see     TimeHelper::timeAgoInWords
470:  */
471:     function relativeTime($dateTime, $options = array()) {
472:         return $this->timeAgoInWords($dateTime, $options);
473:     }
474: /**
475:  * Returns true if specified datetime was within the interval specified, else false.
476:  *
477:  * @param mixed $timeInterval the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.
478:  * @param mixed $dateString the datestring or unix timestamp to compare
479:  * @param int $userOffset User's offset from GMT (in hours)
480:  * @return bool
481:  */
482:     function wasWithinLast($timeInterval, $dateString, $userOffset = null) {
483:         $tmp = str_replace(' ', '', $timeInterval);
484:         if (is_numeric($tmp)) {
485:             $timeInterval = $tmp . ' ' . __('days', true);
486:         }
487: 
488:         $date = $this->fromString($dateString, $userOffset);
489:         $interval = $this->fromString('-'.$timeInterval);
490: 
491:         if ($date >= $interval && $date <= time()) {
492:             return true;
493:         }
494: 
495:         return false;
496:     }
497: /**
498:  * Returns gmt, given either a UNIX timestamp or a valid strtotime() date string.
499:  *
500:  * @param string $dateString Datetime string
501:  * @return string Formatted date string
502:  */
503:     function gmt($string = null) {
504:         if ($string != null) {
505:             $string = $this->fromString($string);
506:         } else {
507:             $string = time();
508:         }
509:         $string = $this->fromString($string);
510:         $hour = intval(date("G", $string));
511:         $minute = intval(date("i", $string));
512:         $second = intval(date("s", $string));
513:         $month = intval(date("n", $string));
514:         $day = intval(date("j", $string));
515:         $year = intval(date("Y", $string));
516: 
517:         $return = gmmktime($hour, $minute, $second, $month, $day, $year);
518:         return $return;
519:     }
520: /**
521:  * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
522:  *
523:  * @param string $format date format string. defaults to 'd-m-Y'
524:  * @param string $dateString Datetime string
525:  * @param boolean $invalid flag to ignore results of fromString == false
526:  * @param int $userOffset User's offset from GMT (in hours)
527:  * @return string Formatted date string
528:  */
529:     function format($format = 'd-m-Y', $date, $invalid = false, $userOffset = null) {
530:         $date = $this->fromString($date, $userOffset);
531:         if ($date === false && $invalid !== false) {
532:             return $invalid;
533:         }
534:         return date($format, $date);
535:     }
536: }
537: ?>