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 bool|null
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: *
119: * @param string $method Method to call.
120: * @param array $params Parameters to pass to method.
121: * @return mixed Whatever is returned by called method, or false on failure
122: */
123: public function __call($method, $params) {
124: return call_user_func_array(array($this->_engine, $method), $params);
125: }
126:
127: /**
128: * Converts a string representing the format for the function strftime and returns a
129: * Windows safe and i18n aware format.
130: *
131: * @param string $format Format with specifiers for strftime function.
132: * Accepts the special specifier %S which mimics the modifier S for date()
133: * @param string $time UNIX timestamp
134: * @return string Windows safe and date() function compatible format for strftime
135: * @see CakeTime::convertSpecifiers()
136: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
137: */
138: public function convertSpecifiers($format, $time = null) {
139: return $this->_engine->convertSpecifiers($format, $time);
140: }
141:
142: /**
143: * Converts given time (in server's time zone) to user's local time, given his/her timezone.
144: *
145: * @param string $serverTime UNIX timestamp
146: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
147: * @return int UNIX timestamp
148: * @see CakeTime::convert()
149: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
150: */
151: public function convert($serverTime, $timezone) {
152: return $this->_engine->convert($serverTime, $timezone);
153: }
154:
155: /**
156: * Returns server's offset
157: *
158: * @return int Offset
159: * @see CakeTime::serverOffset()
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: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
170: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
171: * @return string Parsed timestamp
172: * @see CakeTime::fromString()
173: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
174: */
175: public function fromString($dateString, $timezone = null) {
176: return $this->_engine->fromString($dateString, $timezone);
177: }
178:
179: /**
180: * Returns a nicely formatted date string for given Datetime string.
181: *
182: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
183: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
184: * @param string $format The format to use. If null, `CakeTime::$niceFormat` is used
185: * @return string Formatted date string
186: * @see CakeTime::nice()
187: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
188: */
189: public function nice($dateString = null, $timezone = null, $format = null) {
190: return $this->_engine->nice($dateString, $timezone, $format);
191: }
192:
193: /**
194: * Returns a formatted descriptive date string for given datetime string.
195: *
196: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime objectp
197: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
198: * @return string Described, relative date string
199: * @see CakeTime::niceShort()
200: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
201: */
202: public function niceShort($dateString = null, $timezone = null) {
203: return $this->_engine->niceShort($dateString, $timezone);
204: }
205:
206: /**
207: * Returns a partial SQL string to search for all records between two dates.
208: *
209: * @param int|string|DateTime $begin UNIX timestamp, strtotime() valid string or DateTime object
210: * @param int|string|DateTime $end UNIX timestamp, strtotime() valid string or DateTime object
211: * @param string $fieldName Name of database field to compare with
212: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
213: * @return string Partial SQL string.
214: * @see CakeTime::daysAsSql()
215: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
216: */
217: public function daysAsSql($begin, $end, $fieldName, $timezone = null) {
218: return $this->_engine->daysAsSql($begin, $end, $fieldName, $timezone);
219: }
220:
221: /**
222: * Returns a partial SQL string to search for all records between two times
223: * occurring on the same day.
224: *
225: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
226: * @param string $fieldName Name of database field to compare with
227: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
228: * @return string Partial SQL string.
229: * @see CakeTime::dayAsSql()
230: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
231: */
232: public function dayAsSql($dateString, $fieldName, $timezone = null) {
233: return $this->_engine->dayAsSql($dateString, $fieldName, $timezone);
234: }
235:
236: /**
237: * Returns true if given datetime string is today.
238: *
239: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
240: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
241: * @return bool True if datetime string is today
242: * @see CakeTime::isToday()
243: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
244: */
245: public function isToday($dateString, $timezone = null) {
246: return $this->_engine->isToday($dateString, $timezone);
247: }
248:
249: /**
250: * Returns true if given datetime string is within this week.
251: *
252: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
253: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
254: * @return bool True if datetime string is within current week
255: * @see CakeTime::isThisWeek()
256: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
257: */
258: public function isThisWeek($dateString, $timezone = null) {
259: return $this->_engine->isThisWeek($dateString, $timezone);
260: }
261:
262: /**
263: * Returns true if given datetime string is within this month
264: *
265: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
266: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
267: * @return bool True if datetime string is within current month
268: * @see CakeTime::isThisMonth()
269: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
270: */
271: public function isThisMonth($dateString, $timezone = null) {
272: return $this->_engine->isThisMonth($dateString, $timezone);
273: }
274:
275: /**
276: * Returns true if given datetime string is within current year.
277: *
278: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
279: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
280: * @return bool True if datetime string is within current year
281: * @see CakeTime::isThisYear()
282: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
283: */
284: public function isThisYear($dateString, $timezone = null) {
285: return $this->_engine->isThisYear($dateString, $timezone);
286: }
287:
288: /**
289: * Returns true if given datetime string was yesterday.
290: *
291: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
292: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
293: * @return bool True if datetime string was yesterday
294: * @see CakeTime::wasYesterday()
295: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
296: */
297: public function wasYesterday($dateString, $timezone = null) {
298: return $this->_engine->wasYesterday($dateString, $timezone);
299: }
300:
301: /**
302: * Returns true if given datetime string is tomorrow.
303: *
304: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
305: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
306: * @return bool True if datetime string was yesterday
307: * @see CakeTime::isTomorrow()
308: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
309: */
310: public function isTomorrow($dateString, $timezone = null) {
311: return $this->_engine->isTomorrow($dateString, $timezone);
312: }
313:
314: /**
315: * Returns the quarter
316: *
317: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
318: * @param bool $range if true returns a range in Y-m-d format
319: * @return int|array 1, 2, 3, or 4 quarter of year or array if $range true
320: * @see CakeTime::toQuarter()
321: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
322: */
323: public function toQuarter($dateString, $range = false) {
324: return $this->_engine->toQuarter($dateString, $range);
325: }
326:
327: /**
328: * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
329: *
330: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
331: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
332: * @return int Unix timestamp
333: * @see CakeTime::toUnix()
334: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
335: */
336: public function toUnix($dateString, $timezone = null) {
337: return $this->_engine->toUnix($dateString, $timezone);
338: }
339:
340: /**
341: * Returns a date formatted for Atom RSS feeds.
342: *
343: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
344: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
345: * @return string Formatted date string
346: * @see CakeTime::toAtom()
347: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
348: */
349: public function toAtom($dateString, $timezone = null) {
350: return $this->_engine->toAtom($dateString, $timezone);
351: }
352:
353: /**
354: * Formats date for RSS feeds
355: *
356: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
357: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
358: * @return string Formatted date string
359: * @see CakeTime::toRSS()
360: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
361: */
362: public function toRSS($dateString, $timezone = null) {
363: return $this->_engine->toRSS($dateString, $timezone);
364: }
365:
366: /**
367: * Formats a date into a phrase expressing the relative time.
368: *
369: * ## Addition options
370: *
371: * - `element` - The element to wrap the formatted time in.
372: * Has a few additional options:
373: * - `tag` - The tag to use, defaults to 'span'.
374: * - `class` - The class name to use, defaults to `time-ago-in-words`.
375: * - `title` - Defaults to the $dateTime input.
376: *
377: * @param int|string|DateTime $dateTime UNIX timestamp, strtotime() valid string or DateTime object
378: * @param array $options Default format if timestamp is used in $dateString
379: * @return string Relative time string.
380: * @see CakeTime::timeAgoInWords()
381: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
382: */
383: public function timeAgoInWords($dateTime, $options = array()) {
384: $element = null;
385:
386: if (!empty($options['element'])) {
387: $element = array(
388: 'tag' => 'span',
389: 'class' => 'time-ago-in-words',
390: 'title' => $dateTime
391: );
392:
393: if (is_array($options['element'])) {
394: $element = $options['element'] + $element;
395: } else {
396: $element['tag'] = $options['element'];
397: }
398: unset($options['element']);
399: }
400: $relativeDate = $this->_engine->timeAgoInWords($dateTime, $options);
401:
402: if ($element) {
403: $relativeDate = sprintf(
404: '<%s%s>%s</%s>',
405: $element['tag'],
406: $this->_parseAttributes($element, array('tag')),
407: $relativeDate,
408: $element['tag']
409: );
410: }
411: return $relativeDate;
412: }
413:
414: /**
415: * Returns true if specified datetime was within the interval specified, else false.
416: *
417: * @param string|int $timeInterval the numeric value with space then time type.
418: * Example of valid types: 6 hours, 2 days, 1 minute.
419: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
420: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
421: * @return bool
422: * @see CakeTime::wasWithinLast()
423: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
424: */
425: public function wasWithinLast($timeInterval, $dateString, $timezone = null) {
426: return $this->_engine->wasWithinLast($timeInterval, $dateString, $timezone);
427: }
428:
429: /**
430: * Returns true if specified datetime is within the interval specified, else false.
431: *
432: * @param string|int $timeInterval the numeric value with space then time type.
433: * Example of valid types: 6 hours, 2 days, 1 minute.
434: * @param int|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
435: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
436: * @return bool
437: * @see CakeTime::isWithinLast()
438: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#testing-time
439: */
440: public function isWithinNext($timeInterval, $dateString, $timezone = null) {
441: return $this->_engine->isWithinNext($timeInterval, $dateString, $timezone);
442: }
443:
444: /**
445: * Returns gmt as a UNIX timestamp.
446: *
447: * @param int|string|DateTime $string UNIX timestamp, strtotime() valid string or DateTime object
448: * @return int UNIX timestamp
449: * @see CakeTime::gmt()
450: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
451: */
452: public function gmt($string = null) {
453: return $this->_engine->gmt($string);
454: }
455:
456: /**
457: * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
458: * This function also accepts a time string and a format string as first and second parameters.
459: * In that case this function behaves as a wrapper for TimeHelper::i18nFormat()
460: *
461: * ## Examples
462: *
463: * Create localized & formatted time:
464: *
465: * ```
466: * $this->Time->format('2012-02-15', '%m-%d-%Y'); // returns 02-15-2012
467: * $this->Time->format('2012-02-15 23:01:01', '%c'); // returns preferred date and time based on configured locale
468: * $this->Time->format('0000-00-00', '%d-%m-%Y', 'N/A'); // return N/A becuase an invalid date was passed
469: * $this->Time->format('2012-02-15 23:01:01', '%c', 'N/A', 'America/New_York'); // converts passed date to timezone
470: * ```
471: *
472: * @param int|string|DateTime $format date format string (or a UNIX timestamp, strtotime() valid string or DateTime object)
473: * @param int|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object (or a date format string)
474: * @param bool $invalid flag to ignore results of fromString == false
475: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
476: * @return string Formatted date string
477: * @see CakeTime::format()
478: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
479: */
480: public function format($format, $date = null, $invalid = false, $timezone = null) {
481: return $this->_engine->format($format, $date, $invalid, $timezone);
482: }
483:
484: /**
485: * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
486: * It takes into account the default date format for the current language if a LC_TIME file is used.
487: *
488: * @param int|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object
489: * @param string $format strftime format string.
490: * @param bool $invalid flag to ignore results of fromString == false
491: * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
492: * @return string Formatted and translated date string
493: * @see CakeTime::i18nFormat()
494: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
495: */
496: public function i18nFormat($date, $format = null, $invalid = false, $timezone = null) {
497: return $this->_engine->i18nFormat($date, $format, $invalid, $timezone);
498: }
499:
500: }
501: