Update docs for return and exception info
[lhc/web/wiklou.git] / includes / GlobalFunctions.php
index 84cdeea..3de25e7 100644 (file)
@@ -169,6 +169,7 @@ function wfArrayLookup( $a, $b ) {
  * @param $value Mixed
  * @param $default Mixed
  * @param $changed Array to alter
+ * @throws MWException
  */
 function wfAppendToArrayIfNotDefault( $key, $value, $default, &$changed ) {
        if ( is_null( $changed ) ) {
@@ -786,6 +787,9 @@ function wfParseUrl( $url ) {
                return false;
        }
 
+       // parse_url() incorrectly handles schemes case-sensitively. Convert it to lowercase.
+       $bits['scheme'] = strtolower( $bits['scheme'] );
+
        // most of the protocols are followed by ://, but mailto: and sometimes news: not, check for it
        if ( in_array( $bits['scheme'] . '://', $wgUrlProtocols ) ) {
                $bits['delimiter'] = '://';
@@ -1107,6 +1111,7 @@ function wfWarn( $msg, $callerOffset = 1, $level = E_USER_NOTICE ) {
  *
  * @param $text String
  * @param $file String filename
+ * @throws MWException
  */
 function wfErrorLog( $text, $file ) {
        if ( substr( $file, 0, 4 ) == 'udp:' ) {
@@ -1539,8 +1544,6 @@ function wfMsgGetKey( $key, $useDB = true, $langCode = false, $transform = true
 /**
  * Replace message parameter keys on the given formatted output.
  *
- * @deprecated since 1.18
- *
  * @param $message String
  * @param $args Array
  * @return string
@@ -1718,6 +1721,7 @@ function wfEmptyMsg( $key ) {
  * but now throws an exception instead, with similar results.
  *
  * @param $msg String: message shown when dying.
+ * @throws MWException
  */
 function wfDebugDieBacktrace( $msg = '' ) {
        throw new MWException( $msg );
@@ -2408,118 +2412,13 @@ define( 'TS_ISO_8601_BASIC', 9 );
  * @return Mixed: String / false The same date in the format specified in $outputtype or false
  */
 function wfTimestamp( $outputtype = TS_UNIX, $ts = 0 ) {
-       $uts = 0;
-       $da = array();
-       $strtime = '';
-
-       if ( !$ts ) { // We want to catch 0, '', null... but not date strings starting with a letter.
-               $uts = time();
-               $strtime = "@$uts";
-       } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)$/D', $ts, $da ) ) {
-               # TS_DB
-       } elseif ( preg_match( '/^(\d{4}):(\d\d):(\d\d) (\d\d):(\d\d):(\d\d)$/D', $ts, $da ) ) {
-               # TS_EXIF
-       } elseif ( preg_match( '/^(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)$/D', $ts, $da ) ) {
-               # TS_MW
-       } elseif ( preg_match( '/^-?\d{1,13}$/D', $ts ) ) {
-               # TS_UNIX
-               $uts = $ts;
-               $strtime = "@$ts"; // http://php.net/manual/en/datetime.formats.compound.php
-       } elseif ( preg_match( '/^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}.\d{6}$/', $ts ) ) {
-               # TS_ORACLE // session altered to DD-MM-YYYY HH24:MI:SS.FF6
-               $strtime = preg_replace( '/(\d\d)\.(\d\d)\.(\d\d)(\.(\d+))?/', "$1:$2:$3",
-                               str_replace( '+00:00', 'UTC', $ts ) );
-       } elseif ( preg_match( '/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.*\d*)?Z$/', $ts, $da ) ) {
-               # TS_ISO_8601
-       } elseif ( preg_match( '/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(?:\.*\d*)?Z$/', $ts, $da ) ) {
-               #TS_ISO_8601_BASIC
-       } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.*\d*[\+\- ](\d\d)$/', $ts, $da ) ) {
-               # TS_POSTGRES
-       } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.*\d* GMT$/', $ts, $da ) ) {
-               # TS_POSTGRES
-       } elseif (preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.\d\d\d$/', $ts, $da ) ) {
-               # TS_DB2
-       } elseif ( preg_match( '/^[ \t\r\n]*([A-Z][a-z]{2},[ \t\r\n]*)?' . # Day of week
-                                                       '\d\d?[ \t\r\n]*[A-Z][a-z]{2}[ \t\r\n]*\d{2}(?:\d{2})?' .  # dd Mon yyyy
-                                                       '[ \t\r\n]*\d\d[ \t\r\n]*:[ \t\r\n]*\d\d[ \t\r\n]*:[ \t\r\n]*\d\d/S', $ts ) ) { # hh:mm:ss
-               # TS_RFC2822, accepting a trailing comment. See http://www.squid-cache.org/mail-archive/squid-users/200307/0122.html / r77171
-               # The regex is a superset of rfc2822 for readability
-               $strtime = strtok( $ts, ';' );
-       } elseif ( preg_match( '/^[A-Z][a-z]{5,8}, \d\d-[A-Z][a-z]{2}-\d{2} \d\d:\d\d:\d\d/', $ts ) ) {
-               # TS_RFC850
-               $strtime = $ts;
-       } elseif ( preg_match( '/^[A-Z][a-z]{2} [A-Z][a-z]{2} +\d{1,2} \d\d:\d\d:\d\d \d{4}/', $ts ) ) {
-               # asctime
-               $strtime = $ts;
-       } else {
-               # Bogus value...
+       try {
+               $timestamp = new MWTimestamp( $ts );
+               return $timestamp->getTimestamp( $outputtype );
+       } catch( TimestampException $e ) {
                wfDebug("wfTimestamp() fed bogus time value: TYPE=$outputtype; VALUE=$ts\n");
-
                return false;
        }
-
-       static $formats = array(
-               TS_UNIX => 'U',
-               TS_MW => 'YmdHis',
-               TS_DB => 'Y-m-d H:i:s',
-               TS_ISO_8601 => 'Y-m-d\TH:i:s\Z',
-               TS_ISO_8601_BASIC => 'Ymd\THis\Z',
-               TS_EXIF => 'Y:m:d H:i:s', // This shouldn't ever be used, but is included for completeness
-               TS_RFC2822 => 'D, d M Y H:i:s',
-               TS_ORACLE => 'd-m-Y H:i:s.000000', // Was 'd-M-y h.i.s A' . ' +00:00' before r51500
-               TS_POSTGRES => 'Y-m-d H:i:s',
-               TS_DB2 => 'Y-m-d H:i:s',
-       );
-
-       if ( !isset( $formats[$outputtype] ) ) {
-               throw new MWException( 'wfTimestamp() called with illegal output type.' );
-       }
-
-       if ( function_exists( "date_create" ) ) {
-               if ( count( $da ) ) {
-                       $ds = sprintf("%04d-%02d-%02dT%02d:%02d:%02d.00+00:00",
-                               (int)$da[1], (int)$da[2], (int)$da[3],
-                               (int)$da[4], (int)$da[5], (int)$da[6]);
-
-                       $d = date_create( $ds, new DateTimeZone( 'GMT' ) );
-               } elseif ( $strtime ) {
-                       $d = date_create( $strtime, new DateTimeZone( 'GMT' ) );
-               } else {
-                       return false;
-               }
-
-               if ( !$d ) {
-                       wfDebug("wfTimestamp() fed bogus time value: $outputtype; $ts\n");
-                       return false;
-               }
-
-               $output = $d->format( $formats[$outputtype] );
-       } else {
-               if ( count( $da ) ) {
-                       // Warning! gmmktime() acts oddly if the month or day is set to 0
-                       // We may want to handle that explicitly at some point
-                       $uts = gmmktime( (int)$da[4], (int)$da[5], (int)$da[6],
-                               (int)$da[2], (int)$da[3], (int)$da[1] );
-               } elseif ( $strtime ) {
-                       $uts = strtotime( $strtime );
-               }
-
-               if ( $uts === false ) {
-                       wfDebug("wfTimestamp() can't parse the timestamp (non 32-bit time? Update php): $outputtype; $ts\n");
-                       return false;
-               }
-
-               if ( TS_UNIX == $outputtype ) {
-                       return $uts;
-               }
-               $output = gmdate( $formats[$outputtype], $uts );
-       }
-
-       if ( ( $outputtype == TS_RFC2822 ) || ( $outputtype == TS_POSTGRES ) ) {
-               $output .= ' GMT';
-       }
-
-       return $output;
 }
 
 /**
@@ -2616,6 +2515,7 @@ function wfTempDir() {
  * @param $dir String: full path to directory to create
  * @param $mode Integer: chmod value to use, default is $wgDirectoryMode
  * @param $caller String: optional caller param for debugging.
+ * @throws MWException
  * @return bool
  */
 function wfMkdirParents( $dir, $mode = null, $caller = null ) {
@@ -3126,6 +3026,7 @@ function wfDiff( $before, $after, $params = '-u' ) {
  *
  * @param $req_ver Mixed: the version to check, can be a string, an integer, or
  *                 a float
+ * @throws MWException
  */
 function wfUsePHP( $req_ver ) {
        $php_ver = PHP_VERSION;
@@ -3147,6 +3048,7 @@ function wfUsePHP( $req_ver ) {
  *
  * @param $req_ver Mixed: the version to check, can be a string, an integer, or
  *                 a float
+ * @throws MWException
  */
 function wfUseMW( $req_ver ) {
        global $wgVersion;
@@ -3655,16 +3557,6 @@ function wfBoolToStr( $value ) {
        return $value ? 'true' : 'false';
 }
 
-/**
- * Load an extension messages file
- *
- * @deprecated since 1.16, warnings in 1.18, remove in 1.20
- * @codeCoverageIgnore
- */
-function wfLoadExtensionMessages() {
-       wfDeprecated( __FUNCTION__, '1.16' );
-}
-
 /**
  * Get a platform-independent path to the null file, e.g. /dev/null
  *