1: <?php
2: /**
3: * Time Helper class file.
4: *
5: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
6: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
7: *
8: * Licensed under The MIT License
9: * For full copyright and license information, please see the LICENSE.txt
10: * Redistributions of files must retain the above copyright notice.
11: *
12: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
13: * @link http://cakephp.org CakePHP(tm) Project
14: * @package Cake.View.Helper
15: * @since CakePHP(tm) v 0.10.0.1076
16: * @license http://www.opensource.org/licenses/mit-license.php MIT License
17: */
18:
19: App::uses('CakeTime', 'Utility');
20: App::uses('Multibyte', 'I18n');
21: App::uses('AppHelper', 'View/Helper');
22:
23: /**
24: * Time Helper class for easy use of time data.
25: *
26: * Manipulation of time data.
27: *
28: * @package Cake.View.Helper
29: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html
30: * @see CakeTime
31: */
32: class TimeHelper extends AppHelper {
33:
34: /**
35: * CakeTime instance
36: *
37: * @var stdClass
38: */
39: protected $_engine = null;
40:
41: /**
42: * Constructor
43: *
44: * ### Settings:
45: *
46: * - `engine` Class name to use to replace CakeTime functionality
47: * The class needs to be placed in the `Utility` directory.
48: *
49: * @param View $View the view object the helper is attached to.
50: * @param array $settings Settings array
51: * @throws CakeException When the engine class could not be found.
52: */
53: public function __construct(View $View, $settings = array()) {
54: $settings = Hash::merge(array('engine' => 'CakeTime'), $settings);
55: parent::__construct($View, $settings);
56: list($plugin, $engineClass) = pluginSplit($settings['engine'], true);
57: App::uses($engineClass, $plugin . 'Utility');
58: if (class_exists($engineClass)) {
59: $this->_engine = new $engineClass($settings);
60: } else {
61: throw new CakeException(__d('cake_dev', '%s could not be found', $engineClass));
62: }
63: }
64:
65: /**
66: * Magic accessor for deprecated attributes.
67: *
68: * @param string $name Name of the attribute to set.
69: * @param string $value Value of the attribute to set.
70: * @return void
71: */
72: public function __set($name, $value) {
73: switch ($name) {
74: case 'niceFormat':
75: $this->_engine->{$name} = $value;
76: break;
77: default:
78: $this->{$name} = $value;
79: }
80: }
81:
82: /**
83: * Magic isset check for deprecated attributes.
84: *
85: * @param string $name Name of the attribute to check.
86: * @return boolean
87: */
88: public function __isset($name) {
89: if (isset($this->{$name})) {
90: return true;
91: }
92: $magicGet = array('niceFormat');
93: if (in_array($name, $magicGet)) {
94: return $this->__get($name) !== null;
95: }
96: return null;
97: }
98:
99: /**
100: * Magic accessor for attributes that were deprecated.
101: *
102: * @param string $name Name of the attribute to get.
103: * @return mixed
104: */
105: public function __get($name) {
106: if (isset($this->_engine->{$name})) {
107: return $this->_engine->{$name};
108: }
109: $magicGet = array('niceFormat');
110: if (in_array($name, $magicGet)) {
111: return $this->_engine->{$name};
112: }
113: return null;
114: }
115:
116: /**
117: * Call methods from CakeTime utility class
118: * @return mixed Whatever is returned by called method, or false on failure
119: */
120: public function __call($method, $params) {
121: return call_user_func_array(array($this->_engine, $method), $params);
122: }
123:
124: /**
125: * Converts a string representing the format for the function strftime and returns a
126: * windows safe and i18n aware format.
127: *
128: * @see CakeTime::convertSpecifiers()
129: *
130: * @param string $format Format with specifiers for strftime function.
131: * Accepts the special specifier %S which mimics the modifier S for date()
132: * @param string $time UNIX timestamp
133: * @return string windows safe and date() function compatible format for strftime
134: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
135: */
136: public function convertSpecifiers($format, $time = null) {
137: return $this->_engine->convertSpecifiers($format, $time);
138: }
139:
140: /**
141: * Converts given time (in server's time zone) to user's local time, given his/her timezone.
142: *
143: * @see CakeTime::convert()
144: *
145: * @param string $serverTime UNIX timestamp
146: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
147: * @return integer UNIX timestamp
148: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
149: */
150: public function convert($serverTime, $timezone) {
151: return $this->_engine->convert($serverTime, $timezone);
152: }
153:
154: /**
155: * Returns server's offset
156: *
157: * @see CakeTime::serverOffset()
158: *
159: * @return integer Offset
160: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
161: */
162: public function serverOffset() {
163: return $this->_engine->serverOffset();
164: }
165:
166: /**
167: * Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
168: *
169: * @see CakeTime::fromString()
170: *
171: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
172: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
173: * @return string Parsed timestamp
174: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
175: */
176: public function fromString($dateString, $timezone = null) {
177: return $this->_engine->fromString($dateString, $timezone);
178: }
179:
180: /**
181: * Returns a nicely formatted date string for given Datetime string.
182: *
183: * @see CakeTime::nice()
184: *
185: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
186: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
187: * @param string $format The format to use. If null, `CakeTime::$niceFormat` is used
188: * @return string Formatted date string
189: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
190: */
191: public function nice($dateString = null, $timezone = null, $format = null) {
192: return $this->_engine->nice($dateString, $timezone, $format);
193: }
194:
195: /**
196: * Returns a formatted descriptive date string for given datetime string.
197: *
198: * @see CakeTime::niceShort()
199: *
200: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime objectp
201: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
202: * @return string Described, relative date string
203: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
204: */
205: public function niceShort($dateString = null, $timezone = null) {
206: return $this->_engine->niceShort($dateString, $timezone);
207: }
208:
209: /**
210: * Returns a partial SQL string to search for all records between two dates.
211: *
212: * @see CakeTime::daysAsSql()
213: *
214: * @param integer|string|DateTime $begin UNIX timestamp, strtotime() valid string or DateTime object
215: * @param integer|string|DateTime $end UNIX timestamp, strtotime() valid string or DateTime object
216: * @param string $fieldName Name of database field to compare with
217: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
218: * @return string Partial SQL string.
219: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
220: */
221: public function daysAsSql($begin, $end, $fieldName, $timezone = null) {
222: return $this->_engine->daysAsSql($begin, $end, $fieldName, $timezone);
223: }
224:
225: /**
226: * Returns a partial SQL string to search for all records between two times
227: * occurring on the same day.
228: *
229: * @see CakeTime::dayAsSql()
230: *
231: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
232: * @param string $fieldName Name of database field to compare with
233: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
234: * @return string Partial SQL string.
235: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
236: */
237: public function dayAsSql($dateString, $fieldName, $timezone = null) {
238: return $this->_engine->dayAsSql($dateString, $fieldName, $timezone);
239: }
240:
241: /**
242: * Returns true if given datetime string is today.
243: *
244: * @see CakeTime::isToday()
245: *
246: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
247: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
248: * @return boolean True if datetime string is today
249: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
250: */
251: public function isToday($dateString, $timezone = null) {
252: return $this->_engine->isToday($dateString, $timezone);
253: }
254:
255: /**
256: * Returns true if given datetime string is within this week.
257: *
258: * @see CakeTime::isThisWeek()
259: *
260: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
261: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
262: * @return boolean True if datetime string is within current week
263: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
264: */
265: public function isThisWeek($dateString, $timezone = null) {
266: return $this->_engine->isThisWeek($dateString, $timezone);
267: }
268:
269: /**
270: * Returns true if given datetime string is within this month
271: *
272: * @see CakeTime::isThisMonth()
273: *
274: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
275: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
276: * @return boolean True if datetime string is within current month
277: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
278: */
279: public function isThisMonth($dateString, $timezone = null) {
280: return $this->_engine->isThisMonth($dateString, $timezone);
281: }
282:
283: /**
284: * Returns true if given datetime string is within current year.
285: *
286: * @see CakeTime::isThisYear()
287: *
288: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
289: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
290: * @return boolean True if datetime string is within current year
291: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
292: */
293: public function isThisYear($dateString, $timezone = null) {
294: return $this->_engine->isThisYear($dateString, $timezone);
295: }
296:
297: /**
298: * Returns true if given datetime string was yesterday.
299: *
300: * @see CakeTime::wasYesterday()
301: *
302: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
303: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
304: * @return boolean True if datetime string was yesterday
305: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
306: *
307: */
308: public function wasYesterday($dateString, $timezone = null) {
309: return $this->_engine->wasYesterday($dateString, $timezone);
310: }
311:
312: /**
313: * Returns true if given datetime string is tomorrow.
314: *
315: * @see CakeTime::isTomorrow()
316: *
317: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
318: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
319: * @return boolean True if datetime string was yesterday
320: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
321: */
322: public function isTomorrow($dateString, $timezone = null) {
323: return $this->_engine->isTomorrow($dateString, $timezone);
324: }
325:
326: /**
327: * Returns the quarter
328: *
329: * @see CakeTime::toQuarter()
330: *
331: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
332: * @param boolean $range if true returns a range in Y-m-d format
333: * @return mixed 1, 2, 3, or 4 quarter of year or array if $range true
334: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
335: */
336: public function toQuarter($dateString, $range = false) {
337: return $this->_engine->toQuarter($dateString, $range);
338: }
339:
340: /**
341: * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
342: *
343: * @see CakeTime::toUnix()
344: *
345: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
346: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
347: * @return integer Unix timestamp
348: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
349: */
350: public function toUnix($dateString, $timezone = null) {
351: return $this->_engine->toUnix($dateString, $timezone);
352: }
353:
354: /**
355: * Returns a date formatted for Atom RSS feeds.
356: *
357: * @see CakeTime::toAtom()
358: *
359: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
360: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
361: * @return string Formatted date string
362: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
363: */
364: public function toAtom($dateString, $timezone = null) {
365: return $this->_engine->toAtom($dateString, $timezone);
366: }
367:
368: /**
369: * Formats date for RSS feeds
370: *
371: * @see CakeTime::toRSS()
372: *
373: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
374: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
375: * @return string Formatted date string
376: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
377: */
378: public function toRSS($dateString, $timezone = null) {
379: return $this->_engine->toRSS($dateString, $timezone);
380: }
381:
382: /**
383: * Formats date for RSS feeds
384: *
385: * @see CakeTime::timeAgoInWords()
386: *
387: * ## Addition options
388: *
389: * - `element` - The element to wrap the formatted time in.
390: * Has a few additional options:
391: * - `tag` - The tag to use, defaults to 'span'.
392: * - `class` - The class name to use, defaults to `time-ago-in-words`.
393: * - `title` - Defaults to the $dateTime input.
394: *
395: * @param integer|string|DateTime $dateTime UNIX timestamp, strtotime() valid string or DateTime object
396: * @param array $options Default format if timestamp is used in $dateString
397: * @return string Relative time string.
398: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
399: */
400: public function timeAgoInWords($dateTime, $options = array()) {
401: $element = null;
402:
403: if (!empty($options['element'])) {
404: $element = array(
405: 'tag' => 'span',
406: 'class' => 'time-ago-in-words',
407: 'title' => $dateTime
408: );
409:
410: if (is_array($options['element'])) {
411: $element = array_merge($element, $options['element']);
412: } else {
413: $element['tag'] = $options['element'];
414: }
415: unset($options['element']);
416: }
417: $relativeDate = $this->_engine->timeAgoInWords($dateTime, $options);
418:
419: if ($element) {
420: $relativeDate = sprintf(
421: '<%s%s>%s</%s>',
422: $element['tag'],
423: $this->_parseAttributes($element, array('tag')),
424: $relativeDate,
425: $element['tag']
426: );
427: }
428: return $relativeDate;
429: }
430:
431: /**
432: * Returns true if specified datetime was within the interval specified, else false.
433: *
434: * @see CakeTime::wasWithinLast()
435: *
436: * @param string|integer $timeInterval the numeric value with space then time type.
437: * Example of valid types: 6 hours, 2 days, 1 minute.
438: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
439: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
440: * @return boolean
441: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
442: */
443: public function wasWithinLast($timeInterval, $dateString, $timezone = null) {
444: return $this->_engine->wasWithinLast($timeInterval, $dateString, $timezone);
445: }
446:
447: /**
448: * Returns true if specified datetime is within the interval specified, else false.
449: *
450: * @see CakeTime::isWithinLast()
451: *
452: * @param string|integer $timeInterval the numeric value with space then time type.
453: * Example of valid types: 6 hours, 2 days, 1 minute.
454: * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
455: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
456: * @return boolean
457: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
458: */
459: public function isWithinNext($timeInterval, $dateString, $timezone = null) {
460: return $this->_engine->isWithinNext($timeInterval, $dateString, $timezone);
461: }
462:
463: /**
464: * Returns gmt as a UNIX timestamp.
465: *
466: * @see CakeTime::gmt()
467: *
468: * @param integer|string|DateTime $string UNIX timestamp, strtotime() valid string or DateTime object
469: * @return integer UNIX timestamp
470: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
471: */
472: public function gmt($string = null) {
473: return $this->_engine->gmt($string);
474: }
475:
476: /**
477: * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
478: * This function also accepts a time string and a format string as first and second parameters.
479: * In that case this function behaves as a wrapper for TimeHelper::i18nFormat()
480: *
481: * ## Examples
482: *
483: * Create localized & formatted time:
484: *
485: * {{{
486: * $this->Time->format('2012-02-15', '%m-%d-%Y'); // returns 02-15-2012
487: * $this->Time->format('2012-02-15 23:01:01', '%c'); // returns preferred date and time based on configured locale
488: * $this->Time->format('0000-00-00', '%d-%m-%Y', 'N/A'); // return N/A becuase an invalid date was passed
489: * $this->Time->format('2012-02-15 23:01:01', '%c', 'N/A', 'America/New_York'); // converts passed date to timezone
490: * }}}
491: *
492: * @see CakeTime::format()
493: *
494: * @param integer|string|DateTime $format date format string (or a UNIX timestamp, strtotime() valid string or DateTime object)
495: * @param integer|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object (or a date format string)
496: * @param boolean $invalid flag to ignore results of fromString == false
497: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
498: * @return string Formatted date string
499: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
500: */
501: public function format($format, $date = null, $invalid = false, $timezone = null) {
502: return $this->_engine->format($format, $date, $invalid, $timezone);
503: }
504:
505: /**
506: * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
507: * It takes into account the default date format for the current language if a LC_TIME file is used.
508: *
509: * @see CakeTime::i18nFormat()
510: *
511: * @param integer|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object
512: * @param string $format strftime format string.
513: * @param boolean $invalid flag to ignore results of fromString == false
514: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
515: * @return string Formatted and translated date string
516: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
517: */
518: public function i18nFormat($date, $format = null, $invalid = false, $timezone = null) {
519: return $this->_engine->i18nFormat($date, $format, $invalid, $timezone);
520: }
521:
522: }
523: