includes/MWTimestamp.php

   1 <?php
   2 /**
   3  * Creation and parsing of MW-style timestamps.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @since 1.20
  22  * @author Tyler Romeo, 2012
  23  */
  24 use Wikimedia\Timestamp\ConvertibleTimestamp;
  25
  26 /**
  27  * Library for creating and parsing MW-style timestamps. Based on the JS
  28  * library that does the same thing.
  29  *
  30  * @since 1.20
  31  */
  32 class MWTimestamp extends ConvertibleTimestamp {
  33         /**
  34          * Get a timestamp instance in GMT
  35          *
  36          * @param bool|string $ts Timestamp to set, or false for current time
  37          * @return MWTimestamp The instance
  38          */
  39         public static function getInstance( $ts = false ) {
  40                 return new static( $ts );
  41         }
  42
  43         /**
  44          * Get the timestamp in a human-friendly relative format, e.g., "3 days ago".
  45          *
  46          * Determine the difference between the timestamp and the current time, and
  47          * generate a readable timestamp by returning "<N> <units> ago", where the
  48          * largest possible unit is used.
  49          *
  50          * @since 1.20
  51          * @since 1.22 Uses Language::getHumanTimestamp to produce the timestamp
  52          * @deprecated since 1.26 Use Language::getHumanTimestamp directly
  53          *
  54          * @param MWTimestamp|null $relativeTo The base timestamp to compare to (defaults to now)
  55          * @param User|null $user User the timestamp is being generated for
  56          *  (or null to use main context's user)
  57          * @param Language|null $lang Language to use to make the human timestamp
  58          *  (or null to use main context's language)
  59          * @return string Formatted timestamp
  60          */
  61         public function getHumanTimestamp(
  62                 MWTimestamp $relativeTo = null, User $user = null, Language $lang = null
  63         ) {
  64                 if ( $lang === null ) {
  65                         $lang = RequestContext::getMain()->getLanguage();
  66                 }
  67
  68                 return $lang->getHumanTimestamp( $this, $relativeTo, $user );
  69         }
  70
  71         /**
  72          * Adjust the timestamp depending on the given user's preferences.
  73          *
  74          * @since 1.22
  75          *
  76          * @param User $user User to take preferences from
  77          * @return DateInterval Offset that was applied to the timestamp
  78          */
  79         public function offsetForUser( User $user ) {
  80                 global $wgLocalTZoffset;
  81
  82                 $option = $user->getOption( 'timecorrection' );
  83                 $data = explode( '|', $option, 3 );
  84
  85                 // First handle the case of an actual timezone being specified.
  86                 if ( $data[0] == 'ZoneInfo' ) {
  87                         try {
  88                                 $tz = new DateTimeZone( $data[2] );
  89                         } catch ( Exception $e ) {
  90                                 $tz = false;
  91                         }
  92
  93                         if ( $tz ) {
  94                                 $this->timestamp->setTimezone( $tz );
  95                                 return new DateInterval( 'P0Y' );
  96                         } else {
  97                                 $data[0] = 'Offset';
  98                         }
  99                 }
 100
 101                 $diff = 0;
 102                 // If $option is in fact a pipe-separated value, check the
 103                 // first value.
 104                 if ( $data[0] == 'System' ) {
 105                         // First value is System, so use the system offset.
 106                         if ( $wgLocalTZoffset !== null ) {
 107                                 $diff = $wgLocalTZoffset;
 108                         }
 109                 } elseif ( $data[0] == 'Offset' ) {
 110                         // First value is Offset, so use the specified offset
 111                         $diff = (int)$data[1];
 112                 } else {
 113                         // $option actually isn't a pipe separated value, but instead
 114                         // a comma separated value. Isn't MediaWiki fun?
 115                         $data = explode( ':', $option );
 116                         if ( count( $data ) >= 2 ) {
 117                                 // Combination hours and minutes.
 118                                 $diff = abs( (int)$data[0] ) * 60 + (int)$data[1];
 119                                 if ( (int)$data[0] < 0 ) {
 120                                         $diff *= -1;
 121                                 }
 122                         } else {
 123                                 // Just hours.
 124                                 $diff = (int)$data[0] * 60;
 125                         }
 126                 }
 127
 128                 $interval = new DateInterval( 'PT' . abs( $diff ) . 'M' );
 129                 if ( $diff < 1 ) {
 130                         $interval->invert = 1;
 131                 }
 132
 133                 $this->timestamp->add( $interval );
 134                 return $interval;
 135         }
 136
 137         /**
 138          * Generate a purely relative timestamp, i.e., represent the time elapsed between
 139          * the given base timestamp and this object.
 140          *
 141          * @param MWTimestamp $relativeTo Relative base timestamp (defaults to now)
 142          * @param User $user Use to use offset for
 143          * @param Language $lang Language to use
 144          * @param array $chosenIntervals Intervals to use to represent it
 145          * @return string Relative timestamp
 146          */
 147         public function getRelativeTimestamp(
 148                 MWTimestamp $relativeTo = null,
 149                 User $user = null,
 150                 Language $lang = null,
 151                 array $chosenIntervals = []
 152         ) {
 153                 if ( $relativeTo === null ) {
 154                         $relativeTo = new self;
 155                 }
 156                 if ( $user === null ) {
 157                         $user = RequestContext::getMain()->getUser();
 158                 }
 159                 if ( $lang === null ) {
 160                         $lang = RequestContext::getMain()->getLanguage();
 161                 }
 162
 163                 $ts = '';
 164                 $diff = $this->diff( $relativeTo );
 165                 if ( Hooks::run(
 166                         'GetRelativeTimestamp',
 167                         [ &$ts, &$diff, $this, $relativeTo, $user, $lang ]
 168                 ) ) {
 169                         $seconds = ( ( ( $diff->days * 24 + $diff->h ) * 60 + $diff->i ) * 60 + $diff->s );
 170                         $ts = wfMessage( 'ago', $lang->formatDuration( $seconds, $chosenIntervals ) )
 171                                 ->inLanguage( $lang )->text();
 172                 }
 173
 174                 return $ts;
 175         }
 176
 177         /**
 178          * Get the localized timezone message, if available.
 179          *
 180          * Premade translations are not shipped as format() may return whatever the
 181          * system uses, localized or not, so translation must be done through wiki.
 182          *
 183          * @since 1.27
 184          * @return Message The localized timezone message
 185          */
 186         public function getTimezoneMessage() {
 187                 $tzMsg = $this->format( 'T' );  // might vary on DST changeover!
 188                 $key = 'timezone-' . strtolower( trim( $tzMsg ) );
 189                 $msg = wfMessage( $key );
 190                 if ( $msg->exists() ) {
 191                         return $msg;
 192                 } else {
 193                         return new RawMessage( $tzMsg );
 194                 }
 195         }
 196
 197         /**
 198          * Get a timestamp instance in the server local timezone ($wgLocaltimezone)
 199          *
 200          * @since 1.22
 201          * @param bool|string $ts Timestamp to set, or false for current time
 202          * @return MWTimestamp The local instance
 203          */
 204         public static function getLocalInstance( $ts = false ) {
 205                 global $wgLocaltimezone;
 206                 $timestamp = new self( $ts );
 207                 $timestamp->setTimezone( $wgLocaltimezone );
 208                 return $timestamp;
 209         }
 210 }