includes/GlobalFunctions.php

   1 <?php
   2 /**
   3  * Global functions used everywhere
   4  * @file
   5  */
   6
   7 if ( !defined( 'MEDIAWIKI' ) ) {
   8         die( "This file is part of MediaWiki, it is not a valid entry point" );
   9 }
  10
  11 // Hide compatibility functions from Doxygen
  12 /// @cond
  13
  14 /**
  15  * Compatibility functions
  16  *
  17  * We support PHP 5.2.3 and up.
  18  * Re-implementations of newer functions or functions in non-standard
  19  * PHP extensions may be included here.
  20  */
  21
  22 if( !function_exists( 'iconv' ) ) {
  23         /** @codeCoverageIgnore */
  24         function iconv( $from, $to, $string ) {
  25                 return Fallback::iconv( $from, $to, $string );
  26         }
  27 }
  28
  29 if ( !function_exists( 'mb_substr' ) ) {
  30         /** @codeCoverageIgnore */
  31         function mb_substr( $str, $start, $count='end' ) {
  32                 return Fallback::mb_substr( $str, $start, $count );
  33         }
  34
  35         /** @codeCoverageIgnore */
  36         function mb_substr_split_unicode( $str, $splitPos ) {
  37                 return Fallback::mb_substr_split_unicode( $str, $splitPos );
  38         }
  39 }
  40
  41 if ( !function_exists( 'mb_strlen' ) ) {
  42         /** @codeCoverageIgnore */
  43         function mb_strlen( $str, $enc = '' ) {
  44                 return Fallback::mb_strlen( $str, $enc );
  45         }
  46 }
  47
  48 if( !function_exists( 'mb_strpos' ) ) {
  49         /** @codeCoverageIgnore */
  50         function mb_strpos( $haystack, $needle, $offset = 0, $encoding = '' ) {
  51                 return Fallback::mb_strpos( $haystack, $needle, $offset, $encoding );
  52         }
  53
  54 }
  55
  56 if( !function_exists( 'mb_strrpos' ) ) {
  57         /** @codeCoverageIgnore */
  58         function mb_strrpos( $haystack, $needle, $offset = 0, $encoding = '' ) {
  59                 return Fallback::mb_strrpos( $haystack, $needle, $offset, $encoding );
  60         }
  61 }
  62
  63
  64 // Support for Wietse Venema's taint feature
  65 if ( !function_exists( 'istainted' ) ) {
  66         /** @codeCoverageIgnore */
  67         function istainted( $var ) {
  68                 return 0;
  69         }
  70         /** @codeCoverageIgnore */
  71         function taint( $var, $level = 0 ) {}
  72         /** @codeCoverageIgnore */
  73         function untaint( $var, $level = 0 ) {}
  74         define( 'TC_HTML', 1 );
  75         define( 'TC_SHELL', 1 );
  76         define( 'TC_MYSQL', 1 );
  77         define( 'TC_PCRE', 1 );
  78         define( 'TC_SELF', 1 );
  79 }
  80 /// @endcond
  81
  82 /**
  83  * Like array_diff( $a, $b ) except that it works with two-dimensional arrays.
  84  * @param $a array
  85  * @param $b array
  86  * @return array
  87  */
  88 function wfArrayDiff2( $a, $b ) {
  89         return array_udiff( $a, $b, 'wfArrayDiff2_cmp' );
  90 }
  91
  92 /**
  93  * @param $a
  94  * @param $b
  95  * @return int
  96  */
  97 function wfArrayDiff2_cmp( $a, $b ) {
  98         if ( !is_array( $a ) ) {
  99                 return strcmp( $a, $b );
 100         } elseif ( count( $a ) !== count( $b ) ) {
 101                 return count( $a ) < count( $b ) ? -1 : 1;
 102         } else {
 103                 reset( $a );
 104                 reset( $b );
 105                 while( ( list( , $valueA ) = each( $a ) ) && ( list( , $valueB ) = each( $b ) ) ) {
 106                         $cmp = strcmp( $valueA, $valueB );
 107                         if ( $cmp !== 0 ) {
 108                                 return $cmp;
 109                         }
 110                 }
 111                 return 0;
 112         }
 113 }
 114
 115 /**
 116  * Array lookup
 117  * Returns an array where the values in the first array are replaced by the
 118  * values in the second array with the corresponding keys
 119  *
 120  * @param $a Array
 121  * @param $b Array
 122  * @return array
 123  */
 124 function wfArrayLookup( $a, $b ) {
 125         return array_flip( array_intersect( array_flip( $a ), array_keys( $b ) ) );
 126 }
 127
 128 /**
 129  * Appends to second array if $value differs from that in $default
 130  *
 131  * @param $key String|Int
 132  * @param $value Mixed
 133  * @param $default Mixed
 134  * @param $changed Array to alter
 135  */
 136 function wfAppendToArrayIfNotDefault( $key, $value, $default, &$changed ) {
 137         if ( is_null( $changed ) ) {
 138                 throw new MWException( 'GlobalFunctions::wfAppendToArrayIfNotDefault got null' );
 139         }
 140         if ( $default[$key] !== $value ) {
 141                 $changed[$key] = $value;
 142         }
 143 }
 144
 145 /**
 146  * Backwards array plus for people who haven't bothered to read the PHP manual
 147  * XXX: will not darn your socks for you.
 148  *
 149  * @param $array1 Array
 150  * @param [$array2, [...]] Arrays
 151  * @return Array
 152  */
 153 function wfArrayMerge( $array1/* ... */ ) {
 154         $args = func_get_args();
 155         $args = array_reverse( $args, true );
 156         $out = array();
 157         foreach ( $args as $arg ) {
 158                 $out += $arg;
 159         }
 160         return $out;
 161 }
 162
 163 /**
 164  * Merge arrays in the style of getUserPermissionsErrors, with duplicate removal
 165  * e.g.
 166  *      wfMergeErrorArrays(
 167  *              array( array( 'x' ) ),
 168  *              array( array( 'x', '2' ) ),
 169  *              array( array( 'x' ) ),
 170  *              array( array( 'y' ) )
 171  *      );
 172  * returns:
 173  *              array(
 174  *              array( 'x', '2' ),
 175  *              array( 'x' ),
 176  *              array( 'y' )
 177  *      )
 178  * @param varargs
 179  * @return Array
 180  */
 181 function wfMergeErrorArrays( /*...*/ ) {
 182         $args = func_get_args();
 183         $out = array();
 184         foreach ( $args as $errors ) {
 185                 foreach ( $errors as $params ) {
 186                         # @todo FIXME: Sometimes get nested arrays for $params,
 187                         # which leads to E_NOTICEs
 188                         $spec = implode( "\t", $params );
 189                         $out[$spec] = $params;
 190                 }
 191         }
 192         return array_values( $out );
 193 }
 194
 195 /**
 196  * Insert array into another array after the specified *KEY*
 197  *
 198  * @param $array Array: The array.
 199  * @param $insert Array: The array to insert.
 200  * @param $after Mixed: The key to insert after
 201  * @return Array
 202  */
 203 function wfArrayInsertAfter( $array, $insert, $after ) {
 204         // Find the offset of the element to insert after.
 205         $keys = array_keys( $array );
 206         $offsetByKey = array_flip( $keys );
 207
 208         $offset = $offsetByKey[$after];
 209
 210         // Insert at the specified offset
 211         $before = array_slice( $array, 0, $offset + 1, true );
 212         $after = array_slice( $array, $offset + 1, count( $array ) - $offset, true );
 213
 214         $output = $before + $insert + $after;
 215
 216         return $output;
 217 }
 218
 219 /**
 220  * Recursively converts the parameter (an object) to an array with the same data
 221  *
 222  * @param $objOrArray Object|Array
 223  * @param $recursive Bool
 224  * @return Array
 225  */
 226 function wfObjectToArray( $objOrArray, $recursive = true ) {
 227         $array = array();
 228         if( is_object( $objOrArray ) ) {
 229                 $objOrArray = get_object_vars( $objOrArray );
 230         }
 231         foreach ( $objOrArray as $key => $value ) {
 232                 if ( $recursive && ( is_object( $value ) || is_array( $value ) ) ) {
 233                         $value = wfObjectToArray( $value );
 234                 }
 235
 236                 $array[$key] = $value;
 237         }
 238
 239         return $array;
 240 }
 241
 242 /**
 243  * Wrapper around array_map() which also taints variables
 244  *
 245  * @param  $function Callback
 246  * @param  $input Array
 247  * @return Array
 248  */
 249 function wfArrayMap( $function, $input ) {
 250         $ret = array_map( $function, $input );
 251         foreach ( $ret as $key => $value ) {
 252                 $taint = istainted( $input[$key] );
 253                 if ( $taint ) {
 254                         taint( $ret[$key], $taint );
 255                 }
 256         }
 257         return $ret;
 258 }
 259
 260 /**
 261  * Get a random decimal value between 0 and 1, in a way
 262  * not likely to give duplicate values for any realistic
 263  * number of articles.
 264  *
 265  * @return string
 266  */
 267 function wfRandom() {
 268         # The maximum random value is "only" 2^31-1, so get two random
 269         # values to reduce the chance of dupes
 270         $max = mt_getrandmax() + 1;
 271         $rand = number_format( ( mt_rand() * $max + mt_rand() )
 272                 / $max / $max, 12, '.', '' );
 273         return $rand;
 274 }
 275
 276 /**
 277  * We want some things to be included as literal characters in our title URLs
 278  * for prettiness, which urlencode encodes by default.  According to RFC 1738,
 279  * all of the following should be safe:
 280  *
 281  * ;:@&=$-_.+!*'(),
 282  *
 283  * But + is not safe because it's used to indicate a space; &= are only safe in
 284  * paths and not in queries (and we don't distinguish here); ' seems kind of
 285  * scary; and urlencode() doesn't touch -_. to begin with.  Plus, although /
 286  * is reserved, we don't care.  So the list we unescape is:
 287  *
 288  * ;:@$!*(),/
 289  *
 290  * However, IIS7 redirects fail when the url contains a colon (Bug 22709),
 291  * so no fancy : for IIS7.
 292  *
 293  * %2F in the page titles seems to fatally break for some reason.
 294  *
 295  * @param $s String:
 296  * @return string
 297 */
 298 function wfUrlencode( $s ) {
 299         static $needle;
 300         if ( is_null( $s ) ) {
 301                 $needle = null;
 302                 return '';
 303         }
 304
 305         if ( is_null( $needle ) ) {
 306                 $needle = array( '%3B', '%40', '%24', '%21', '%2A', '%28', '%29', '%2C', '%2F' );
 307                 if ( !isset( $_SERVER['SERVER_SOFTWARE'] ) || ( strpos( $_SERVER['SERVER_SOFTWARE'], 'Microsoft-IIS/7' ) === false ) ) {
 308                         $needle[] = '%3A';
 309                 }
 310         }
 311
 312         $s = urlencode( $s );
 313         $s = str_ireplace(
 314                 $needle,
 315                 array( ';', '@', '$', '!', '*', '(', ')', ',', '/', ':' ),
 316                 $s
 317         );
 318
 319         return $s;
 320 }
 321
 322 /**
 323  * This function takes two arrays as input, and returns a CGI-style string, e.g.
 324  * "days=7&limit=100". Options in the first array override options in the second.
 325  * Options set to null or false will not be output.
 326  *
 327  * @param $array1 Array ( String|Array )
 328  * @param $array2 Array ( String|Array )
 329  * @param $prefix String
 330  * @return String
 331  */
 332 function wfArrayToCGI( $array1, $array2 = null, $prefix = '' ) {
 333         if ( !is_null( $array2 ) ) {
 334                 $array1 = $array1 + $array2;
 335         }
 336
 337         $cgi = '';
 338         foreach ( $array1 as $key => $value ) {
 339                 if ( !is_null($value) && $value !== false ) {
 340                         if ( $cgi != '' ) {
 341                                 $cgi .= '&';
 342                         }
 343                         if ( $prefix !== '' ) {
 344                                 $key = $prefix . "[$key]";
 345                         }
 346                         if ( is_array( $value ) ) {
 347                                 $firstTime = true;
 348                                 foreach ( $value as $k => $v ) {
 349                                         $cgi .= $firstTime ? '' : '&';
 350                                         if ( is_array( $v ) ) {
 351                                                 $cgi .= wfArrayToCGI( $v, null, $key . "[$k]" );
 352                                         } else {
 353                                                 $cgi .= urlencode( $key . "[$k]" ) . '=' . urlencode( $v );
 354                                         }
 355                                         $firstTime = false;
 356                                 }
 357                         } else {
 358                                 if ( is_object( $value ) ) {
 359                                         $value = $value->__toString();
 360                                 }
 361                                 $cgi .= urlencode( $key ) . '=' . urlencode( $value );
 362                         }
 363                 }
 364         }
 365         return $cgi;
 366 }
 367
 368 /**
 369  * This is the logical opposite of wfArrayToCGI(): it accepts a query string as
 370  * its argument and returns the same string in array form.  This allows compa-
 371  * tibility with legacy functions that accept raw query strings instead of nice
 372  * arrays.  Of course, keys and values are urldecode()d.
 373  *
 374  * @param $query String: query string
 375  * @return array Array version of input
 376  */
 377 function wfCgiToArray( $query ) {
 378         if ( isset( $query[0] ) && $query[0] == '?' ) {
 379                 $query = substr( $query, 1 );
 380         }
 381         $bits = explode( '&', $query );
 382         $ret = array();
 383         foreach ( $bits as $bit ) {
 384                 if ( $bit === '' ) {
 385                         continue;
 386                 }
 387                 if ( strpos( $bit, '=' ) === false ) {
 388                         // Pieces like &qwerty become 'qwerty' => '' (at least this is what php does)
 389                         $key = $bit;
 390                         $value = '';
 391                 } else {
 392                         list( $key, $value ) = explode( '=', $bit );
 393                 }
 394                 $key = urldecode( $key );
 395                 $value = urldecode( $value );
 396                 if ( strpos( $key, '[' ) !== false ) {
 397                         $keys = array_reverse( explode( '[', $key ) );
 398                         $key = array_pop( $keys );
 399                         $temp = $value;
 400                         foreach ( $keys as $k ) {
 401                                 $k = substr( $k, 0, -1 );
 402                                 $temp = array( $k => $temp );
 403                         }
 404                         if ( isset( $ret[$key] ) ) {
 405                                 $ret[$key] = array_merge( $ret[$key], $temp );
 406                         } else {
 407                                 $ret[$key] = $temp;
 408                         }
 409                 } else {
 410                         $ret[$key] = $value;
 411                 }
 412         }
 413         return $ret;
 414 }
 415
 416 /**
 417  * Append a query string to an existing URL, which may or may not already
 418  * have query string parameters already. If so, they will be combined.
 419  *
 420  * @param $url String
 421  * @param $query Mixed: string or associative array
 422  * @return string
 423  */
 424 function wfAppendQuery( $url, $query ) {
 425         if ( is_array( $query ) ) {
 426                 $query = wfArrayToCGI( $query );
 427         }
 428         if( $query != '' ) {
 429                 if( false === strpos( $url, '?' ) ) {
 430                         $url .= '?';
 431                 } else {
 432                         $url .= '&';
 433                 }
 434                 $url .= $query;
 435         }
 436         return $url;
 437 }
 438
 439 /**
 440  * Expand a potentially local URL to a fully-qualified URL.  Assumes $wgServer
 441  * is correct.
 442  *
 443  * The meaning of the PROTO_* constants is as follows:
 444  * PROTO_HTTP: Output a URL starting with http://
 445  * PROTO_HTTPS: Output a URL starting with https://
 446  * PROTO_RELATIVE: Output a URL starting with // (protocol-relative URL)
 447  * PROTO_CURRENT: Output a URL starting with either http:// or https:// , depending on which protocol was used for the current incoming request
 448  * PROTO_CANONICAL: For URLs without a domain, like /w/index.php , use $wgCanonicalServer. For protocol-relative URLs, use the protocol of $wgCanonicalServer
 449  * PROTO_INTERNAL: Like PROTO_CANONICAL, but uses $wgInternalServer instead of $wgCanonicalServer
 450  *
 451  * @todo this won't work with current-path-relative URLs
 452  * like "subdir/foo.html", etc.
 453  *
 454  * @param $url String: either fully-qualified or a local path + query
 455  * @param $defaultProto Mixed: one of the PROTO_* constants. Determines the
 456  *                             protocol to use if $url or $wgServer is
 457  *                             protocol-relative
 458  * @return string Fully-qualified URL, current-path-relative URL or false if
 459  *                no valid URL can be constructed
 460  */
 461 function wfExpandUrl( $url, $defaultProto = PROTO_CURRENT ) {
 462         global $wgServer, $wgCanonicalServer, $wgInternalServer;
 463         $serverUrl = $wgServer;
 464         if ( $defaultProto === PROTO_CANONICAL ) {
 465                 $serverUrl = $wgCanonicalServer;
 466         }
 467         // Make $wgInternalServer fall back to $wgServer if not set
 468         if ( $defaultProto === PROTO_INTERNAL && $wgInternalServer !== false ) {
 469                 $serverUrl = $wgInternalServer;
 470         }
 471         if ( $defaultProto === PROTO_CURRENT ) {
 472                 $defaultProto = WebRequest::detectProtocol() . '://';
 473         }
 474
 475         // Analyze $serverUrl to obtain its protocol
 476         $bits = wfParseUrl( $serverUrl );
 477         $serverHasProto = $bits && $bits['scheme'] != '';
 478
 479         if ( $defaultProto === PROTO_CANONICAL || $defaultProto === PROTO_INTERNAL ) {
 480                 if ( $serverHasProto ) {
 481                         $defaultProto = $bits['scheme'] . '://';
 482                 } else {
 483                         // $wgCanonicalServer or $wgInternalServer doesn't have a protocol. This really isn't supposed to happen
 484                         // Fall back to HTTP in this ridiculous case
 485                         $defaultProto = PROTO_HTTP;
 486                 }
 487         }
 488
 489         $defaultProtoWithoutSlashes = substr( $defaultProto, 0, -2 );
 490
 491         if ( substr( $url, 0, 2 ) == '//' ) {
 492                 $url = $defaultProtoWithoutSlashes . $url;
 493         } elseif ( substr( $url, 0, 1 ) == '/' ) {
 494                 // If $serverUrl is protocol-relative, prepend $defaultProtoWithoutSlashes, otherwise leave it alone
 495                 $url = ( $serverHasProto ? '' : $defaultProtoWithoutSlashes ) . $serverUrl . $url;
 496         }
 497
 498         $bits = wfParseUrl( $url );
 499         if ( $bits && isset( $bits['path'] ) ) {
 500                 $bits['path'] = wfRemoveDotSegments( $bits['path'] );
 501                 return wfAssembleUrl( $bits );
 502         } elseif ( $bits ) {
 503                 # No path to expand
 504                 return $url;
 505         } elseif ( substr( $url, 0, 1 ) != '/' ) {
 506                 # URL is a relative path
 507                 return wfRemoveDotSegments( $url );
 508         }
 509
 510         # Expanded URL is not valid.
 511         return false;
 512 }
 513
 514 /**
 515  * This function will reassemble a URL parsed with wfParseURL.  This is useful
 516  * if you need to edit part of a URL and put it back together.
 517  *
 518  * This is the basic structure used (brackets contain keys for $urlParts):
 519  * [scheme][delimiter][user]:[pass]@[host]:[port][path]?[query]#[fragment]
 520  *
 521  * @todo Need to integrate this into wfExpandUrl (bug 32168)
 522  *
 523  * @param $urlParts Array URL parts, as output from wfParseUrl
 524  * @return string URL assembled from its component parts
 525  */
 526 function wfAssembleUrl( $urlParts ) {
 527         $result = '';
 528
 529         if ( isset( $urlParts['delimiter'] ) ) {
 530                 if ( isset( $urlParts['scheme'] ) ) {
 531                         $result .= $urlParts['scheme'];
 532                 }
 533
 534                 $result .= $urlParts['delimiter'];
 535         }
 536
 537         if ( isset( $urlParts['host'] ) ) {
 538                 if ( isset( $urlParts['user'] ) ) {
 539                         $result .= $urlParts['user'];
 540                         if ( isset( $urlParts['pass'] ) ) {
 541                                 $result .= ':' . $urlParts['pass'];
 542                         }
 543                         $result .= '@';
 544                 }
 545
 546                 $result .= $urlParts['host'];
 547
 548                 if ( isset( $urlParts['port'] ) ) {
 549                         $result .= ':' . $urlParts['port'];
 550                 }
 551         }
 552
 553         if ( isset( $urlParts['path'] ) ) {
 554                 $result .= $urlParts['path'];
 555         }
 556
 557         if ( isset( $urlParts['query'] ) ) {
 558                 $result .= '?' . $urlParts['query'];
 559         }
 560
 561         if ( isset( $urlParts['fragment'] ) ) {
 562                 $result .= '#' . $urlParts['fragment'];
 563         }
 564
 565         return $result;
 566 }
 567
 568 /**
 569  * Remove all dot-segments in the provided URL path.  For example,
 570  * '/a/./b/../c/' becomes '/a/c/'.  For details on the algorithm, please see
 571  * RFC3986 section 5.2.4.
 572  *
 573  * @todo Need to integrate this into wfExpandUrl (bug 32168)
 574  *
 575  * @param $urlPath String URL path, potentially containing dot-segments
 576  * @return string URL path with all dot-segments removed
 577  */
 578 function wfRemoveDotSegments( $urlPath ) {
 579         $output = '';
 580
 581         while ( $urlPath ) {
 582                 $matches = null;
 583                 if ( preg_match('%^\.\.?/%', $urlPath, $matches) ) {
 584                         # Step A, remove leading "../" or "./"
 585                         $urlPath = substr( $urlPath, strlen( $matches[0] ) );
 586                 } elseif ( preg_match( '%^/\.(/|$)%', $urlPath, $matches ) ) {
 587                         # Step B, replace leading "/.$" or "/./" with "/"
 588                         $start = strlen( $matches[0] );
 589                         $urlPath = '/' . substr( $urlPath, $start );
 590                 } elseif ( preg_match( '%^/\.\.(/|$)%', $urlPath, $matches ) ) {
 591                         # Step C, replace leading "/..$" or "/../" with "/" and
 592                         # remove last path component in output
 593                         $start = strlen( $matches[0] );
 594                         $urlPath = '/' . substr( $urlPath, $start );
 595                         $output = preg_replace('%(^|/)[^/]*$%', '', $output);
 596                 } elseif ( preg_match( '%^\.\.?$%', $urlPath, $matches ) ) {
 597                         # Step D, remove "^..$" or "^.$"
 598                         $urlPath = '';
 599                 } else {
 600                         # Step E, move leading path segment to output
 601                         preg_match( '%^/?[^/]*%', $urlPath, $matches );
 602                         $urlPath = substr( $urlPath, strlen( $matches[0] ) );
 603                         $output .= $matches[0];
 604                 }
 605         }
 606
 607         return $output;
 608 }
 609
 610 /**
 611  * Returns a regular expression of url protocols
 612  *
 613  * @param $includeProtocolRelative bool If false, remove '//' from the returned protocol list.
 614  *        DO NOT USE this directly, use wfUrlProtocolsWithoutProtRel() instead
 615  * @return String
 616  */
 617 function wfUrlProtocols( $includeProtocolRelative = true ) {
 618         global $wgUrlProtocols;
 619
 620         // Cache return values separately based on $includeProtocolRelative
 621         static $withProtRel = null, $withoutProtRel = null;
 622         $cachedValue = $includeProtocolRelative ? $withProtRel : $withoutProtRel;
 623         if ( !is_null( $cachedValue ) ) {
 624                 return $cachedValue;
 625         }
 626
 627         // Support old-style $wgUrlProtocols strings, for backwards compatibility
 628         // with LocalSettings files from 1.5
 629         if ( is_array( $wgUrlProtocols ) ) {
 630                 $protocols = array();
 631                 foreach ( $wgUrlProtocols as $protocol ) {
 632                         // Filter out '//' if !$includeProtocolRelative
 633                         if ( $includeProtocolRelative || $protocol !== '//' ) {
 634                                 $protocols[] = preg_quote( $protocol, '/' );
 635                         }
 636                 }
 637
 638                 $retval = implode( '|', $protocols );
 639         } else {
 640                 // Ignore $includeProtocolRelative in this case
 641                 // This case exists for pre-1.6 compatibility, and we can safely assume
 642                 // that '//' won't appear in a pre-1.6 config because protocol-relative
 643                 // URLs weren't supported until 1.18
 644                 $retval = $wgUrlProtocols;
 645         }
 646
 647         // Cache return value
 648         if ( $includeProtocolRelative ) {
 649                 $withProtRel = $retval;
 650         } else {
 651                 $withoutProtRel = $retval;
 652         }
 653         return $retval;
 654 }
 655
 656 /**
 657  * Like wfUrlProtocols(), but excludes '//' from the protocol list. Use this if
 658  * you need a regex that matches all URL protocols but does not match protocol-
 659  * relative URLs
 660  * @return String
 661  */
 662 function wfUrlProtocolsWithoutProtRel() {
 663         return wfUrlProtocols( false );
 664 }
 665
 666 /**
 667  * parse_url() work-alike, but non-broken.  Differences:
 668  *
 669  * 1) Does not raise warnings on bad URLs (just returns false)
 670  * 2) Handles protocols that don't use :// (e.g., mailto: and news: , as well as protocol-relative URLs) correctly
 671  * 3) Adds a "delimiter" element to the array, either '://', ':' or '//' (see (2))
 672  *
 673  * @param $url String: a URL to parse
 674  * @return Array: bits of the URL in an associative array, per PHP docs
 675  */
 676 function wfParseUrl( $url ) {
 677         global $wgUrlProtocols; // Allow all protocols defined in DefaultSettings/LocalSettings.php
 678
 679         // Protocol-relative URLs are handled really badly by parse_url(). It's so bad that the easiest
 680         // way to handle them is to just prepend 'http:' and strip the protocol out later
 681         $wasRelative = substr( $url, 0, 2 ) == '//';
 682         if ( $wasRelative ) {
 683                 $url = "http:$url";
 684         }
 685         wfSuppressWarnings();
 686         $bits = parse_url( $url );
 687         wfRestoreWarnings();
 688         // parse_url() returns an array without scheme for some invalid URLs, e.g.
 689         // parse_url("%0Ahttp://example.com") == array( 'host' => '%0Ahttp', 'path' => 'example.com' )
 690         if ( !$bits || !isset( $bits['scheme'] ) ) {
 691                 return false;
 692         }
 693
 694         // most of the protocols are followed by ://, but mailto: and sometimes news: not, check for it
 695         if ( in_array( $bits['scheme'] . '://', $wgUrlProtocols ) ) {
 696                 $bits['delimiter'] = '://';
 697         } elseif ( in_array( $bits['scheme'] . ':', $wgUrlProtocols ) ) {
 698                 $bits['delimiter'] = ':';
 699                 // parse_url detects for news: and mailto: the host part of an url as path
 700                 // We have to correct this wrong detection
 701                 if ( isset( $bits['path'] ) ) {
 702                         $bits['host'] = $bits['path'];
 703                         $bits['path'] = '';
 704                 }
 705         } else {
 706                 return false;
 707         }
 708
 709         /* Provide an empty host for eg. file:/// urls (see bug 28627) */
 710         if ( !isset( $bits['host'] ) ) {
 711                 $bits['host'] = '';
 712
 713                 /* parse_url loses the third / for file:///c:/ urls (but not on variants) */
 714                 if ( substr( $bits['path'], 0, 1 ) !== '/' ) {
 715                         $bits['path'] = '/' . $bits['path'];
 716                 }
 717         }
 718
 719         // If the URL was protocol-relative, fix scheme and delimiter
 720         if ( $wasRelative ) {
 721                 $bits['scheme'] = '';
 722                 $bits['delimiter'] = '//';
 723         }
 724         return $bits;
 725 }
 726
 727 /**
 728  * Make URL indexes, appropriate for the el_index field of externallinks.
 729  *
 730  * @param $url String
 731  * @return array
 732  */
 733 function wfMakeUrlIndexes( $url ) {
 734         $bits = wfParseUrl( $url );
 735
 736         // Reverse the labels in the hostname, convert to lower case
 737         // For emails reverse domainpart only
 738         if ( $bits['scheme'] == 'mailto' ) {
 739                 $mailparts = explode( '@', $bits['host'], 2 );
 740                 if ( count( $mailparts ) === 2 ) {
 741                         $domainpart = strtolower( implode( '.', array_reverse( explode( '.', $mailparts[1] ) ) ) );
 742                 } else {
 743                         // No domain specified, don't mangle it
 744                         $domainpart = '';
 745                 }
 746                 $reversedHost = $domainpart . '@' . $mailparts[0];
 747         } else {
 748                 $reversedHost = strtolower( implode( '.', array_reverse( explode( '.', $bits['host'] ) ) ) );
 749         }
 750         // Add an extra dot to the end
 751         // Why? Is it in wrong place in mailto links?
 752         if ( substr( $reversedHost, -1, 1 ) !== '.' ) {
 753                 $reversedHost .= '.';
 754         }
 755         // Reconstruct the pseudo-URL
 756         $prot = $bits['scheme'];
 757         $index = $prot . $bits['delimiter'] . $reversedHost;
 758         // Leave out user and password. Add the port, path, query and fragment
 759         if ( isset( $bits['port'] ) ) {
 760                 $index .= ':' . $bits['port'];
 761         }
 762         if ( isset( $bits['path'] ) ) {
 763                 $index .= $bits['path'];
 764         } else {
 765                 $index .= '/';
 766         }
 767         if ( isset( $bits['query'] ) ) {
 768                 $index .= '?' . $bits['query'];
 769         }
 770         if ( isset( $bits['fragment'] ) ) {
 771                 $index .= '#' . $bits['fragment'];
 772         }
 773
 774         if ( $prot == '' ) {
 775                 return array( "http:$index", "https:$index" );
 776         } else {
 777                 return array( $index );
 778         }
 779 }
 780
 781 /**
 782  * Check whether a given URL has a domain that occurs in a given set of domains
 783  * @param $url string URL
 784  * @param $domains array Array of domains (strings)
 785  * @return bool True if the host part of $url ends in one of the strings in $domains
 786  */
 787 function wfMatchesDomainList( $url, $domains ) {
 788         $bits = wfParseUrl( $url );
 789         if ( is_array( $bits ) && isset( $bits['host'] ) ) {
 790                 foreach ( (array)$domains as $domain ) {
 791                         // FIXME: This gives false positives. http://nds-nl.wikipedia.org will match nl.wikipedia.org
 792                         // We should use something that interprets dots instead
 793                         if ( substr( $bits['host'], -strlen( $domain ) ) === $domain ) {
 794                                 return true;
 795                         }
 796                 }
 797         }
 798         return false;
 799 }
 800
 801 /**
 802  * Sends a line to the debug log if enabled or, optionally, to a comment in output.
 803  * In normal operation this is a NOP.
 804  *
 805  * Controlling globals:
 806  * $wgDebugLogFile - points to the log file
 807  * $wgProfileOnly - if set, normal debug messages will not be recorded.
 808  * $wgDebugRawPage - if false, 'action=raw' hits will not result in debug output.
 809  * $wgDebugComments - if on, some debug items may appear in comments in the HTML output.
 810  *
 811  * @param $text String
 812  * @param $logonly Bool: set true to avoid appearing in HTML when $wgDebugComments is set
 813  */
 814 function wfDebug( $text, $logonly = false ) {
 815         global $wgOut, $wgDebugLogFile, $wgDebugComments, $wgProfileOnly, $wgDebugRawPage;
 816         global $wgDebugLogPrefix, $wgShowDebug;
 817
 818         static $cache = array(); // Cache of unoutputted messages
 819         $text = wfDebugTimer() . $text;
 820
 821         if ( !$wgDebugRawPage && wfIsDebugRawPage() ) {
 822                 return;
 823         }
 824
 825         if ( ( $wgDebugComments || $wgShowDebug ) && !$logonly ) {
 826                 $cache[] = $text;
 827
 828                 if ( isset( $wgOut ) && is_object( $wgOut ) ) {
 829                         // add the message and any cached messages to the output
 830                         array_map( array( $wgOut, 'debug' ), $cache );
 831                         $cache = array();
 832                 }
 833         }
 834         if ( wfRunHooks( 'Debug', array( $text, null /* no log group */ ) ) ) {
 835                 if ( $wgDebugLogFile != '' && !$wgProfileOnly ) {
 836                         # Strip unprintables; they can switch terminal modes when binary data
 837                         # gets dumped, which is pretty annoying.
 838                         $text = preg_replace( '![\x00-\x08\x0b\x0c\x0e-\x1f]!', ' ', $text );
 839                         $text = $wgDebugLogPrefix . $text;
 840                         wfErrorLog( $text, $wgDebugLogFile );
 841                 }
 842         }
 843
 844         MWDebug::debugMsg( $text );
 845 }
 846
 847 /**
 848  * Returns true if debug logging should be suppressed if $wgDebugRawPage = false
 849  */
 850 function wfIsDebugRawPage() {
 851         static $cache;
 852         if ( $cache !== null ) {
 853                 return $cache;
 854         }
 855         # Check for raw action using $_GET not $wgRequest, since the latter might not be initialised yet
 856         if ( ( isset( $_GET['action'] ) && $_GET['action'] == 'raw' )
 857                 || (
 858                         isset( $_SERVER['SCRIPT_NAME'] )
 859                         && substr( $_SERVER['SCRIPT_NAME'], -8 ) == 'load.php'
 860                 ) )
 861         {
 862                 $cache = true;
 863         } else {
 864                 $cache = false;
 865         }
 866         return $cache;
 867 }
 868
 869 /**
 870  * Get microsecond timestamps for debug logs
 871  *
 872  * @return string
 873  */
 874 function wfDebugTimer() {
 875         global $wgDebugTimestamps;
 876         if ( !$wgDebugTimestamps ) {
 877                 return '';
 878         }
 879         static $start = null;
 880
 881         if ( $start === null ) {
 882                 $start = microtime( true );
 883                 $prefix = "\n$start";
 884         } else {
 885                 $prefix = sprintf( "%6.4f", microtime( true ) - $start );
 886         }
 887         $mem = sprintf( "%5.1fM", ( memory_get_usage( true ) / (1024*1024) ) );
 888         return "$prefix $mem  " ;
 889 }
 890
 891 /**
 892  * Send a line giving PHP memory usage.
 893  *
 894  * @param $exact Bool: print exact values instead of kilobytes (default: false)
 895  */
 896 function wfDebugMem( $exact = false ) {
 897         $mem = memory_get_usage();
 898         if( !$exact ) {
 899                 $mem = floor( $mem / 1024 ) . ' kilobytes';
 900         } else {
 901                 $mem .= ' bytes';
 902         }
 903         wfDebug( "Memory usage: $mem\n" );
 904 }
 905
 906 /**
 907  * Send a line to a supplementary debug log file, if configured, or main debug log if not.
 908  * $wgDebugLogGroups[$logGroup] should be set to a filename to send to a separate log.
 909  *
 910  * @param $logGroup String
 911  * @param $text String
 912  * @param $public Bool: whether to log the event in the public log if no private
 913  *                     log file is specified, (default true)
 914  */
 915 function wfDebugLog( $logGroup, $text, $public = true ) {
 916         global $wgDebugLogGroups, $wgShowHostnames;
 917         $text = trim( $text ) . "\n";
 918         if( isset( $wgDebugLogGroups[$logGroup] ) ) {
 919                 $time = wfTimestamp( TS_DB );
 920                 $wiki = wfWikiID();
 921                 if ( $wgShowHostnames ) {
 922                         $host = wfHostname();
 923                 } else {
 924                         $host = '';
 925                 }
 926                 if ( wfRunHooks( 'Debug', array( $text, $logGroup ) ) ) {
 927                         wfErrorLog( "$time $host $wiki: $text", $wgDebugLogGroups[$logGroup] );
 928                 }
 929         } elseif ( $public === true ) {
 930                 wfDebug( $text, true );
 931         }
 932 }
 933
 934 /**
 935  * Log for database errors
 936  *
 937  * @param $text String: database error message.
 938  */
 939 function wfLogDBError( $text ) {
 940         global $wgDBerrorLog, $wgDBname;
 941         if ( $wgDBerrorLog ) {
 942                 $host = trim(`hostname`);
 943                 $text = date( 'D M j G:i:s T Y' ) . "\t$host\t$wgDBname\t$text";
 944                 wfErrorLog( $text, $wgDBerrorLog );
 945         }
 946 }
 947
 948 /**
 949  * Log to a file without getting "file size exceeded" signals.
 950  *
 951  * Can also log to TCP or UDP with the syntax udp://host:port/prefix. This will
 952  * send lines to the specified port, prefixed by the specified prefix and a space.
 953  *
 954  * @param $text String
 955  * @param $file String filename
 956  */
 957 function wfErrorLog( $text, $file ) {
 958         if ( substr( $file, 0, 4 ) == 'udp:' ) {
 959                 # Needs the sockets extension
 960                 if ( preg_match( '!^(tcp|udp):(?://)?\[([0-9a-fA-F:]+)\]:(\d+)(?:/(.*))?$!', $file, $m ) ) {
 961                         // IPv6 bracketed host
 962                         $host = $m[2];
 963                         $port = intval( $m[3] );
 964                         $prefix = isset( $m[4] ) ? $m[4] : false;
 965                         $domain = AF_INET6;
 966                 } elseif ( preg_match( '!^(tcp|udp):(?://)?([a-zA-Z0-9.-]+):(\d+)(?:/(.*))?$!', $file, $m ) ) {
 967                         $host = $m[2];
 968                         if ( !IP::isIPv4( $host ) ) {
 969                                 $host = gethostbyname( $host );
 970                         }
 971                         $port = intval( $m[3] );
 972                         $prefix = isset( $m[4] ) ? $m[4] : false;
 973                         $domain = AF_INET;
 974                 } else {
 975                         throw new MWException( __METHOD__ . ': Invalid UDP specification' );
 976                 }
 977
 978                 // Clean it up for the multiplexer
 979                 if ( strval( $prefix ) !== '' ) {
 980                         $text = preg_replace( '/^/m', $prefix . ' ', $text );
 981
 982                         // Limit to 64KB
 983                         if ( strlen( $text ) > 65506 ) {
 984                                 $text = substr( $text, 0, 65506 );
 985                         }
 986
 987                         if ( substr( $text, -1 ) != "\n" ) {
 988                                 $text .= "\n";
 989                         }
 990                 } elseif ( strlen( $text ) > 65507 ) {
 991                         $text = substr( $text, 0, 65507 );
 992                 }
 993
 994                 $sock = socket_create( $domain, SOCK_DGRAM, SOL_UDP );
 995                 if ( !$sock ) {
 996                         return;
 997                 }
 998
 999                 socket_sendto( $sock, $text, strlen( $text ), 0, $host, $port );
1000                 socket_close( $sock );
1001         } else {
1002                 wfSuppressWarnings();
1003                 $exists = file_exists( $file );
1004                 $size = $exists ? filesize( $file ) : false;
1005                 if ( !$exists || ( $size !== false && $size + strlen( $text ) < 0x7fffffff ) ) {
1006                         file_put_contents( $file, $text, FILE_APPEND );
1007                 }
1008                 wfRestoreWarnings();
1009         }
1010 }
1011
1012 /**
1013  * @todo document
1014  */
1015 function wfLogProfilingData() {
1016         global $wgRequestTime, $wgDebugLogFile, $wgDebugRawPage, $wgRequest;
1017         global $wgProfileLimit, $wgUser;
1018
1019         $profiler = Profiler::instance();
1020
1021         # Profiling must actually be enabled...
1022         if ( $profiler->isStub() ) {
1023                 return;
1024         }
1025
1026         // Get total page request time and only show pages that longer than
1027         // $wgProfileLimit time (default is 0)
1028         $now = wfTime();
1029         $elapsed = $now - $wgRequestTime;
1030         if ( $elapsed <= $wgProfileLimit ) {
1031                 return;
1032         }
1033
1034         $profiler->logData();
1035
1036         // Check whether this should be logged in the debug file.
1037         if ( $wgDebugLogFile == '' || ( !$wgDebugRawPage && wfIsDebugRawPage() ) ) {
1038                 return;
1039         }
1040
1041         $forward = '';
1042         if ( !empty( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) {
1043                 $forward = ' forwarded for ' . $_SERVER['HTTP_X_FORWARDED_FOR'];
1044         }
1045         if ( !empty( $_SERVER['HTTP_CLIENT_IP'] ) ) {
1046                 $forward .= ' client IP ' . $_SERVER['HTTP_CLIENT_IP'];
1047         }
1048         if ( !empty( $_SERVER['HTTP_FROM'] ) ) {
1049                 $forward .= ' from ' . $_SERVER['HTTP_FROM'];
1050         }
1051         if ( $forward ) {
1052                 $forward = "\t(proxied via {$_SERVER['REMOTE_ADDR']}{$forward})";
1053         }
1054         // Don't load $wgUser at this late stage just for statistics purposes
1055         // @todo FIXME: We can detect some anons even if it is not loaded. See User::getId()
1056         if ( $wgUser->isItemLoaded( 'id' ) && $wgUser->isAnon() ) {
1057                 $forward .= ' anon';
1058         }
1059         $log = sprintf( "%s\t%04.3f\t%s\n",
1060                 gmdate( 'YmdHis' ), $elapsed,
1061                 urldecode( $wgRequest->getRequestURL() . $forward ) );
1062
1063         wfErrorLog( $log . $profiler->getOutput(), $wgDebugLogFile );
1064 }
1065
1066 /**
1067  * Check if the wiki read-only lock file is present. This can be used to lock
1068  * off editing functions, but doesn't guarantee that the database will not be
1069  * modified.
1070  *
1071  * @return bool
1072  */
1073 function wfReadOnly() {
1074         global $wgReadOnlyFile, $wgReadOnly;
1075
1076         if ( !is_null( $wgReadOnly ) ) {
1077                 return (bool)$wgReadOnly;
1078         }
1079         if ( $wgReadOnlyFile == '' ) {
1080                 return false;
1081         }
1082         // Set $wgReadOnly for faster access next time
1083         if ( is_file( $wgReadOnlyFile ) ) {
1084                 $wgReadOnly = file_get_contents( $wgReadOnlyFile );
1085         } else {
1086                 $wgReadOnly = false;
1087         }
1088         return (bool)$wgReadOnly;
1089 }
1090
1091 /**
1092  * @return bool
1093  */
1094 function wfReadOnlyReason() {
1095         global $wgReadOnly;
1096         wfReadOnly();
1097         return $wgReadOnly;
1098 }
1099
1100 /**
1101  * Return a Language object from $langcode
1102  *
1103  * @param $langcode Mixed: either:
1104  *                  - a Language object
1105  *                  - code of the language to get the message for, if it is
1106  *                    a valid code create a language for that language, if
1107  *                    it is a string but not a valid code then make a basic
1108  *                    language object
1109  *                  - a boolean: if it's false then use the global object for
1110  *                    the current user's language (as a fallback for the old parameter
1111  *                    functionality), or if it is true then use global object
1112  *                    for the wiki's content language.
1113  * @return Language object
1114  */
1115 function wfGetLangObj( $langcode = false ) {
1116         # Identify which language to get or create a language object for.
1117         # Using is_object here due to Stub objects.
1118         if( is_object( $langcode ) ) {
1119                 # Great, we already have the object (hopefully)!
1120                 return $langcode;
1121         }
1122
1123         global $wgContLang, $wgLanguageCode;
1124         if( $langcode === true || $langcode === $wgLanguageCode ) {
1125                 # $langcode is the language code of the wikis content language object.
1126                 # or it is a boolean and value is true
1127                 return $wgContLang;
1128         }
1129
1130         global $wgLang;
1131         if( $langcode === false || $langcode === $wgLang->getCode() ) {
1132                 # $langcode is the language code of user language object.
1133                 # or it was a boolean and value is false
1134                 return $wgLang;
1135         }
1136
1137         $validCodes = array_keys( Language::getLanguageNames() );
1138         if( in_array( $langcode, $validCodes ) ) {
1139                 # $langcode corresponds to a valid language.
1140                 return Language::factory( $langcode );
1141         }
1142
1143         # $langcode is a string, but not a valid language code; use content language.
1144         wfDebug( "Invalid language code passed to wfGetLangObj, falling back to content language.\n" );
1145         return $wgContLang;
1146 }
1147
1148 /**
1149  * Old function when $wgBetterDirectionality existed
1150  * Removed in core, kept in extensions for backwards compat.
1151  *
1152  * @deprecated since 1.18
1153  * @return Language
1154  */
1155 function wfUILang() {
1156         wfDeprecated( __METHOD__, '1.18' );
1157         global $wgLang;
1158         return $wgLang;
1159 }
1160
1161 /**
1162  * This is the new function for getting translated interface messages.
1163  * See the Message class for documentation how to use them.
1164  * The intention is that this function replaces all old wfMsg* functions.
1165  * @param $key \string Message key.
1166  * Varargs: normal message parameters.
1167  * @return Message
1168  * @since 1.17
1169  */
1170 function wfMessage( $key /*...*/) {
1171         $params = func_get_args();
1172         array_shift( $params );
1173         if ( isset( $params[0] ) && is_array( $params[0] ) ) {
1174                 $params = $params[0];
1175         }
1176         return new Message( $key, $params );
1177 }
1178
1179 /**
1180  * This function accepts multiple message keys and returns a message instance
1181  * for the first message which is non-empty. If all messages are empty then an
1182  * instance of the first message key is returned.
1183  * @param varargs: message keys
1184  * @return Message
1185  * @since 1.18
1186  */
1187 function wfMessageFallback( /*...*/ ) {
1188         $args = func_get_args();
1189         return MWFunction::callArray( 'Message::newFallbackSequence', $args );
1190 }
1191
1192 /**
1193  * Get a message from anywhere, for the current user language.
1194  *
1195  * Use wfMsgForContent() instead if the message should NOT
1196  * change depending on the user preferences.
1197  *
1198  * @param $key String: lookup key for the message, usually
1199  *    defined in languages/Language.php
1200  *
1201  * Parameters to the message, which can be used to insert variable text into
1202  * it, can be passed to this function in the following formats:
1203  * - One per argument, starting at the second parameter
1204  * - As an array in the second parameter
1205  * These are not shown in the function definition.
1206  *
1207  * @return String
1208  */
1209 function wfMsg( $key ) {
1210         $args = func_get_args();
1211         array_shift( $args );
1212         return wfMsgReal( $key, $args );
1213 }
1214
1215 /**
1216  * Same as above except doesn't transform the message
1217  *
1218  * @param $key String
1219  * @return String
1220  */
1221 function wfMsgNoTrans( $key ) {
1222         $args = func_get_args();
1223         array_shift( $args );
1224         return wfMsgReal( $key, $args, true, false, false );
1225 }
1226
1227 /**
1228  * Get a message from anywhere, for the current global language
1229  * set with $wgLanguageCode.
1230  *
1231  * Use this if the message should NOT change dependent on the
1232  * language set in the user's preferences. This is the case for
1233  * most text written into logs, as well as link targets (such as
1234  * the name of the copyright policy page). Link titles, on the
1235  * other hand, should be shown in the UI language.
1236  *
1237  * Note that MediaWiki allows users to change the user interface
1238  * language in their preferences, but a single installation
1239  * typically only contains content in one language.
1240  *
1241  * Be wary of this distinction: If you use wfMsg() where you should
1242  * use wfMsgForContent(), a user of the software may have to
1243  * customize potentially hundreds of messages in
1244  * order to, e.g., fix a link in every possible language.
1245  *
1246  * @param $key String: lookup key for the message, usually
1247  *     defined in languages/Language.php
1248  * @return String
1249  */
1250 function wfMsgForContent( $key ) {
1251         global $wgForceUIMsgAsContentMsg;
1252         $args = func_get_args();
1253         array_shift( $args );
1254         $forcontent = true;
1255         if( is_array( $wgForceUIMsgAsContentMsg ) &&
1256                 in_array( $key, $wgForceUIMsgAsContentMsg ) )
1257         {
1258                 $forcontent = false;
1259         }
1260         return wfMsgReal( $key, $args, true, $forcontent );
1261 }
1262
1263 /**
1264  * Same as above except doesn't transform the message
1265  *
1266  * @param $key String
1267  * @return String
1268  */
1269 function wfMsgForContentNoTrans( $key ) {
1270         global $wgForceUIMsgAsContentMsg;
1271         $args = func_get_args();
1272         array_shift( $args );
1273         $forcontent = true;
1274         if( is_array( $wgForceUIMsgAsContentMsg ) &&
1275                 in_array( $key, $wgForceUIMsgAsContentMsg ) )
1276         {
1277                 $forcontent = false;
1278         }
1279         return wfMsgReal( $key, $args, true, $forcontent, false );
1280 }
1281
1282 /**
1283  * Really get a message
1284  *
1285  * @param $key String: key to get.
1286  * @param $args
1287  * @param $useDB Boolean
1288  * @param $forContent Mixed: Language code, or false for user lang, true for content lang.
1289  * @param $transform Boolean: Whether or not to transform the message.
1290  * @return String: the requested message.
1291  */
1292 function wfMsgReal( $key, $args, $useDB = true, $forContent = false, $transform = true ) {
1293         wfProfileIn( __METHOD__ );
1294         $message = wfMsgGetKey( $key, $useDB, $forContent, $transform );
1295         $message = wfMsgReplaceArgs( $message, $args );
1296         wfProfileOut( __METHOD__ );
1297         return $message;
1298 }
1299
1300 /**
1301  * Fetch a message string value, but don't replace any keys yet.
1302  *
1303  * @param $key String
1304  * @param $useDB Bool
1305  * @param $langCode String: Code of the language to get the message for, or
1306  *                  behaves as a content language switch if it is a boolean.
1307  * @param $transform Boolean: whether to parse magic words, etc.
1308  * @return string
1309  */
1310 function wfMsgGetKey( $key, $useDB = true, $langCode = false, $transform = true ) {
1311         wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) );
1312
1313         $cache = MessageCache::singleton();
1314         $message = $cache->get( $key, $useDB, $langCode );
1315         if( $message === false ) {
1316                 $message = '&lt;' . htmlspecialchars( $key ) . '&gt;';
1317         } elseif ( $transform ) {
1318                 $message = $cache->transform( $message );
1319         }
1320         return $message;
1321 }
1322
1323 /**
1324  * Replace message parameter keys on the given formatted output.
1325  *
1326  * @param $message String
1327  * @param $args Array
1328  * @return string
1329  * @private
1330  */
1331 function wfMsgReplaceArgs( $message, $args ) {
1332         # Fix windows line-endings
1333         # Some messages are split with explode("\n", $msg)
1334         $message = str_replace( "\r", '', $message );
1335
1336         // Replace arguments
1337         if ( count( $args ) ) {
1338                 if ( is_array( $args[0] ) ) {
1339                         $args = array_values( $args[0] );
1340                 }
1341                 $replacementKeys = array();
1342                 foreach( $args as $n => $param ) {
1343                         $replacementKeys['$' . ( $n + 1 )] = $param;
1344                 }
1345                 $message = strtr( $message, $replacementKeys );
1346         }
1347
1348         return $message;
1349 }
1350
1351 /**
1352  * Return an HTML-escaped version of a message.
1353  * Parameter replacements, if any, are done *after* the HTML-escaping,
1354  * so parameters may contain HTML (eg links or form controls). Be sure
1355  * to pre-escape them if you really do want plaintext, or just wrap
1356  * the whole thing in htmlspecialchars().
1357  *
1358  * @param $key String
1359  * @param string ... parameters
1360  * @return string
1361  */
1362 function wfMsgHtml( $key ) {
1363         $args = func_get_args();
1364         array_shift( $args );
1365         return wfMsgReplaceArgs( htmlspecialchars( wfMsgGetKey( $key ) ), $args );
1366 }
1367
1368 /**
1369  * Return an HTML version of message
1370  * Parameter replacements, if any, are done *after* parsing the wiki-text message,
1371  * so parameters may contain HTML (eg links or form controls). Be sure
1372  * to pre-escape them if you really do want plaintext, or just wrap
1373  * the whole thing in htmlspecialchars().
1374  *
1375  * @param $key String
1376  * @param string ... parameters
1377  * @return string
1378  */
1379 function wfMsgWikiHtml( $key ) {
1380         $args = func_get_args();
1381         array_shift( $args );
1382         return wfMsgReplaceArgs(
1383                 MessageCache::singleton()->parse( wfMsgGetKey( $key ), null,
1384                 /* can't be set to false */ true, /* interface */ true )->getText(),
1385                 $args );
1386 }
1387
1388 /**
1389  * Returns message in the requested format
1390  * @param $key String: key of the message
1391  * @param $options Array: processing rules. Can take the following options:
1392  *   <i>parse</i>: parses wikitext to HTML
1393  *   <i>parseinline</i>: parses wikitext to HTML and removes the surrounding
1394  *       p's added by parser or tidy
1395  *   <i>escape</i>: filters message through htmlspecialchars
1396  *   <i>escapenoentities</i>: same, but allows entity references like &#160; through
1397  *   <i>replaceafter</i>: parameters are substituted after parsing or escaping
1398  *   <i>parsemag</i>: transform the message using magic phrases
1399  *   <i>content</i>: fetch message for content language instead of interface
1400  * Also can accept a single associative argument, of the form 'language' => 'xx':
1401  *   <i>language</i>: Language object or language code to fetch message for
1402  *       (overriden by <i>content</i>).
1403  * Behavior for conflicting options (e.g., parse+parseinline) is undefined.
1404  *
1405  * @return String
1406  */
1407 function wfMsgExt( $key, $options ) {
1408         $args = func_get_args();
1409         array_shift( $args );
1410         array_shift( $args );
1411         $options = (array)$options;
1412
1413         foreach( $options as $arrayKey => $option ) {
1414                 if( !preg_match( '/^[0-9]+|language$/', $arrayKey ) ) {
1415                         # An unknown index, neither numeric nor "language"
1416                         wfWarn( "wfMsgExt called with incorrect parameter key $arrayKey", 1, E_USER_WARNING );
1417                 } elseif( preg_match( '/^[0-9]+$/', $arrayKey ) && !in_array( $option,
1418                 array( 'parse', 'parseinline', 'escape', 'escapenoentities',
1419                 'replaceafter', 'parsemag', 'content' ) ) ) {
1420                         # A numeric index with unknown value
1421                         wfWarn( "wfMsgExt called with incorrect parameter $option", 1, E_USER_WARNING );
1422                 }
1423         }
1424
1425         if( in_array( 'content', $options, true ) ) {
1426                 $forContent = true;
1427                 $langCode = true;
1428                 $langCodeObj = null;
1429         } elseif( array_key_exists( 'language', $options ) ) {
1430                 $forContent = false;
1431                 $langCode = wfGetLangObj( $options['language'] );
1432                 $langCodeObj = $langCode;
1433         } else {
1434                 $forContent = false;
1435                 $langCode = false;
1436                 $langCodeObj = null;
1437         }
1438
1439         $string = wfMsgGetKey( $key, /*DB*/true, $langCode, /*Transform*/false );
1440
1441         if( !in_array( 'replaceafter', $options, true ) ) {
1442                 $string = wfMsgReplaceArgs( $string, $args );
1443         }
1444
1445         $messageCache = MessageCache::singleton();
1446         if( in_array( 'parse', $options, true ) ) {
1447                 $string = $messageCache->parse( $string, null, true, !$forContent, $langCodeObj )->getText();
1448         } elseif ( in_array( 'parseinline', $options, true ) ) {
1449                 $string = $messageCache->parse( $string, null, true, !$forContent, $langCodeObj )->getText();
1450                 $m = array();
1451                 if( preg_match( '/^<p>(.*)\n?<\/p>\n?$/sU', $string, $m ) ) {
1452                         $string = $m[1];
1453                 }
1454         } elseif ( in_array( 'parsemag', $options, true ) ) {
1455                 $string = $messageCache->transform( $string,
1456                                 !$forContent, $langCodeObj );
1457         }
1458
1459         if ( in_array( 'escape', $options, true ) ) {
1460                 $string = htmlspecialchars ( $string );
1461         } elseif ( in_array( 'escapenoentities', $options, true ) ) {
1462                 $string = Sanitizer::escapeHtmlAllowEntities( $string );
1463         }
1464
1465         if( in_array( 'replaceafter', $options, true ) ) {
1466                 $string = wfMsgReplaceArgs( $string, $args );
1467         }
1468
1469         return $string;
1470 }
1471
1472 /**
1473  * Since wfMsg() and co suck, they don't return false if the message key they
1474  * looked up didn't exist but a XHTML string, this function checks for the
1475  * nonexistance of messages by checking the MessageCache::get() result directly.
1476  *
1477  * @param $key      String: the message key looked up
1478  * @return Boolean True if the message *doesn't* exist.
1479  */
1480 function wfEmptyMsg( $key ) {
1481         return MessageCache::singleton()->get( $key, /*useDB*/true, /*content*/false ) === false;
1482 }
1483
1484 /**
1485  * Throw a debugging exception. This function previously once exited the process,
1486  * but now throws an exception instead, with similar results.
1487  *
1488  * @param $msg String: message shown when dying.
1489  */
1490 function wfDebugDieBacktrace( $msg = '' ) {
1491         throw new MWException( $msg );
1492 }
1493
1494 /**
1495  * Fetch server name for use in error reporting etc.
1496  * Use real server name if available, so we know which machine
1497  * in a server farm generated the current page.
1498  *
1499  * @return string
1500  */
1501 function wfHostname() {
1502         static $host;
1503         if ( is_null( $host ) ) {
1504                 if ( function_exists( 'posix_uname' ) ) {
1505                         // This function not present on Windows
1506                         $uname = posix_uname();
1507                 } else {
1508                         $uname = false;
1509                 }
1510                 if( is_array( $uname ) && isset( $uname['nodename'] ) ) {
1511                         $host = $uname['nodename'];
1512                 } elseif ( getenv( 'COMPUTERNAME' ) ) {
1513                         # Windows computer name
1514                         $host = getenv( 'COMPUTERNAME' );
1515                 } else {
1516                         # This may be a virtual server.
1517                         $host = $_SERVER['SERVER_NAME'];
1518                 }
1519         }
1520         return $host;
1521 }
1522
1523 /**
1524  * Returns a HTML comment with the elapsed time since request.
1525  * This method has no side effects.
1526  *
1527  * @return string
1528  */
1529 function wfReportTime() {
1530         global $wgRequestTime, $wgShowHostnames;
1531
1532         $now = wfTime();
1533         $elapsed = $now - $wgRequestTime;
1534
1535         return $wgShowHostnames
1536                 ? sprintf( '<!-- Served by %s in %01.3f secs. -->', wfHostname(), $elapsed )
1537                 : sprintf( '<!-- Served in %01.3f secs. -->', $elapsed );
1538 }
1539
1540 /**
1541  * Safety wrapper for debug_backtrace().
1542  *
1543  * With Zend Optimizer 3.2.0 loaded, this causes segfaults under somewhat
1544  * murky circumstances, which may be triggered in part by stub objects
1545  * or other fancy talkin'.
1546  *
1547  * Will return an empty array if Zend Optimizer is detected or if
1548  * debug_backtrace is disabled, otherwise the output from
1549  * debug_backtrace() (trimmed).
1550  *
1551  * @param $limit int This parameter can be used to limit the number of stack frames returned
1552  *
1553  * @return array of backtrace information
1554  */
1555 function wfDebugBacktrace( $limit = 0 ) {
1556         static $disabled = null;
1557
1558         if( extension_loaded( 'Zend Optimizer' ) ) {
1559                 wfDebug( "Zend Optimizer detected; skipping debug_backtrace for safety.\n" );
1560                 return array();
1561         }
1562
1563         if ( is_null( $disabled ) ) {
1564                 $disabled = false;
1565                 $functions = explode( ',', ini_get( 'disable_functions' ) );
1566                 $functions = array_map( 'trim', $functions );
1567                 $functions = array_map( 'strtolower', $functions );
1568                 if ( in_array( 'debug_backtrace', $functions ) ) {
1569                         wfDebug( "debug_backtrace is in disabled_functions\n" );
1570                         $disabled = true;
1571                 }
1572         }
1573         if ( $disabled ) {
1574                 return array();
1575         }
1576
1577         if ( $limit && version_compare( PHP_VERSION, '5.4.0', '>=' ) ) {
1578                 return array_slice( debug_backtrace( DEBUG_BACKTRACE_PROVIDE_OBJECT, $limit ), 1 );
1579         } else {
1580                 return array_slice( debug_backtrace(), 1 );
1581         }
1582 }
1583
1584 /**
1585  * Get a debug backtrace as a string
1586  *
1587  * @return string
1588  */
1589 function wfBacktrace() {
1590         global $wgCommandLineMode;
1591
1592         if ( $wgCommandLineMode ) {
1593                 $msg = '';
1594         } else {
1595                 $msg = "<ul>\n";
1596         }
1597         $backtrace = wfDebugBacktrace();
1598         foreach( $backtrace as $call ) {
1599                 if( isset( $call['file'] ) ) {
1600                         $f = explode( DIRECTORY_SEPARATOR, $call['file'] );
1601                         $file = $f[count( $f ) - 1];
1602                 } else {
1603                         $file = '-';
1604                 }
1605                 if( isset( $call['line'] ) ) {
1606                         $line = $call['line'];
1607                 } else {
1608                         $line = '-';
1609                 }
1610                 if ( $wgCommandLineMode ) {
1611                         $msg .= "$file line $line calls ";
1612                 } else {
1613                         $msg .= '<li>' . $file . ' line ' . $line . ' calls ';
1614                 }
1615                 if( !empty( $call['class'] ) ) {
1616                         $msg .= $call['class'] . $call['type'];
1617                 }
1618                 $msg .= $call['function'] . '()';
1619
1620                 if ( $wgCommandLineMode ) {
1621                         $msg .= "\n";
1622                 } else {
1623                         $msg .= "</li>\n";
1624                 }
1625         }
1626         if ( $wgCommandLineMode ) {
1627                 $msg .= "\n";
1628         } else {
1629                 $msg .= "</ul>\n";
1630         }
1631
1632         return $msg;
1633 }
1634
1635 /**
1636  * Get the name of the function which called this function
1637  *
1638  * @param $level Int
1639  * @return Bool|string
1640  */
1641 function wfGetCaller( $level = 2 ) {
1642         $backtrace = wfDebugBacktrace( $level );
1643         if ( isset( $backtrace[$level] ) ) {
1644                 return wfFormatStackFrame( $backtrace[$level] );
1645         } else {
1646                 $caller = 'unknown';
1647         }
1648         return $caller;
1649 }
1650
1651 /**
1652  * Return a string consisting of callers in the stack. Useful sometimes
1653  * for profiling specific points.
1654  *
1655  * @param $limit The maximum depth of the stack frame to return, or false for
1656  *               the entire stack.
1657  * @return String
1658  */
1659 function wfGetAllCallers( $limit = 3 ) {
1660         $trace = array_reverse( wfDebugBacktrace() );
1661         if ( !$limit || $limit > count( $trace ) - 1 ) {
1662                 $limit = count( $trace ) - 1;
1663         }
1664         $trace = array_slice( $trace, -$limit - 1, $limit );
1665         return implode( '/', array_map( 'wfFormatStackFrame', $trace ) );
1666 }
1667
1668 /**
1669  * Return a string representation of frame
1670  *
1671  * @param $frame Array
1672  * @return Bool
1673  */
1674 function wfFormatStackFrame( $frame ) {
1675         return isset( $frame['class'] ) ?
1676                 $frame['class'] . '::' . $frame['function'] :
1677                 $frame['function'];
1678 }
1679
1680
1681 /* Some generic result counters, pulled out of SearchEngine */
1682
1683
1684 /**
1685  * @todo document
1686  *
1687  * @param $offset Int
1688  * @param $limit Int
1689  * @return String
1690  */
1691 function wfShowingResults( $offset, $limit ) {
1692         global $wgLang;
1693         return wfMsgExt(
1694                 'showingresults',
1695                 array( 'parseinline' ),
1696                 $wgLang->formatNum( $limit ),
1697                 $wgLang->formatNum( $offset + 1 )
1698         );
1699 }
1700
1701 /**
1702  * Generate (prev x| next x) (20|50|100...) type links for paging
1703  *
1704  * @param $offset String
1705  * @param $limit Integer
1706  * @param $link String
1707  * @param $query String: optional URL query parameter string
1708  * @param $atend Bool: optional param for specified if this is the last page
1709  * @return String
1710  * @deprecated in 1.19; use Language::viewPrevNext() instead
1711  */
1712 function wfViewPrevNext( $offset, $limit, $link, $query = '', $atend = false ) {
1713         wfDeprecated( __METHOD__, '1.19' );
1714
1715         global $wgLang;
1716
1717         $query = wfCgiToArray( $query );
1718
1719         if( is_object( $link ) ) {
1720                 $title = $link;
1721         } else {
1722                 $title = Title::newFromText( $link );
1723                 if( is_null( $title ) ) {
1724                         return false;
1725                 }
1726         }
1727
1728         return $wgLang->viewPrevNext( $title, $offset, $limit, $query, $atend );
1729 }
1730
1731 /**
1732  * Make a list item, used by various special pages
1733  *
1734  * @param $page String Page link
1735  * @param $details String Text between brackets
1736  * @param $oppositedm Boolean   Add the direction mark opposite to your
1737  *                                                              language, to display text properly
1738  * @return String
1739  * @deprecated since 1.19; use Language::specialList() instead
1740  */
1741 function wfSpecialList( $page, $details, $oppositedm = true ) {
1742         global $wgLang;
1743         return $wgLang->specialList( $page, $details, $oppositedm );
1744 }
1745
1746 /**
1747  * @todo document
1748  * @todo FIXME: We may want to blacklist some broken browsers
1749  *
1750  * @param $force Bool
1751  * @return bool Whereas client accept gzip compression
1752  */
1753 function wfClientAcceptsGzip( $force = false ) {
1754         static $result = null;
1755         if ( $result === null || $force ) {
1756                 $result = false;
1757                 if( isset( $_SERVER['HTTP_ACCEPT_ENCODING'] ) ) {
1758                         # @todo FIXME: We may want to blacklist some broken browsers
1759                         $m = array();
1760                         if( preg_match(
1761                                 '/\bgzip(?:;(q)=([0-9]+(?:\.[0-9]+)))?\b/',
1762                                 $_SERVER['HTTP_ACCEPT_ENCODING'],
1763                                 $m )
1764                         )
1765                         {
1766                                 if( isset( $m[2] ) && ( $m[1] == 'q' ) && ( $m[2] == 0 ) ) {
1767                                         $result = false;
1768                                         return $result;
1769                                 }
1770                                 wfDebug( "wfClientAcceptsGzip: client accepts gzip.\n" );
1771                                 $result = true;
1772                         }
1773                 }
1774         }
1775         return $result;
1776 }
1777
1778 /**
1779  * Obtain the offset and limit values from the request string;
1780  * used in special pages
1781  *
1782  * @param $deflimit Int default limit if none supplied
1783  * @param $optionname String Name of a user preference to check against
1784  * @return array
1785  *
1786  */
1787 function wfCheckLimits( $deflimit = 50, $optionname = 'rclimit' ) {
1788         global $wgRequest;
1789         return $wgRequest->getLimitOffset( $deflimit, $optionname );
1790 }
1791
1792 /**
1793  * Escapes the given text so that it may be output using addWikiText()
1794  * without any linking, formatting, etc. making its way through. This
1795  * is achieved by substituting certain characters with HTML entities.
1796  * As required by the callers, <nowiki> is not used.
1797  *
1798  * @param $text String: text to be escaped
1799  * @return String
1800  */
1801 function wfEscapeWikiText( $text ) {
1802         $text = strtr( "\n$text", array(
1803                 '"' => '&#34;', '&' => '&#38;', "'" => '&#39;', '<' => '&#60;',
1804                 '=' => '&#61;', '>' => '&#62;', '[' => '&#91;', ']' => '&#93;',
1805                 '{' => '&#123;', '|' => '&#124;', '}' => '&#125;',
1806                 "\n#" => "\n&#35;", "\n*" => "\n&#42;",
1807                 "\n:" => "\n&#58;", "\n;" => "\n&#59;",
1808                 '://' => '&#58;//', 'ISBN ' => 'ISBN&#32;', 'RFC ' => 'RFC&#32;',
1809         ) );
1810         return substr( $text, 1 );
1811 }
1812
1813 /**
1814  * Get the current unix timetstamp with microseconds.  Useful for profiling
1815  * @return Float
1816  */
1817 function wfTime() {
1818         return microtime( true );
1819 }
1820
1821 /**
1822  * Sets dest to source and returns the original value of dest
1823  * If source is NULL, it just returns the value, it doesn't set the variable
1824  * If force is true, it will set the value even if source is NULL
1825  *
1826  * @param $dest Mixed
1827  * @param $source Mixed
1828  * @param $force Bool
1829  * @return Mixed
1830  */
1831 function wfSetVar( &$dest, $source, $force = false ) {
1832         $temp = $dest;
1833         if ( !is_null( $source ) || $force ) {
1834                 $dest = $source;
1835         }
1836         return $temp;
1837 }
1838
1839 /**
1840  * As for wfSetVar except setting a bit
1841  *
1842  * @param $dest Int
1843  * @param $bit Int
1844  * @param $state Bool
1845  *
1846  * @return bool
1847  */
1848 function wfSetBit( &$dest, $bit, $state = true ) {
1849         $temp = (bool)( $dest & $bit );
1850         if ( !is_null( $state ) ) {
1851                 if ( $state ) {
1852                         $dest |= $bit;
1853                 } else {
1854                         $dest &= ~$bit;
1855                 }
1856         }
1857         return $temp;
1858 }
1859
1860 /**
1861  * A wrapper around the PHP function var_export().
1862  * Either print it or add it to the regular output ($wgOut).
1863  *
1864  * @param $var A PHP variable to dump.
1865  */
1866 function wfVarDump( $var ) {
1867         global $wgOut;
1868         $s = str_replace( "\n", "<br />\n", var_export( $var, true ) . "\n" );
1869         if ( headers_sent() || !isset( $wgOut ) || !is_object( $wgOut ) ) {
1870                 print $s;
1871         } else {
1872                 $wgOut->addHTML( $s );
1873         }
1874 }
1875
1876 /**
1877  * Provide a simple HTTP error.
1878  *
1879  * @param $code Int|String
1880  * @param $label String
1881  * @param $desc String
1882  */
1883 function wfHttpError( $code, $label, $desc ) {
1884         global $wgOut;
1885         $wgOut->disable();
1886         header( "HTTP/1.0 $code $label" );
1887         header( "Status: $code $label" );
1888         $wgOut->sendCacheControl();
1889
1890         header( 'Content-type: text/html; charset=utf-8' );
1891         print "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">".
1892                 '<html><head><title>' .
1893                 htmlspecialchars( $label ) .
1894                 '</title></head><body><h1>' .
1895                 htmlspecialchars( $label ) .
1896                 '</h1><p>' .
1897                 nl2br( htmlspecialchars( $desc ) ) .
1898                 "</p></body></html>\n";
1899 }
1900
1901 /**
1902  * Clear away any user-level output buffers, discarding contents.
1903  *
1904  * Suitable for 'starting afresh', for instance when streaming
1905  * relatively large amounts of data without buffering, or wanting to
1906  * output image files without ob_gzhandler's compression.
1907  *
1908  * The optional $resetGzipEncoding parameter controls suppression of
1909  * the Content-Encoding header sent by ob_gzhandler; by default it
1910  * is left. See comments for wfClearOutputBuffers() for why it would
1911  * be used.
1912  *
1913  * Note that some PHP configuration options may add output buffer
1914  * layers which cannot be removed; these are left in place.
1915  *
1916  * @param $resetGzipEncoding Bool
1917  */
1918 function wfResetOutputBuffers( $resetGzipEncoding = true ) {
1919         if( $resetGzipEncoding ) {
1920                 // Suppress Content-Encoding and Content-Length
1921                 // headers from 1.10+s wfOutputHandler
1922                 global $wgDisableOutputCompression;
1923                 $wgDisableOutputCompression = true;
1924         }
1925         while( $status = ob_get_status() ) {
1926                 if( $status['type'] == 0 /* PHP_OUTPUT_HANDLER_INTERNAL */ ) {
1927                         // Probably from zlib.output_compression or other
1928                         // PHP-internal setting which can't be removed.
1929                         //
1930                         // Give up, and hope the result doesn't break
1931                         // output behavior.
1932                         break;
1933                 }
1934                 if( !ob_end_clean() ) {
1935                         // Could not remove output buffer handler; abort now
1936                         // to avoid getting in some kind of infinite loop.
1937                         break;
1938                 }
1939                 if( $resetGzipEncoding ) {
1940                         if( $status['name'] == 'ob_gzhandler' ) {
1941                                 // Reset the 'Content-Encoding' field set by this handler
1942                                 // so we can start fresh.
1943                                 if ( function_exists( 'header_remove' ) ) {
1944                                         // Available since PHP 5.3.0
1945                                         header_remove( 'Content-Encoding' );
1946                                 } else {
1947                                         // We need to provide a valid content-coding. See bug 28069
1948                                         header( 'Content-Encoding: identity' );
1949                                 }
1950                                 break;
1951                         }
1952                 }
1953         }
1954 }
1955
1956 /**
1957  * More legible than passing a 'false' parameter to wfResetOutputBuffers():
1958  *
1959  * Clear away output buffers, but keep the Content-Encoding header
1960  * produced by ob_gzhandler, if any.
1961  *
1962  * This should be used for HTTP 304 responses, where you need to
1963  * preserve the Content-Encoding header of the real result, but
1964  * also need to suppress the output of ob_gzhandler to keep to spec
1965  * and avoid breaking Firefox in rare cases where the headers and
1966  * body are broken over two packets.
1967  */
1968 function wfClearOutputBuffers() {
1969         wfResetOutputBuffers( false );
1970 }
1971
1972 /**
1973  * Converts an Accept-* header into an array mapping string values to quality
1974  * factors
1975  *
1976  * @param $accept String
1977  * @param $def String default
1978  * @return Array
1979  */
1980 function wfAcceptToPrefs( $accept, $def = '*/*' ) {
1981         # No arg means accept anything (per HTTP spec)
1982         if( !$accept ) {
1983                 return array( $def => 1.0 );
1984         }
1985
1986         $prefs = array();
1987
1988         $parts = explode( ',', $accept );
1989
1990         foreach( $parts as $part ) {
1991                 # @todo FIXME: Doesn't deal with params like 'text/html; level=1'
1992                 $values = explode( ';', trim( $part ) );
1993                 $match = array();
1994                 if ( count( $values ) == 1 ) {
1995                         $prefs[$values[0]] = 1.0;
1996                 } elseif ( preg_match( '/q\s*=\s*(\d*\.\d+)/', $values[1], $match ) ) {
1997                         $prefs[$values[0]] = floatval( $match[1] );
1998                 }
1999         }
2000
2001         return $prefs;
2002 }
2003
2004 /**
2005  * Checks if a given MIME type matches any of the keys in the given
2006  * array. Basic wildcards are accepted in the array keys.
2007  *
2008  * Returns the matching MIME type (or wildcard) if a match, otherwise
2009  * NULL if no match.
2010  *
2011  * @param $type String
2012  * @param $avail Array
2013  * @return string
2014  * @private
2015  */
2016 function mimeTypeMatch( $type, $avail ) {
2017         if( array_key_exists( $type, $avail ) ) {
2018                 return $type;
2019         } else {
2020                 $parts = explode( '/', $type );
2021                 if( array_key_exists( $parts[0] . '/*', $avail ) ) {
2022                         return $parts[0] . '/*';
2023                 } elseif( array_key_exists( '*/*', $avail ) ) {
2024                         return '*/*';
2025                 } else {
2026                         return null;
2027                 }
2028         }
2029 }
2030
2031 /**
2032  * Returns the 'best' match between a client's requested internet media types
2033  * and the server's list of available types. Each list should be an associative
2034  * array of type to preference (preference is a float between 0.0 and 1.0).
2035  * Wildcards in the types are acceptable.
2036  *
2037  * @param $cprefs Array: client's acceptable type list
2038  * @param $sprefs Array: server's offered types
2039  * @return string
2040  *
2041  * @todo FIXME: Doesn't handle params like 'text/plain; charset=UTF-8'
2042  * XXX: generalize to negotiate other stuff
2043  */
2044 function wfNegotiateType( $cprefs, $sprefs ) {
2045         $combine = array();
2046
2047         foreach( array_keys( $sprefs ) as $type ) {
2048                 $parts = explode( '/', $type );
2049                 if( $parts[1] != '*' ) {
2050                         $ckey = mimeTypeMatch( $type, $cprefs );
2051                         if( $ckey ) {
2052                                 $combine[$type] = $sprefs[$type] * $cprefs[$ckey];
2053                         }
2054                 }
2055         }
2056
2057         foreach( array_keys( $cprefs ) as $type ) {
2058                 $parts = explode( '/', $type );
2059                 if( $parts[1] != '*' && !array_key_exists( $type, $sprefs ) ) {
2060                         $skey = mimeTypeMatch( $type, $sprefs );
2061                         if( $skey ) {
2062                                 $combine[$type] = $sprefs[$skey] * $cprefs[$type];
2063                         }
2064                 }
2065         }
2066
2067         $bestq = 0;
2068         $besttype = null;
2069
2070         foreach( array_keys( $combine ) as $type ) {
2071                 if( $combine[$type] > $bestq ) {
2072                         $besttype = $type;
2073                         $bestq = $combine[$type];
2074                 }
2075         }
2076
2077         return $besttype;
2078 }
2079
2080 /**
2081  * Reference-counted warning suppression
2082  *
2083  * @param $end Bool
2084  */
2085 function wfSuppressWarnings( $end = false ) {
2086         static $suppressCount = 0;
2087         static $originalLevel = false;
2088
2089         if ( $end ) {
2090                 if ( $suppressCount ) {
2091                         --$suppressCount;
2092                         if ( !$suppressCount ) {
2093                                 error_reporting( $originalLevel );
2094                         }
2095                 }
2096         } else {
2097                 if ( !$suppressCount ) {
2098                         // E_DEPRECATED is undefined in PHP 5.2
2099                         if( !defined( 'E_DEPRECATED' ) ) {
2100                                 define( 'E_DEPRECATED', 8192 );
2101                         }
2102                         $originalLevel = error_reporting( E_ALL & ~( E_WARNING | E_NOTICE | E_USER_WARNING | E_USER_NOTICE | E_DEPRECATED ) );
2103                 }
2104                 ++$suppressCount;
2105         }
2106 }
2107
2108 /**
2109  * Restore error level to previous value
2110  */
2111 function wfRestoreWarnings() {
2112         wfSuppressWarnings( true );
2113 }
2114
2115 # Autodetect, convert and provide timestamps of various types
2116
2117 /**
2118  * Unix time - the number of seconds since 1970-01-01 00:00:00 UTC
2119  */
2120 define( 'TS_UNIX', 0 );
2121
2122 /**
2123  * MediaWiki concatenated string timestamp (YYYYMMDDHHMMSS)
2124  */
2125 define( 'TS_MW', 1 );
2126
2127 /**
2128  * MySQL DATETIME (YYYY-MM-DD HH:MM:SS)
2129  */
2130 define( 'TS_DB', 2 );
2131
2132 /**
2133  * RFC 2822 format, for E-mail and HTTP headers
2134  */
2135 define( 'TS_RFC2822', 3 );
2136
2137 /**
2138  * ISO 8601 format with no timezone: 1986-02-09T20:00:00Z
2139  *
2140  * This is used by Special:Export
2141  */
2142 define( 'TS_ISO_8601', 4 );
2143
2144 /**
2145  * An Exif timestamp (YYYY:MM:DD HH:MM:SS)
2146  *
2147  * @see http://exif.org/Exif2-2.PDF The Exif 2.2 spec, see page 28 for the
2148  *       DateTime tag and page 36 for the DateTimeOriginal and
2149  *       DateTimeDigitized tags.
2150  */
2151 define( 'TS_EXIF', 5 );
2152
2153 /**
2154  * Oracle format time.
2155  */
2156 define( 'TS_ORACLE', 6 );
2157
2158 /**
2159  * Postgres format time.
2160  */
2161 define( 'TS_POSTGRES', 7 );
2162
2163 /**
2164  * DB2 format time
2165  */
2166 define( 'TS_DB2', 8 );
2167
2168 /**
2169  * ISO 8601 basic format with no timezone: 19860209T200000Z.  This is used by ResourceLoader
2170  */
2171 define( 'TS_ISO_8601_BASIC', 9 );
2172
2173 /**
2174  * Get a timestamp string in one of various formats
2175  *
2176  * @param $outputtype Mixed: A timestamp in one of the supported formats, the
2177  *                    function will autodetect which format is supplied and act
2178  *                    accordingly.
2179  * @param $ts Mixed: the timestamp to convert or 0 for the current timestamp
2180  * @return Mixed: String / false The same date in the format specified in $outputtype or false
2181  */
2182 function wfTimestamp( $outputtype = TS_UNIX, $ts = 0 ) {
2183         $uts = 0;
2184         $da = array();
2185         $strtime = '';
2186
2187         if ( !$ts ) { // We want to catch 0, '', null... but not date strings starting with a letter.
2188                 $uts = time();
2189                 $strtime = "@$uts";
2190         } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)$/D', $ts, $da ) ) {
2191                 # TS_DB
2192         } elseif ( preg_match( '/^(\d{4}):(\d\d):(\d\d) (\d\d):(\d\d):(\d\d)$/D', $ts, $da ) ) {
2193                 # TS_EXIF
2194         } elseif ( preg_match( '/^(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)$/D', $ts, $da ) ) {
2195                 # TS_MW
2196         } elseif ( preg_match( '/^-?\d{1,13}$/D', $ts ) ) {
2197                 # TS_UNIX
2198                 $uts = $ts;
2199                 $strtime = "@$ts"; // http://php.net/manual/en/datetime.formats.compound.php
2200         } elseif ( preg_match( '/^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}.\d{6}$/', $ts ) ) {
2201                 # TS_ORACLE // session altered to DD-MM-YYYY HH24:MI:SS.FF6
2202                 $strtime = preg_replace( '/(\d\d)\.(\d\d)\.(\d\d)(\.(\d+))?/', "$1:$2:$3",
2203                                 str_replace( '+00:00', 'UTC', $ts ) );
2204         } elseif ( preg_match( '/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.*\d*)?Z$/', $ts, $da ) ) {
2205                 # TS_ISO_8601
2206         } elseif ( preg_match( '/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(?:\.*\d*)?Z$/', $ts, $da ) ) {
2207                 #TS_ISO_8601_BASIC
2208         } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.*\d*[\+\- ](\d\d)$/', $ts, $da ) ) {
2209                 # TS_POSTGRES
2210         } elseif ( preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.*\d* GMT$/', $ts, $da ) ) {
2211                 # TS_POSTGRES
2212         } elseif (preg_match( '/^(\d{4})\-(\d\d)\-(\d\d) (\d\d):(\d\d):(\d\d)\.\d\d\d$/', $ts, $da ) ) {
2213                 # TS_DB2
2214         } elseif ( preg_match( '/^[ \t\r\n]*([A-Z][a-z]{2},[ \t\r\n]*)?' . # Day of week
2215                                                         '\d\d?[ \t\r\n]*[A-Z][a-z]{2}[ \t\r\n]*\d{2}(?:\d{2})?' .  # dd Mon yyyy
2216                                                         '[ \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
2217                 # TS_RFC2822, accepting a trailing comment. See http://www.squid-cache.org/mail-archive/squid-users/200307/0122.html / r77171
2218                 # The regex is a superset of rfc2822 for readability
2219                 $strtime = strtok( $ts, ';' );
2220         } 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 ) ) {
2221                 # TS_RFC850
2222                 $strtime = $ts;
2223         } 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 ) ) {
2224                 # asctime
2225                 $strtime = $ts;
2226         } else {
2227                 # Bogus value...
2228                 wfDebug("wfTimestamp() fed bogus time value: TYPE=$outputtype; VALUE=$ts\n");
2229
2230                 return false;
2231         }
2232
2233         static $formats = array(
2234                 TS_UNIX => 'U',
2235                 TS_MW => 'YmdHis',
2236                 TS_DB => 'Y-m-d H:i:s',
2237                 TS_ISO_8601 => 'Y-m-d\TH:i:s\Z',
2238                 TS_ISO_8601_BASIC => 'Ymd\THis\Z',
2239                 TS_EXIF => 'Y:m:d H:i:s', // This shouldn't ever be used, but is included for completeness
2240                 TS_RFC2822 => 'D, d M Y H:i:s',
2241                 TS_ORACLE => 'd-m-Y H:i:s.000000', // Was 'd-M-y h.i.s A' . ' +00:00' before r51500
2242                 TS_POSTGRES => 'Y-m-d H:i:s',
2243                 TS_DB2 => 'Y-m-d H:i:s',
2244         );
2245
2246         if ( !isset( $formats[$outputtype] ) ) {
2247                 throw new MWException( 'wfTimestamp() called with illegal output type.' );
2248         }
2249
2250         if ( function_exists( "date_create" ) ) {
2251                 if ( count( $da ) ) {
2252                         $ds = sprintf("%04d-%02d-%02dT%02d:%02d:%02d.00+00:00",
2253                                 (int)$da[1], (int)$da[2], (int)$da[3],
2254                                 (int)$da[4], (int)$da[5], (int)$da[6]);
2255
2256                         $d = date_create( $ds, new DateTimeZone( 'GMT' ) );
2257                 } elseif ( $strtime ) {
2258                         $d = date_create( $strtime, new DateTimeZone( 'GMT' ) );
2259                 } else {
2260                         return false;
2261                 }
2262
2263                 if ( !$d ) {
2264                         wfDebug("wfTimestamp() fed bogus time value: $outputtype; $ts\n");
2265                         return false;
2266                 }
2267
2268                 $output = $d->format( $formats[$outputtype] );
2269         } else {
2270                 if ( count( $da ) ) {
2271                         // Warning! gmmktime() acts oddly if the month or day is set to 0
2272                         // We may want to handle that explicitly at some point
2273                         $uts = gmmktime( (int)$da[4], (int)$da[5], (int)$da[6],
2274                                 (int)$da[2], (int)$da[3], (int)$da[1] );
2275                 } elseif ( $strtime ) {
2276                         $uts = strtotime( $strtime );
2277                 }
2278
2279                 if ( $uts === false ) {
2280                         wfDebug("wfTimestamp() can't parse the timestamp (non 32-bit time? Update php): $outputtype; $ts\n");
2281                         return false;
2282                 }
2283
2284                 if ( TS_UNIX == $outputtype ) {
2285                         return $uts;
2286                 }
2287                 $output = gmdate( $formats[$outputtype], $uts );
2288         }
2289
2290         if ( ( $outputtype == TS_RFC2822 ) || ( $outputtype == TS_POSTGRES ) ) {
2291                 $output .= ' GMT';
2292         }
2293
2294         return $output;
2295 }
2296
2297 /**
2298  * Return a formatted timestamp, or null if input is null.
2299  * For dealing with nullable timestamp columns in the database.
2300  *
2301  * @param $outputtype Integer
2302  * @param $ts String
2303  * @return String
2304  */
2305 function wfTimestampOrNull( $outputtype = TS_UNIX, $ts = null ) {
2306         if( is_null( $ts ) ) {
2307                 return null;
2308         } else {
2309                 return wfTimestamp( $outputtype, $ts );
2310         }
2311 }
2312
2313 /**
2314  * Convenience function; returns MediaWiki timestamp for the present time.
2315  *
2316  * @return string
2317  */
2318 function wfTimestampNow() {
2319         # return NOW
2320         return wfTimestamp( TS_MW, time() );
2321 }
2322
2323 /**
2324  * Check if the operating system is Windows
2325  *
2326  * @return Bool: true if it's Windows, False otherwise.
2327  */
2328 function wfIsWindows() {
2329         static $isWindows = null;
2330         if ( $isWindows === null ) {
2331                 $isWindows = substr( php_uname(), 0, 7 ) == 'Windows';
2332         }
2333         return $isWindows;
2334 }
2335
2336 /**
2337  * Check if we are running under HipHop
2338  *
2339  * @return Bool
2340  */
2341 function wfIsHipHop() {
2342         return function_exists( 'hphp_thread_set_warmup_enabled' );
2343 }
2344
2345 /**
2346  * Swap two variables
2347  *
2348  * @param $x Mixed
2349  * @param $y Mixed
2350  */
2351 function swap( &$x, &$y ) {
2352         $z = $x;
2353         $x = $y;
2354         $y = $z;
2355 }
2356
2357 /**
2358  * Tries to get the system directory for temporary files. The TMPDIR, TMP, and
2359  * TEMP environment variables are then checked in sequence, and if none are set
2360  * try sys_get_temp_dir() for PHP >= 5.2.1. All else fails, return /tmp for Unix
2361  * or C:\Windows\Temp for Windows and hope for the best.
2362  * It is common to call it with tempnam().
2363  *
2364  * NOTE: When possible, use instead the tmpfile() function to create
2365  * temporary files to avoid race conditions on file creation, etc.
2366  *
2367  * @return String
2368  */
2369 function wfTempDir() {
2370         foreach( array( 'TMPDIR', 'TMP', 'TEMP' ) as $var ) {
2371                 $tmp = getenv( $var );
2372                 if( $tmp && file_exists( $tmp ) && is_dir( $tmp ) && is_writable( $tmp ) ) {
2373                         return $tmp;
2374                 }
2375         }
2376         if( function_exists( 'sys_get_temp_dir' ) ) {
2377                 return sys_get_temp_dir();
2378         }
2379         # Usual defaults
2380         return wfIsWindows() ? 'C:\Windows\Temp' : '/tmp';
2381 }
2382
2383 /**
2384  * Make directory, and make all parent directories if they don't exist
2385  *
2386  * @param $dir String: full path to directory to create
2387  * @param $mode Integer: chmod value to use, default is $wgDirectoryMode
2388  * @param $caller String: optional caller param for debugging.
2389  * @return bool
2390  */
2391 function wfMkdirParents( $dir, $mode = null, $caller = null ) {
2392         global $wgDirectoryMode;
2393
2394         if ( FileBackend::isStoragePath( $dir ) ) { // sanity
2395                 throw new MWException( __FUNCTION__ . " given storage path `$dir`.");
2396         }
2397
2398         if ( !is_null( $caller ) ) {
2399                 wfDebug( "$caller: called wfMkdirParents($dir)\n" );
2400         }
2401
2402         if( strval( $dir ) === '' || file_exists( $dir ) ) {
2403                 return true;
2404         }
2405
2406         $dir = str_replace( array( '\\', '/' ), DIRECTORY_SEPARATOR, $dir );
2407
2408         if ( is_null( $mode ) ) {
2409                 $mode = $wgDirectoryMode;
2410         }
2411
2412         // Turn off the normal warning, we're doing our own below
2413         wfSuppressWarnings();
2414         $ok = mkdir( $dir, $mode, true ); // PHP5 <3
2415         wfRestoreWarnings();
2416
2417         if( !$ok ) {
2418                 // PHP doesn't report the path in its warning message, so add our own to aid in diagnosis.
2419                 trigger_error( __FUNCTION__ . ": failed to mkdir \"$dir\" mode $mode", E_USER_WARNING );
2420         }
2421         return $ok;
2422 }
2423
2424 /**
2425  * Increment a statistics counter
2426  *
2427  * @param $key String
2428  * @param $count Int
2429  */
2430 function wfIncrStats( $key, $count = 1 ) {
2431         global $wgStatsMethod;
2432
2433         $count = intval( $count );
2434
2435         if( $wgStatsMethod == 'udp' ) {
2436                 global $wgUDPProfilerHost, $wgUDPProfilerPort, $wgDBname, $wgAggregateStatsID;
2437                 static $socket;
2438
2439                 $id = $wgAggregateStatsID !== false ? $wgAggregateStatsID : $wgDBname;
2440
2441                 if ( !$socket ) {
2442                         $socket = socket_create( AF_INET, SOCK_DGRAM, SOL_UDP );
2443                         $statline = "stats/{$id} - {$count} 1 1 1 1 -total\n";
2444                         socket_sendto(
2445                                 $socket,
2446                                 $statline,
2447                                 strlen( $statline ),
2448                                 0,
2449                                 $wgUDPProfilerHost,
2450                                 $wgUDPProfilerPort
2451                         );
2452                 }
2453                 $statline = "stats/{$id} - {$count} 1 1 1 1 {$key}\n";
2454                 wfSuppressWarnings();
2455                 socket_sendto(
2456                         $socket,
2457                         $statline,
2458                         strlen( $statline ),
2459                         0,
2460                         $wgUDPProfilerHost,
2461                         $wgUDPProfilerPort
2462                 );
2463                 wfRestoreWarnings();
2464         } elseif( $wgStatsMethod == 'cache' ) {
2465                 global $wgMemc;
2466                 $key = wfMemcKey( 'stats', $key );
2467                 if ( is_null( $wgMemc->incr( $key, $count ) ) ) {
2468                         $wgMemc->add( $key, $count );
2469                 }
2470         } else {
2471                 // Disabled
2472         }
2473 }
2474
2475 /**
2476  * @param $nr Mixed: the number to format
2477  * @param $acc Integer: the number of digits after the decimal point, default 2
2478  * @param $round Boolean: whether or not to round the value, default true
2479  * @return float
2480  */
2481 function wfPercent( $nr, $acc = 2, $round = true ) {
2482         $ret = sprintf( "%.${acc}f", $nr );
2483         return $round ? round( $ret, $acc ) . '%' : "$ret%";
2484 }
2485
2486 /**
2487  * Find out whether or not a mixed variable exists in a string
2488  *
2489  * @param $needle String
2490  * @param $str String
2491  * @param $insensitive Boolean
2492  * @return Boolean
2493  */
2494 function in_string( $needle, $str, $insensitive = false ) {
2495         $func = 'strpos';
2496         if( $insensitive ) $func = 'stripos';
2497
2498         return $func( $str, $needle ) !== false;
2499 }
2500
2501 /**
2502  * Safety wrapper around ini_get() for boolean settings.
2503  * The values returned from ini_get() are pre-normalized for settings
2504  * set via php.ini or php_flag/php_admin_flag... but *not*
2505  * for those set via php_value/php_admin_value.
2506  *
2507  * It's fairly common for people to use php_value instead of php_flag,
2508  * which can leave you with an 'off' setting giving a false positive
2509  * for code that just takes the ini_get() return value as a boolean.
2510  *
2511  * To make things extra interesting, setting via php_value accepts
2512  * "true" and "yes" as true, but php.ini and php_flag consider them false. :)
2513  * Unrecognized values go false... again opposite PHP's own coercion
2514  * from string to bool.
2515  *
2516  * Luckily, 'properly' set settings will always come back as '0' or '1',
2517  * so we only have to worry about them and the 'improper' settings.
2518  *
2519  * I frickin' hate PHP... :P
2520  *
2521  * @param $setting String
2522  * @return Bool
2523  */
2524 function wfIniGetBool( $setting ) {
2525         $val = ini_get( $setting );
2526         // 'on' and 'true' can't have whitespace around them, but '1' can.
2527         return strtolower( $val ) == 'on'
2528                 || strtolower( $val ) == 'true'
2529                 || strtolower( $val ) == 'yes'
2530                 || preg_match( "/^\s*[+-]?0*[1-9]/", $val ); // approx C atoi() function
2531 }
2532
2533 /**
2534  * Wrapper function for PHP's dl(). This doesn't work in most situations from
2535  * PHP 5.3 onward, and is usually disabled in shared environments anyway.
2536  *
2537  * @param $extension String A PHP extension. The file suffix (.so or .dll)
2538  *                          should be omitted
2539  * @param $fileName String Name of the library, if not $extension.suffix
2540  * @return Bool - Whether or not the extension is loaded
2541  */
2542 function wfDl( $extension, $fileName = null ) {
2543         if( extension_loaded( $extension ) ) {
2544                 return true;
2545         }
2546
2547         $canDl = false;
2548         $sapi = php_sapi_name();
2549         if( version_compare( PHP_VERSION, '5.3.0', '<' ) ||
2550                 $sapi == 'cli' || $sapi == 'cgi' || $sapi == 'embed' )
2551         {
2552                 $canDl = ( function_exists( 'dl' ) && is_callable( 'dl' )
2553                 && wfIniGetBool( 'enable_dl' ) && !wfIniGetBool( 'safe_mode' ) );
2554         }
2555
2556         if( $canDl ) {
2557                 $fileName = $fileName ? $fileName : $extension;
2558                 if( wfIsWindows() ) {
2559                         $fileName = 'php_' . $fileName;
2560                 }
2561                 wfSuppressWarnings();
2562                 dl( $fileName . '.' . PHP_SHLIB_SUFFIX );
2563                 wfRestoreWarnings();
2564         }
2565         return extension_loaded( $extension );
2566 }
2567
2568 /**
2569  * Windows-compatible version of escapeshellarg()
2570  * Windows doesn't recognise single-quotes in the shell, but the escapeshellarg()
2571  * function puts single quotes in regardless of OS.
2572  *
2573  * Also fixes the locale problems on Linux in PHP 5.2.6+ (bug backported to
2574  * earlier distro releases of PHP)
2575  *
2576  * @param varargs
2577  * @return String
2578  */
2579 function wfEscapeShellArg( ) {
2580         wfInitShellLocale();
2581
2582         $args = func_get_args();
2583         $first = true;
2584         $retVal = '';
2585         foreach ( $args as $arg ) {
2586                 if ( !$first ) {
2587                         $retVal .= ' ';
2588                 } else {
2589                         $first = false;
2590                 }
2591
2592                 if ( wfIsWindows() ) {
2593                         // Escaping for an MSVC-style command line parser and CMD.EXE
2594                         // Refs:
2595                         //  * http://web.archive.org/web/20020708081031/http://mailman.lyra.org/pipermail/scite-interest/2002-March/000436.html
2596                         //  * http://technet.microsoft.com/en-us/library/cc723564.aspx
2597                         //  * Bug #13518
2598                         //  * CR r63214
2599                         // Double the backslashes before any double quotes. Escape the double quotes.
2600                         $tokens = preg_split( '/(\\\\*")/', $arg, -1, PREG_SPLIT_DELIM_CAPTURE );
2601                         $arg = '';
2602                         $iteration = 0;
2603                         foreach ( $tokens as $token ) {
2604                                 if ( $iteration % 2 == 1 ) {
2605                                         // Delimiter, a double quote preceded by zero or more slashes
2606                                         $arg .= str_replace( '\\', '\\\\', substr( $token, 0, -1 ) ) . '\\"';
2607                                 } elseif ( $iteration % 4 == 2 ) {
2608                                         // ^ in $token will be outside quotes, need to be escaped
2609                                         $arg .= str_replace( '^', '^^', $token );
2610                                 } else { // $iteration % 4 == 0
2611                                         // ^ in $token will appear inside double quotes, so leave as is
2612                                         $arg .= $token;
2613                                 }
2614                                 $iteration++;
2615                         }
2616                         // Double the backslashes before the end of the string, because
2617                         // we will soon add a quote
2618                         $m = array();
2619                         if ( preg_match( '/^(.*?)(\\\\+)$/', $arg, $m ) ) {
2620                                 $arg = $m[1] . str_replace( '\\', '\\\\', $m[2] );
2621                         }
2622
2623                         // Add surrounding quotes
2624                         $retVal .= '"' . $arg . '"';
2625                 } else {
2626                         $retVal .= escapeshellarg( $arg );
2627                 }
2628         }
2629         return $retVal;
2630 }
2631
2632 /**
2633  * Execute a shell command, with time and memory limits mirrored from the PHP
2634  * configuration if supported.
2635  * @param $cmd String Command line, properly escaped for shell.
2636  * @param &$retval optional, will receive the program's exit code.
2637  *                 (non-zero is usually failure)
2638  * @param $environ Array optional environment variables which should be
2639  *                 added to the executed command environment.
2640  * @return collected stdout as a string (trailing newlines stripped)
2641  */
2642 function wfShellExec( $cmd, &$retval = null, $environ = array() ) {
2643         global $IP, $wgMaxShellMemory, $wgMaxShellFileSize, $wgMaxShellTime;
2644
2645         static $disabled;
2646         if ( is_null( $disabled ) ) {
2647                 $disabled = false;
2648                 if( wfIniGetBool( 'safe_mode' ) ) {
2649                         wfDebug( "wfShellExec can't run in safe_mode, PHP's exec functions are too broken.\n" );
2650                         $disabled = 'safemode';
2651                 } else {
2652                         $functions = explode( ',', ini_get( 'disable_functions' ) );
2653                         $functions = array_map( 'trim', $functions );
2654                         $functions = array_map( 'strtolower', $functions );
2655                         if ( in_array( 'passthru', $functions ) ) {
2656                                 wfDebug( "passthru is in disabled_functions\n" );
2657                                 $disabled = 'passthru';
2658                         }
2659                 }
2660         }
2661         if ( $disabled ) {
2662                 $retval = 1;
2663                 return $disabled == 'safemode' ?
2664                         'Unable to run external programs in safe mode.' :
2665                         'Unable to run external programs, passthru() is disabled.';
2666         }
2667
2668         wfInitShellLocale();
2669
2670         $envcmd = '';
2671         foreach( $environ as $k => $v ) {
2672                 if ( wfIsWindows() ) {
2673                         /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
2674                          * appear in the environment variable, so we must use carat escaping as documented in
2675                          * http://technet.microsoft.com/en-us/library/cc723564.aspx
2676                          * Note however that the quote isn't listed there, but is needed, and the parentheses
2677                          * are listed there but doesn't appear to need it.
2678                          */
2679                         $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
2680                 } else {
2681                         /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
2682                          * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
2683                          */
2684                         $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
2685                 }
2686         }
2687         $cmd = $envcmd . $cmd;
2688
2689         if ( wfIsWindows() ) {
2690                 if ( version_compare( PHP_VERSION, '5.3.0', '<' ) && /* Fixed in 5.3.0 :) */
2691                         ( version_compare( PHP_VERSION, '5.2.1', '>=' ) || php_uname( 's' ) == 'Windows NT' ) )
2692                 {
2693                         # Hack to work around PHP's flawed invocation of cmd.exe
2694                         # http://news.php.net/php.internals/21796
2695                         # Windows 9x doesn't accept any kind of quotes
2696                         $cmd = '"' . $cmd . '"';
2697                 }
2698         } elseif ( php_uname( 's' ) == 'Linux' ) {
2699                 $time = intval( $wgMaxShellTime );
2700                 $mem = intval( $wgMaxShellMemory );
2701                 $filesize = intval( $wgMaxShellFileSize );
2702
2703                 if ( $time > 0 && $mem > 0 ) {
2704                         $script = "$IP/bin/ulimit4.sh";
2705                         if ( is_executable( $script ) ) {
2706                                 $cmd = '/bin/bash ' . escapeshellarg( $script ) . " $time $mem $filesize " . escapeshellarg( $cmd );
2707                         }
2708                 }
2709         }
2710         wfDebug( "wfShellExec: $cmd\n" );
2711
2712         $retval = 1; // error by default?
2713         ob_start();
2714         passthru( $cmd, $retval );
2715         $output = ob_get_contents();
2716         ob_end_clean();
2717
2718         if ( $retval == 127 ) {
2719                 wfDebugLog( 'exec', "Possibly missing executable file: $cmd\n" );
2720         }
2721         return $output;
2722 }
2723
2724 /**
2725  * Workaround for http://bugs.php.net/bug.php?id=45132
2726  * escapeshellarg() destroys non-ASCII characters if LANG is not a UTF-8 locale
2727  */
2728 function wfInitShellLocale() {
2729         static $done = false;
2730         if ( $done ) {
2731                 return;
2732         }
2733         $done = true;
2734         global $wgShellLocale;
2735         if ( !wfIniGetBool( 'safe_mode' ) ) {
2736                 putenv( "LC_CTYPE=$wgShellLocale" );
2737                 setlocale( LC_CTYPE, $wgShellLocale );
2738         }
2739 }
2740
2741 /**
2742  * Generate a shell-escaped command line string to run a maintenance script.
2743  * Note that $parameters should be a flat array and an option with an argument
2744  * should consist of two consecutive items in the array (do not use "--option value").
2745  * @param $script string MediaWiki maintenance script path
2746  * @param $parameters Array Arguments and options to the script
2747  * @param $options Array Associative array of options:
2748  *              'php': The path to the php executable
2749  *              'wrapper': Path to a PHP wrapper to handle the maintenance script
2750  * @return Array
2751  */
2752 function wfShellMaintenanceCmd( $script, array $parameters = array(), array $options = array() ) {
2753         global $wgPhpCli;
2754         // Give site config file a chance to run the script in a wrapper.
2755         // The caller may likely want to call wfBasename() on $script.
2756         wfRunHooks( 'wfShellMaintenanceCmd', array( &$script, &$parameters, &$options ) );
2757         $cmd = isset( $options['php'] ) ? array( $options['php'] ) : array( $wgPhpCli );
2758         if ( isset( $options['wrapper'] ) ) {
2759                 $cmd[] = $options['wrapper'];
2760         }
2761         $cmd[] = $script;
2762         // Escape each parameter for shell
2763         return implode( " ", array_map( 'wfEscapeShellArg', array_merge( $cmd, $parameters ) ) );
2764 }
2765
2766 /**
2767  * wfMerge attempts to merge differences between three texts.
2768  * Returns true for a clean merge and false for failure or a conflict.
2769  *
2770  * @param $old String
2771  * @param $mine String
2772  * @param $yours String
2773  * @param $result String
2774  * @return Bool
2775  */
2776 function wfMerge( $old, $mine, $yours, &$result ) {
2777         global $wgDiff3;
2778
2779         # This check may also protect against code injection in
2780         # case of broken installations.
2781         wfSuppressWarnings();
2782         $haveDiff3 = $wgDiff3 && file_exists( $wgDiff3 );
2783         wfRestoreWarnings();
2784
2785         if( !$haveDiff3 ) {
2786                 wfDebug( "diff3 not found\n" );
2787                 return false;
2788         }
2789
2790         # Make temporary files
2791         $td = wfTempDir();
2792         $oldtextFile = fopen( $oldtextName = tempnam( $td, 'merge-old-' ), 'w' );
2793         $mytextFile = fopen( $mytextName = tempnam( $td, 'merge-mine-' ), 'w' );
2794         $yourtextFile = fopen( $yourtextName = tempnam( $td, 'merge-your-' ), 'w' );
2795
2796         fwrite( $oldtextFile, $old );
2797         fclose( $oldtextFile );
2798         fwrite( $mytextFile, $mine );
2799         fclose( $mytextFile );
2800         fwrite( $yourtextFile, $yours );
2801         fclose( $yourtextFile );
2802
2803         # Check for a conflict
2804         $cmd = $wgDiff3 . ' -a --overlap-only ' .
2805                 wfEscapeShellArg( $mytextName ) . ' ' .
2806                 wfEscapeShellArg( $oldtextName ) . ' ' .
2807                 wfEscapeShellArg( $yourtextName );
2808         $handle = popen( $cmd, 'r' );
2809
2810         if( fgets( $handle, 1024 ) ) {
2811                 $conflict = true;
2812         } else {
2813                 $conflict = false;
2814         }
2815         pclose( $handle );
2816
2817         # Merge differences
2818         $cmd = $wgDiff3 . ' -a -e --merge ' .
2819                 wfEscapeShellArg( $mytextName, $oldtextName, $yourtextName );
2820         $handle = popen( $cmd, 'r' );
2821         $result = '';
2822         do {
2823                 $data = fread( $handle, 8192 );
2824                 if ( strlen( $data ) == 0 ) {
2825                         break;
2826                 }
2827                 $result .= $data;
2828         } while ( true );
2829         pclose( $handle );
2830         unlink( $mytextName );
2831         unlink( $oldtextName );
2832         unlink( $yourtextName );
2833
2834         if ( $result === '' && $old !== '' && !$conflict ) {
2835                 wfDebug( "Unexpected null result from diff3. Command: $cmd\n" );
2836                 $conflict = true;
2837         }
2838         return !$conflict;
2839 }
2840
2841 /**
2842  * Returns unified plain-text diff of two texts.
2843  * Useful for machine processing of diffs.
2844  *
2845  * @param $before String: the text before the changes.
2846  * @param $after String: the text after the changes.
2847  * @param $params String: command-line options for the diff command.
2848  * @return String: unified diff of $before and $after
2849  */
2850 function wfDiff( $before, $after, $params = '-u' ) {
2851         if ( $before == $after ) {
2852                 return '';
2853         }
2854
2855         global $wgDiff;
2856         wfSuppressWarnings();
2857         $haveDiff = $wgDiff && file_exists( $wgDiff );
2858         wfRestoreWarnings();
2859
2860         # This check may also protect against code injection in
2861         # case of broken installations.
2862         if( !$haveDiff ) {
2863                 wfDebug( "diff executable not found\n" );
2864                 $diffs = new Diff( explode( "\n", $before ), explode( "\n", $after ) );
2865                 $format = new UnifiedDiffFormatter();
2866                 return $format->format( $diffs );
2867         }
2868
2869         # Make temporary files
2870         $td = wfTempDir();
2871         $oldtextFile = fopen( $oldtextName = tempnam( $td, 'merge-old-' ), 'w' );
2872         $newtextFile = fopen( $newtextName = tempnam( $td, 'merge-your-' ), 'w' );
2873
2874         fwrite( $oldtextFile, $before );
2875         fclose( $oldtextFile );
2876         fwrite( $newtextFile, $after );
2877         fclose( $newtextFile );
2878
2879         // Get the diff of the two files
2880         $cmd = "$wgDiff " . $params . ' ' . wfEscapeShellArg( $oldtextName, $newtextName );
2881
2882         $h = popen( $cmd, 'r' );
2883
2884         $diff = '';
2885
2886         do {
2887                 $data = fread( $h, 8192 );
2888                 if ( strlen( $data ) == 0 ) {
2889                         break;
2890                 }
2891                 $diff .= $data;
2892         } while ( true );
2893
2894         // Clean up
2895         pclose( $h );
2896         unlink( $oldtextName );
2897         unlink( $newtextName );
2898
2899         // Kill the --- and +++ lines. They're not useful.
2900         $diff_lines = explode( "\n", $diff );
2901         if ( strpos( $diff_lines[0], '---' ) === 0 ) {
2902                 unset( $diff_lines[0] );
2903         }
2904         if ( strpos( $diff_lines[1], '+++' ) === 0 ) {
2905                 unset( $diff_lines[1] );
2906         }
2907
2908         $diff = implode( "\n", $diff_lines );
2909
2910         return $diff;
2911 }
2912
2913 /**
2914  * This function works like "use VERSION" in Perl, the program will die with a
2915  * backtrace if the current version of PHP is less than the version provided
2916  *
2917  * This is useful for extensions which due to their nature are not kept in sync
2918  * with releases, and might depend on other versions of PHP than the main code
2919  *
2920  * Note: PHP might die due to parsing errors in some cases before it ever
2921  *       manages to call this function, such is life
2922  *
2923  * @see perldoc -f use
2924  *
2925  * @param $req_ver Mixed: the version to check, can be a string, an integer, or
2926  *                 a float
2927  */
2928 function wfUsePHP( $req_ver ) {
2929         $php_ver = PHP_VERSION;
2930
2931         if ( version_compare( $php_ver, (string)$req_ver, '<' ) ) {
2932                 throw new MWException( "PHP $req_ver required--this is only $php_ver" );
2933         }
2934 }
2935
2936 /**
2937  * This function works like "use VERSION" in Perl except it checks the version
2938  * of MediaWiki, the program will die with a backtrace if the current version
2939  * of MediaWiki is less than the version provided.
2940  *
2941  * This is useful for extensions which due to their nature are not kept in sync
2942  * with releases
2943  *
2944  * @see perldoc -f use
2945  *
2946  * @param $req_ver Mixed: the version to check, can be a string, an integer, or
2947  *                 a float
2948  */
2949 function wfUseMW( $req_ver ) {
2950         global $wgVersion;
2951
2952         if ( version_compare( $wgVersion, (string)$req_ver, '<' ) ) {
2953                 throw new MWException( "MediaWiki $req_ver required--this is only $wgVersion" );
2954         }
2955 }
2956
2957 /**
2958  * Return the final portion of a pathname.
2959  * Reimplemented because PHP5's basename() is buggy with multibyte text.
2960  * http://bugs.php.net/bug.php?id=33898
2961  *
2962  * PHP's basename() only considers '\' a pathchar on Windows and Netware.
2963  * We'll consider it so always, as we don't want \s in our Unix paths either.
2964  *
2965  * @param $path String
2966  * @param $suffix String: to remove if present
2967  * @return String
2968  */
2969 function wfBaseName( $path, $suffix = '' ) {
2970         $encSuffix = ( $suffix == '' )
2971                 ? ''
2972                 : ( '(?:' . preg_quote( $suffix, '#' ) . ')?' );
2973         $matches = array();
2974         if( preg_match( "#([^/\\\\]*?){$encSuffix}[/\\\\]*$#", $path, $matches ) ) {
2975                 return $matches[1];
2976         } else {
2977                 return '';
2978         }
2979 }
2980
2981 /**
2982  * Generate a relative path name to the given file.
2983  * May explode on non-matching case-insensitive paths,
2984  * funky symlinks, etc.
2985  *
2986  * @param $path String: absolute destination path including target filename
2987  * @param $from String: Absolute source path, directory only
2988  * @return String
2989  */
2990 function wfRelativePath( $path, $from ) {
2991         // Normalize mixed input on Windows...
2992         $path = str_replace( '/', DIRECTORY_SEPARATOR, $path );
2993         $from = str_replace( '/', DIRECTORY_SEPARATOR, $from );
2994
2995         // Trim trailing slashes -- fix for drive root
2996         $path = rtrim( $path, DIRECTORY_SEPARATOR );
2997         $from = rtrim( $from, DIRECTORY_SEPARATOR );
2998
2999         $pieces = explode( DIRECTORY_SEPARATOR, dirname( $path ) );
3000         $against = explode( DIRECTORY_SEPARATOR, $from );
3001
3002         if( $pieces[0] !== $against[0] ) {
3003                 // Non-matching Windows drive letters?
3004                 // Return a full path.
3005                 return $path;
3006         }
3007
3008         // Trim off common prefix
3009         while( count( $pieces ) && count( $against )
3010                 && $pieces[0] == $against[0] ) {
3011                 array_shift( $pieces );
3012                 array_shift( $against );
3013         }
3014
3015         // relative dots to bump us to the parent
3016         while( count( $against ) ) {
3017                 array_unshift( $pieces, '..' );
3018                 array_shift( $against );
3019         }
3020
3021         array_push( $pieces, wfBaseName( $path ) );
3022
3023         return implode( DIRECTORY_SEPARATOR, $pieces );
3024 }
3025
3026 /**
3027  * Do any deferred updates and clear the list
3028  *
3029  * @deprecated since 1.19
3030  * @see DeferredUpdates::doUpdate()
3031  * @param $commit string
3032  */
3033 function wfDoUpdates( $commit = '' ) {
3034         wfDeprecated( __METHOD__, '1.19' );
3035         DeferredUpdates::doUpdates( $commit );
3036 }
3037
3038 /**
3039  * Convert an arbitrarily-long digit string from one numeric base
3040  * to another, optionally zero-padding to a minimum column width.
3041  *
3042  * Supports base 2 through 36; digit values 10-36 are represented
3043  * as lowercase letters a-z. Input is case-insensitive.
3044  *
3045  * @param $input String: of digits
3046  * @param $sourceBase Integer: 2-36
3047  * @param $destBase Integer: 2-36
3048  * @param $pad Integer: 1 or greater
3049  * @param $lowercase Boolean
3050  * @return String or false on invalid input
3051  */
3052 function wfBaseConvert( $input, $sourceBase, $destBase, $pad = 1, $lowercase = true ) {
3053         $input = strval( $input );
3054         if( $sourceBase < 2 ||
3055                 $sourceBase > 36 ||
3056                 $destBase < 2 ||
3057                 $destBase > 36 ||
3058                 $pad < 1 ||
3059                 $sourceBase != intval( $sourceBase ) ||
3060                 $destBase != intval( $destBase ) ||
3061                 $pad != intval( $pad ) ||
3062                 !is_string( $input ) ||
3063                 $input == '' ) {
3064                 return false;
3065         }
3066         $digitChars = ( $lowercase ) ? '0123456789abcdefghijklmnopqrstuvwxyz' : '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
3067         $inDigits = array();
3068         $outChars = '';
3069
3070         // Decode and validate input string
3071         $input = strtolower( $input );
3072         for( $i = 0; $i < strlen( $input ); $i++ ) {
3073                 $n = strpos( $digitChars, $input[$i] );
3074                 if( $n === false || $n > $sourceBase ) {
3075                         return false;
3076                 }
3077                 $inDigits[] = $n;
3078         }
3079
3080         // Iterate over the input, modulo-ing out an output digit
3081         // at a time until input is gone.
3082         while( count( $inDigits ) ) {
3083                 $work = 0;
3084                 $workDigits = array();
3085
3086                 // Long division...
3087                 foreach( $inDigits as $digit ) {
3088                         $work *= $sourceBase;
3089                         $work += $digit;
3090
3091                         if( $work < $destBase ) {
3092                                 // Gonna need to pull another digit.
3093                                 if( count( $workDigits ) ) {
3094                                         // Avoid zero-padding; this lets us find
3095                                         // the end of the input very easily when
3096                                         // length drops to zero.
3097                                         $workDigits[] = 0;
3098                                 }
3099                         } else {
3100                                 // Finally! Actual division!
3101                                 $workDigits[] = intval( $work / $destBase );
3102
3103                                 // Isn't it annoying that most programming languages
3104                                 // don't have a single divide-and-remainder operator,
3105                                 // even though the CPU implements it that way?
3106                                 $work = $work % $destBase;
3107                         }
3108                 }
3109
3110                 // All that division leaves us with a remainder,
3111                 // which is conveniently our next output digit.
3112                 $outChars .= $digitChars[$work];
3113
3114                 // And we continue!
3115                 $inDigits = $workDigits;
3116         }
3117
3118         while( strlen( $outChars ) < $pad ) {
3119                 $outChars .= '0';
3120         }
3121
3122         return strrev( $outChars );
3123 }
3124
3125 /**
3126  * Create an object with a given name and an array of construct parameters
3127  *
3128  * @param $name String
3129  * @param $p Array: parameters
3130  * @return object
3131  * @deprecated since 1.18, warnings in 1.18, removal in 1.20
3132  */
3133 function wfCreateObject( $name, $p ) {
3134         wfDeprecated( __FUNCTION__, '1.18' );
3135         return MWFunction::newObj( $name, $p );
3136 }
3137
3138 /**
3139  * @return bool
3140  */
3141 function wfHttpOnlySafe() {
3142         global $wgHttpOnlyBlacklist;
3143
3144         if( isset( $_SERVER['HTTP_USER_AGENT'] ) ) {
3145                 foreach( $wgHttpOnlyBlacklist as $regex ) {
3146                         if( preg_match( $regex, $_SERVER['HTTP_USER_AGENT'] ) ) {
3147                                 return false;
3148                         }
3149                 }
3150         }
3151
3152         return true;
3153 }
3154
3155 /**
3156  * Initialise php session
3157  *
3158  * @param $sessionId Bool
3159  */
3160 function wfSetupSession( $sessionId = false ) {
3161         global $wgSessionsInMemcached, $wgCookiePath, $wgCookieDomain,
3162                         $wgCookieSecure, $wgCookieHttpOnly, $wgSessionHandler;
3163         if( $wgSessionsInMemcached ) {
3164                 if ( !defined( 'MW_COMPILED' ) ) {
3165                         global $IP;
3166                         require_once( "$IP/includes/cache/MemcachedSessions.php" );
3167                 }
3168                 session_set_save_handler( 'memsess_open', 'memsess_close', 'memsess_read',
3169                         'memsess_write', 'memsess_destroy', 'memsess_gc' );
3170
3171                 // It's necessary to register a shutdown function to call session_write_close(),
3172                 // because by the time the request shutdown function for the session module is
3173                 // called, $wgMemc has already been destroyed. Shutdown functions registered
3174                 // this way are called before object destruction.
3175                 register_shutdown_function( 'memsess_write_close' );
3176         } elseif( $wgSessionHandler && $wgSessionHandler != ini_get( 'session.save_handler' ) ) {
3177                 # Only set this if $wgSessionHandler isn't null and session.save_handler
3178                 # hasn't already been set to the desired value (that causes errors)
3179                 ini_set( 'session.save_handler', $wgSessionHandler );
3180         }
3181         $httpOnlySafe = wfHttpOnlySafe() && $wgCookieHttpOnly;
3182         wfDebugLog( 'cookie',
3183                 'session_set_cookie_params: "' . implode( '", "',
3184                         array(
3185                                 0,
3186                                 $wgCookiePath,
3187                                 $wgCookieDomain,
3188                                 $wgCookieSecure,
3189                                 $httpOnlySafe ) ) . '"' );
3190         session_set_cookie_params( 0, $wgCookiePath, $wgCookieDomain, $wgCookieSecure, $httpOnlySafe );
3191         session_cache_limiter( 'private, must-revalidate' );
3192         if ( $sessionId ) {
3193                 session_id( $sessionId );
3194         }
3195         wfSuppressWarnings();
3196         session_start();
3197         wfRestoreWarnings();
3198 }
3199
3200 /**
3201  * Get an object from the precompiled serialized directory
3202  *
3203  * @param $name String
3204  * @return Mixed: the variable on success, false on failure
3205  */
3206 function wfGetPrecompiledData( $name ) {
3207         global $IP;
3208
3209         $file = "$IP/serialized/$name";
3210         if ( file_exists( $file ) ) {
3211                 $blob = file_get_contents( $file );
3212                 if ( $blob ) {
3213                         return unserialize( $blob );
3214                 }
3215         }
3216         return false;
3217 }
3218
3219 /**
3220  * Get a cache key
3221  *
3222  * @param varargs
3223  * @return String
3224  */
3225 function wfMemcKey( /*... */ ) {
3226         global $wgCachePrefix;
3227         $prefix = $wgCachePrefix === false ? wfWikiID() : $wgCachePrefix;
3228         $args = func_get_args();
3229         $key = $prefix . ':' . implode( ':', $args );
3230         $key = str_replace( ' ', '_', $key );
3231         return $key;
3232 }
3233
3234 /**
3235  * Get a cache key for a foreign DB
3236  *
3237  * @param $db String
3238  * @param $prefix String
3239  * @param varargs String
3240  * @return String
3241  */
3242 function wfForeignMemcKey( $db, $prefix /*, ... */ ) {
3243         $args = array_slice( func_get_args(), 2 );
3244         if ( $prefix ) {
3245                 $key = "$db-$prefix:" . implode( ':', $args );
3246         } else {
3247                 $key = $db . ':' . implode( ':', $args );
3248         }
3249         return $key;
3250 }
3251
3252 /**
3253  * Get an ASCII string identifying this wiki
3254  * This is used as a prefix in memcached keys
3255  *
3256  * @return String
3257  */
3258 function wfWikiID() {
3259         global $wgDBprefix, $wgDBname;
3260         if ( $wgDBprefix ) {
3261                 return "$wgDBname-$wgDBprefix";
3262         } else {
3263                 return $wgDBname;
3264         }
3265 }
3266
3267 /**
3268  * Split a wiki ID into DB name and table prefix
3269  *
3270  * @param $wiki String
3271  *
3272  * @return array
3273  */
3274 function wfSplitWikiID( $wiki ) {
3275         $bits = explode( '-', $wiki, 2 );
3276         if ( count( $bits ) < 2 ) {
3277                 $bits[] = '';
3278         }
3279         return $bits;
3280 }
3281
3282 /**
3283  * Get a Database object.
3284  *
3285  * @param $db Integer: index of the connection to get. May be DB_MASTER for the
3286  *            master (for write queries), DB_SLAVE for potentially lagged read
3287  *            queries, or an integer >= 0 for a particular server.
3288  *
3289  * @param $groups Mixed: query groups. An array of group names that this query
3290  *                belongs to. May contain a single string if the query is only
3291  *                in one group.
3292  *
3293  * @param $wiki String: the wiki ID, or false for the current wiki
3294  *
3295  * Note: multiple calls to wfGetDB(DB_SLAVE) during the course of one request
3296  * will always return the same object, unless the underlying connection or load
3297  * balancer is manually destroyed.
3298  *
3299  * Note 2: use $this->getDB() in maintenance scripts that may be invoked by
3300  * updater to ensure that a proper database is being updated.
3301  *
3302  * @return DatabaseBase
3303  */
3304 function &wfGetDB( $db, $groups = array(), $wiki = false ) {
3305         return wfGetLB( $wiki )->getConnection( $db, $groups, $wiki );
3306 }
3307
3308 /**
3309  * Get a load balancer object.
3310  *
3311  * @param $wiki String: wiki ID, or false for the current wiki
3312  * @return LoadBalancer
3313  */
3314 function wfGetLB( $wiki = false ) {
3315         return wfGetLBFactory()->getMainLB( $wiki );
3316 }
3317
3318 /**
3319  * Get the load balancer factory object
3320  *
3321  * @return LBFactory
3322  */
3323 function &wfGetLBFactory() {
3324         return LBFactory::singleton();
3325 }
3326
3327 /**
3328  * Find a file.
3329  * Shortcut for RepoGroup::singleton()->findFile()
3330  *
3331  * @param $title String or Title object
3332  * @param $options Associative array of options:
3333  *     time:           requested time for an archived image, or false for the
3334  *                     current version. An image object will be returned which was
3335  *                     created at the specified time.
3336  *
3337  *     ignoreRedirect: If true, do not follow file redirects
3338  *
3339  *     private:        If true, return restricted (deleted) files if the current
3340  *                     user is allowed to view them. Otherwise, such files will not
3341  *                     be found.
3342  *
3343  *     bypassCache:    If true, do not use the process-local cache of File objects
3344  *
3345  * @return File, or false if the file does not exist
3346  */
3347 function wfFindFile( $title, $options = array() ) {
3348         return RepoGroup::singleton()->findFile( $title, $options );
3349 }
3350
3351 /**
3352  * Get an object referring to a locally registered file.
3353  * Returns a valid placeholder object if the file does not exist.
3354  *
3355  * @param $title Title or String
3356  * @return File|null A File, or null if passed an invalid Title
3357  */
3358 function wfLocalFile( $title ) {
3359         return RepoGroup::singleton()->getLocalRepo()->newFile( $title );
3360 }
3361
3362 /**
3363  * Stream a file to the browser. Back-compat alias for StreamFile::stream()
3364  * @deprecated since 1.19
3365  */
3366 function wfStreamFile( $fname, $headers = array() ) {
3367         wfDeprecated( __FUNCTION__, '1.19' );
3368         StreamFile::stream( $fname, $headers );
3369 }
3370
3371 /**
3372  * Should low-performance queries be disabled?
3373  *
3374  * @return Boolean
3375  * @codeCoverageIgnore
3376  */
3377 function wfQueriesMustScale() {
3378         global $wgMiserMode;
3379         return $wgMiserMode
3380                 || ( SiteStats::pages() > 100000
3381                 && SiteStats::edits() > 1000000
3382                 && SiteStats::users() > 10000 );
3383 }
3384
3385 /**
3386  * Get the path to a specified script file, respecting file
3387  * extensions; this is a wrapper around $wgScriptExtension etc.
3388  *
3389  * @param $script String: script filename, sans extension
3390  * @return String
3391  */
3392 function wfScript( $script = 'index' ) {
3393         global $wgScriptPath, $wgScriptExtension;
3394         return "{$wgScriptPath}/{$script}{$wgScriptExtension}";
3395 }
3396
3397 /**
3398  * Get the script URL.
3399  *
3400  * @return script URL
3401  */
3402 function wfGetScriptUrl() {
3403         if( isset( $_SERVER['SCRIPT_NAME'] ) ) {
3404                 #
3405                 # as it was called, minus the query string.
3406                 #
3407                 # Some sites use Apache rewrite rules to handle subdomains,
3408                 # and have PHP set up in a weird way that causes PHP_SELF
3409                 # to contain the rewritten URL instead of the one that the
3410                 # outside world sees.
3411                 #
3412                 # If in this mode, use SCRIPT_URL instead, which mod_rewrite
3413                 # provides containing the "before" URL.
3414                 return $_SERVER['SCRIPT_NAME'];
3415         } else {
3416                 return $_SERVER['URL'];
3417         }
3418 }
3419
3420 /**
3421  * Convenience function converts boolean values into "true"
3422  * or "false" (string) values
3423  *
3424  * @param $value Boolean
3425  * @return String
3426  */
3427 function wfBoolToStr( $value ) {
3428         return $value ? 'true' : 'false';
3429 }
3430
3431 /**
3432  * Load an extension messages file
3433  *
3434  * @deprecated since 1.16, warnings in 1.18, remove in 1.20
3435  * @codeCoverageIgnore
3436  */
3437 function wfLoadExtensionMessages() {
3438         wfDeprecated( __FUNCTION__, '1.16' );
3439 }
3440
3441 /**
3442  * Get a platform-independent path to the null file, e.g. /dev/null
3443  *
3444  * @return string
3445  */
3446 function wfGetNull() {
3447         return wfIsWindows()
3448                 ? 'NUL'
3449                 : '/dev/null';
3450 }
3451
3452 /**
3453  * Throws a warning that $function is deprecated
3454  *
3455  * @param $function String
3456  * @param $version String|false: Added in 1.19.
3457  * @param $component String|false: Added in 1.19.
3458  *
3459  * @return null
3460  */
3461 function wfDeprecated( $function, $version = false, $component = false ) {
3462         static $functionsWarned = array();
3463
3464         MWDebug::deprecated( $function, $version, $component );
3465
3466         if ( !in_array( $function, $GLOBALS['wgDeprecationWhitelist'] ) && !isset( $functionsWarned[$function] ) ) {
3467                 $functionsWarned[$function] = true;
3468
3469                 if ( $version ) {
3470                         global $wgDeprecationReleaseLimit;
3471
3472                         if ( $wgDeprecationReleaseLimit && $component === false ) {
3473                                 # Strip -* off the end of $version so that branches can use the
3474                                 # format #.##-branchname to avoid issues if the branch is merged into
3475                                 # a version of MediaWiki later than what it was branched from
3476                                 $comparableVersion = preg_replace( '/-.*$/', '', $version );
3477
3478                                 # If the comparableVersion is larger than our release limit then
3479                                 # skip the warning message for the deprecation
3480                                 if ( version_compare( $wgDeprecationReleaseLimit, $comparableVersion, '<' ) ) {
3481                                         return;
3482                                 }
3483                         }
3484
3485                         $component = $component === false ? 'MediaWiki' : $component;
3486                         wfWarn( "Use of $function was deprecated in $component $version.", 2 );
3487                 } else {
3488                         wfWarn( "Use of $function is deprecated.", 2 );
3489                 }
3490         }
3491 }
3492
3493 /**
3494  * Send a warning either to the debug log or in a PHP error depending on
3495  * $wgDevelopmentWarnings
3496  *
3497  * @param $msg String: message to send
3498  * @param $callerOffset Integer: number of items to go back in the backtrace to
3499  *        find the correct caller (1 = function calling wfWarn, ...)
3500  * @param $level Integer: PHP error level; only used when $wgDevelopmentWarnings
3501  *        is true
3502  */
3503 function wfWarn( $msg, $callerOffset = 1, $level = E_USER_NOTICE ) {
3504         global $wgDevelopmentWarnings;
3505
3506         MWDebug::warning( $msg, $callerOffset + 2 );
3507
3508         $callers = wfDebugBacktrace();
3509         if ( isset( $callers[$callerOffset + 1] ) ) {
3510                 $callerfunc = $callers[$callerOffset + 1];
3511                 $callerfile = $callers[$callerOffset];
3512                 if ( isset( $callerfile['file'] ) && isset( $callerfile['line'] ) ) {
3513                         $file = $callerfile['file'] . ' at line ' . $callerfile['line'];
3514                 } else {
3515                         $file = '(internal function)';
3516                 }
3517                 $func = '';
3518                 if ( isset( $callerfunc['class'] ) ) {
3519                         $func .= $callerfunc['class'] . '::';
3520                 }
3521                 if ( isset( $callerfunc['function'] ) ) {
3522                         $func .= $callerfunc['function'];
3523                 }
3524                 $msg .= " [Called from $func in $file]";
3525         }
3526
3527         if ( $wgDevelopmentWarnings ) {
3528                 trigger_error( $msg, $level );
3529         } else {
3530                 wfDebug( "$msg\n" );
3531         }
3532 }
3533
3534 /**
3535  * Modern version of wfWaitForSlaves(). Instead of looking at replication lag
3536  * and waiting for it to go down, this waits for the slaves to catch up to the
3537  * master position. Use this when updating very large numbers of rows, as
3538  * in maintenance scripts, to avoid causing too much lag.  Of course, this is
3539  * a no-op if there are no slaves.
3540  *
3541  * @param $maxLag Integer (deprecated)
3542  * @param $wiki mixed Wiki identifier accepted by wfGetLB
3543  */
3544 function wfWaitForSlaves( $maxLag = false, $wiki = false ) {
3545         $lb = wfGetLB( $wiki );
3546         // bug 27975 - Don't try to wait for slaves if there are none
3547         // Prevents permission error when getting master position
3548         if ( $lb->getServerCount() > 1 ) {
3549                 $dbw = $lb->getConnection( DB_MASTER );
3550                 $pos = $dbw->getMasterPos();
3551                 $lb->waitForAll( $pos );
3552         }
3553 }
3554
3555 /**
3556  * Used to be used for outputting text in the installer/updater
3557  * @deprecated since 1.18, warnings in 1.18, remove in 1.20
3558  */
3559 function wfOut( $s ) {
3560         wfDeprecated( __FUNCTION__, '1.18' );
3561         global $wgCommandLineMode;
3562         if ( $wgCommandLineMode ) {
3563                 echo $s;
3564         } else {
3565                 echo htmlspecialchars( $s );
3566         }
3567         flush();
3568 }
3569
3570 /**
3571  * Count down from $n to zero on the terminal, with a one-second pause
3572  * between showing each number. For use in command-line scripts.
3573  * @codeCoverageIgnore
3574  * @param $n int
3575  */
3576 function wfCountDown( $n ) {
3577         for ( $i = $n; $i >= 0; $i-- ) {
3578                 if ( $i != $n ) {
3579                         echo str_repeat( "\x08", strlen( $i + 1 ) );
3580                 }
3581                 echo $i;
3582                 flush();
3583                 if ( $i ) {
3584                         sleep( 1 );
3585                 }
3586         }
3587         echo "\n";
3588 }
3589
3590 /**
3591  * Generate a random 32-character hexadecimal token.
3592  * @param $salt Mixed: some sort of salt, if necessary, to add to random
3593  *              characters before hashing.
3594  * @return string
3595  * @codeCoverageIgnore
3596  */
3597 function wfGenerateToken( $salt = '' ) {
3598         $salt = serialize( $salt );
3599         return md5( mt_rand( 0, 0x7fffffff ) . $salt );
3600 }
3601
3602 /**
3603  * Replace all invalid characters with -
3604  *
3605  * @param $name Mixed: filename to process
3606  * @return String
3607  */
3608 function wfStripIllegalFilenameChars( $name ) {
3609         global $wgIllegalFileChars;
3610         $name = wfBaseName( $name );
3611         $name = preg_replace(
3612                 "/[^" . Title::legalChars() . "]" .
3613                         ( $wgIllegalFileChars ? "|[" . $wgIllegalFileChars . "]" : '' ) .
3614                         "/",
3615                 '-',
3616                 $name
3617         );
3618         return $name;
3619 }
3620
3621 /**
3622  * Set PHP's memory limit to the larger of php.ini or $wgMemoryLimit;
3623  *
3624  * @return Integer value memory was set to.
3625  */
3626 function wfMemoryLimit() {
3627         global $wgMemoryLimit;
3628         $memlimit = wfShorthandToInteger( ini_get( 'memory_limit' ) );
3629         if( $memlimit != -1 ) {
3630                 $conflimit = wfShorthandToInteger( $wgMemoryLimit );
3631                 if( $conflimit == -1 ) {
3632                         wfDebug( "Removing PHP's memory limit\n" );
3633                         wfSuppressWarnings();
3634                         ini_set( 'memory_limit', $conflimit );
3635                         wfRestoreWarnings();
3636                         return $conflimit;
3637                 } elseif ( $conflimit > $memlimit ) {
3638                         wfDebug( "Raising PHP's memory limit to $conflimit bytes\n" );
3639                         wfSuppressWarnings();
3640                         ini_set( 'memory_limit', $conflimit );
3641                         wfRestoreWarnings();
3642                         return $conflimit;
3643                 }
3644         }
3645         return $memlimit;
3646 }
3647
3648 /**
3649  * Converts shorthand byte notation to integer form
3650  *
3651  * @param $string String
3652  * @return Integer
3653  */
3654 function wfShorthandToInteger( $string = '' ) {
3655         $string = trim( $string );
3656         if( $string === '' ) {
3657                 return -1;
3658         }
3659         $last = $string[strlen( $string ) - 1];
3660         $val = intval( $string );
3661         switch( $last ) {
3662                 case 'g':
3663                 case 'G':
3664                         $val *= 1024;
3665                         // break intentionally missing
3666                 case 'm':
3667                 case 'M':
3668                         $val *= 1024;
3669                         // break intentionally missing
3670                 case 'k':
3671                 case 'K':
3672                         $val *= 1024;
3673         }
3674
3675         return $val;
3676 }
3677
3678 /**
3679  * Get the normalised IETF language tag
3680  * See unit test for examples.
3681  *
3682  * @param $code String: The language code.
3683  * @return String: The language code which complying with BCP 47 standards.
3684  */
3685 function wfBCP47( $code ) {
3686         $codeSegment = explode( '-', $code );
3687         $codeBCP = array();
3688         foreach ( $codeSegment as $segNo => $seg ) {
3689                 if ( count( $codeSegment ) > 0 ) {
3690                         // when previous segment is x, it is a private segment and should be lc
3691                         if( $segNo > 0 && strtolower( $codeSegment[( $segNo - 1 )] ) == 'x' ) {
3692                                 $codeBCP[$segNo] = strtolower( $seg );
3693                         // ISO 3166 country code
3694                         } elseif ( ( strlen( $seg ) == 2 ) && ( $segNo > 0 ) ) {
3695                                 $codeBCP[$segNo] = strtoupper( $seg );
3696                         // ISO 15924 script code
3697                         } elseif ( ( strlen( $seg ) == 4 ) && ( $segNo > 0 ) ) {
3698                                 $codeBCP[$segNo] = ucfirst( strtolower( $seg ) );
3699                         // Use lowercase for other cases
3700                         } else {
3701                                 $codeBCP[$segNo] = strtolower( $seg );
3702                         }
3703                 } else {
3704                 // Use lowercase for single segment
3705                         $codeBCP[$segNo] = strtolower( $seg );
3706                 }
3707         }
3708         $langCode = implode( '-', $codeBCP );
3709         return $langCode;
3710 }
3711
3712 /**
3713  * Get a cache object.
3714  *
3715  * @param $inputType integer Cache type, one the the CACHE_* constants.
3716  * @return BagOStuff
3717  */
3718 function wfGetCache( $inputType ) {
3719         return ObjectCache::getInstance( $inputType );
3720 }
3721
3722 /**
3723  * Get the main cache object
3724  *
3725  * @return BagOStuff
3726  */
3727 function wfGetMainCache() {
3728         global $wgMainCacheType;
3729         return ObjectCache::getInstance( $wgMainCacheType );
3730 }
3731
3732 /**
3733  * Get the cache object used by the message cache
3734  *
3735  * @return BagOStuff
3736  */
3737 function wfGetMessageCacheStorage() {
3738         global $wgMessageCacheType;
3739         return ObjectCache::getInstance( $wgMessageCacheType );
3740 }
3741
3742 /**
3743  * Get the cache object used by the parser cache
3744  *
3745  * @return BagOStuff
3746  */
3747 function wfGetParserCacheStorage() {
3748         global $wgParserCacheType;
3749         return ObjectCache::getInstance( $wgParserCacheType );
3750 }
3751
3752 /**
3753  * Call hook functions defined in $wgHooks
3754  *
3755  * @param $event String: event name
3756  * @param $args Array: parameters passed to hook functions
3757  * @return Boolean True if no handler aborted the hook
3758  */
3759 function wfRunHooks( $event, $args = array() ) {
3760         return Hooks::run( $event, $args );
3761 }
3762
3763 /**
3764  * Wrapper around php's unpack.
3765  *
3766  * @param $format String: The format string (See php's docs)
3767  * @param $data: A binary string of binary data
3768  * @param $length integer or false: The minimun length of $data. This is to
3769  *      prevent reading beyond the end of $data. false to disable the check.
3770  *
3771  * Also be careful when using this function to read unsigned 32 bit integer
3772  * because php might make it negative.
3773  *
3774  * @throws MWException if $data not long enough, or if unpack fails
3775  * @return Associative array of the extracted data
3776  */
3777 function wfUnpack( $format, $data, $length=false ) {
3778         if ( $length !== false ) {
3779                 $realLen = strlen( $data );
3780                 if ( $realLen < $length ) {
3781                         throw new MWException( "Tried to use wfUnpack on a "
3782                                 . "string of length $realLen, but needed one "
3783                                 . "of at least length $length."
3784                         );
3785                 }
3786         }
3787
3788         wfSuppressWarnings();
3789         $result = unpack( $format, $data );
3790         wfRestoreWarnings();
3791
3792         if ( $result === false ) {
3793                 // If it cannot extract the packed data.
3794                 throw new MWException( "unpack could not unpack binary data" );
3795         }
3796         return $result;
3797 }