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