1: <?php
  2: /**
  3:  * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
  4:  * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
  5:  *
  6:  * Licensed under The MIT License
  7:  * For full copyright and license information, please see the LICENSE.txt
  8:  * Redistributions of files must retain the above copyright notice.
  9:  *
 10:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 11:  * @link          https://cakephp.org CakePHP(tm) Project
 12:  * @since         3.2.0
 13:  * @license       https://opensource.org/licenses/mit-license.php MIT License
 14:  */
 15: namespace Cake\I18n;
 16: 
 17: use Cake\Chronos\MutableDate;
 18: use IntlDateFormatter;
 19: use JsonSerializable;
 20: 
 21: /**
 22:  * Extends the Date class provided by Chronos.
 23:  *
 24:  * Adds handy methods and locale-aware formatting helpers
 25:  */
 26: class Date extends MutableDate implements JsonSerializable
 27: {
 28:     use DateFormatTrait;
 29: 
 30:     /**
 31:      * The format to use when formatting a time using `Cake\I18n\Date::i18nFormat()`
 32:      * and `__toString`. This format is also used by `parseDateTime()`.
 33:      *
 34:      * The format should be either the formatting constants from IntlDateFormatter as
 35:      * described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern
 36:      * as specified in (http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details)
 37:      *
 38:      * It is possible to provide an array of 2 constants. In this case, the first position
 39:      * will be used for formatting the date part of the object and the second position
 40:      * will be used to format the time part.
 41:      *
 42:      * @var string|array|int
 43:      * @see \Cake\I18n\DateFormatTrait::i18nFormat()
 44:      */
 45:     protected static $_toStringFormat = [IntlDateFormatter::SHORT, -1];
 46: 
 47:     /**
 48:      * The format to use when formatting a time using `Cake\I18n\Date::timeAgoInWords()`
 49:      * and the difference is more than `Cake\I18n\Date::$wordEnd`
 50:      *
 51:      * @var string|array|int
 52:      * @see \Cake\I18n\DateFormatTrait::parseDate()
 53:      */
 54:     public static $wordFormat = [IntlDateFormatter::SHORT, -1];
 55: 
 56:     /**
 57:      * The format to use when formatting a time using `Cake\I18n\Date::nice()`
 58:      *
 59:      * The format should be either the formatting constants from IntlDateFormatter as
 60:      * described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern
 61:      * as specified in (http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details)
 62:      *
 63:      * It is possible to provide an array of 2 constants. In this case, the first position
 64:      * will be used for formatting the date part of the object and the second position
 65:      * will be used to format the time part.
 66:      *
 67:      * @var string|array|int
 68:      * @see \Cake\I18n\DateFormatTrait::nice()
 69:      */
 70:     public static $niceFormat = [IntlDateFormatter::MEDIUM, -1];
 71: 
 72:     /**
 73:      * The format to use when formatting a time using `Date::timeAgoInWords()`
 74:      * and the difference is less than `Date::$wordEnd`
 75:      *
 76:      * @var string[]
 77:      * @see \Cake\I18n\Date::timeAgoInWords()
 78:      */
 79:     public static $wordAccuracy = [
 80:         'year' => 'day',
 81:         'month' => 'day',
 82:         'week' => 'day',
 83:         'day' => 'day',
 84:         'hour' => 'day',
 85:         'minute' => 'day',
 86:         'second' => 'day',
 87:     ];
 88: 
 89:     /**
 90:      * The end of relative time telling
 91:      *
 92:      * @var string
 93:      * @see \Cake\I18n\Date::timeAgoInWords()
 94:      */
 95:     public static $wordEnd = '+1 month';
 96: 
 97:     /**
 98:      * Returns either a relative or a formatted absolute date depending
 99:      * on the difference between the current date and this object.
100:      *
101:      * ### Options:
102:      *
103:      * - `from` => another Date object representing the "now" date
104:      * - `format` => a fall back format if the relative time is longer than the duration specified by end
105:      * - `accuracy` => Specifies how accurate the date should be described (array)
106:      *    - year =>   The format if years > 0   (default "day")
107:      *    - month =>  The format if months > 0  (default "day")
108:      *    - week =>   The format if weeks > 0   (default "day")
109:      *    - day =>    The format if weeks > 0   (default "day")
110:      * - `end` => The end of relative date telling
111:      * - `relativeString` => The printf compatible string when outputting relative date
112:      * - `absoluteString` => The printf compatible string when outputting absolute date
113:      * - `timezone` => The user timezone the timestamp should be formatted in.
114:      *
115:      * Relative dates look something like this:
116:      *
117:      * - 3 weeks, 4 days ago
118:      * - 1 day ago
119:      *
120:      * Default date formatting is d/M/YY e.g: on 18/2/09. Formatting is done internally using
121:      * `i18nFormat`, see the method for the valid formatting strings.
122:      *
123:      * The returned string includes 'ago' or 'on' and assumes you'll properly add a word
124:      * like 'Posted ' before the function output.
125:      *
126:      * NOTE: If the difference is one week or more, the lowest level of accuracy is day.
127:      *
128:      * @param array $options Array of options.
129:      * @return string Relative time string.
130:      */
131:     public function timeAgoInWords(array $options = [])
132:     {
133:         return static::diffFormatter()->dateAgoInWords($this, $options);
134:     }
135: }
136: