Bump PHP version requirement to 7.0.0+
[lhc/web/wiklou.git] / includes / GlobalFunctions.php
1 <?php
2 /**
3 * Global functions used everywhere.
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 */
22
23 if ( !defined( 'MEDIAWIKI' ) ) {
24 die( "This file is part of MediaWiki, it is not a valid entry point" );
25 }
26
27 use MediaWiki\Logger\LoggerFactory;
28 use MediaWiki\ProcOpenError;
29 use MediaWiki\Session\SessionManager;
30 use MediaWiki\MediaWikiServices;
31 use MediaWiki\Shell\Shell;
32 use Wikimedia\ScopedCallback;
33 use Wikimedia\Rdbms\DBReplicationWaitError;
34
35 /**
36 * Load an extension
37 *
38 * This queues an extension to be loaded through
39 * the ExtensionRegistry system.
40 *
41 * @param string $ext Name of the extension to load
42 * @param string|null $path Absolute path of where to find the extension.json file
43 * @since 1.25
44 */
45 function wfLoadExtension( $ext, $path = null ) {
46 if ( !$path ) {
47 global $wgExtensionDirectory;
48 $path = "$wgExtensionDirectory/$ext/extension.json";
49 }
50 ExtensionRegistry::getInstance()->queue( $path );
51 }
52
53 /**
54 * Load multiple extensions at once
55 *
56 * Same as wfLoadExtension, but more efficient if you
57 * are loading multiple extensions.
58 *
59 * If you want to specify custom paths, you should interact with
60 * ExtensionRegistry directly.
61 *
62 * @see wfLoadExtension
63 * @param string[] $exts Array of extension names to load
64 * @since 1.25
65 */
66 function wfLoadExtensions( array $exts ) {
67 global $wgExtensionDirectory;
68 $registry = ExtensionRegistry::getInstance();
69 foreach ( $exts as $ext ) {
70 $registry->queue( "$wgExtensionDirectory/$ext/extension.json" );
71 }
72 }
73
74 /**
75 * Load a skin
76 *
77 * @see wfLoadExtension
78 * @param string $skin Name of the extension to load
79 * @param string|null $path Absolute path of where to find the skin.json file
80 * @since 1.25
81 */
82 function wfLoadSkin( $skin, $path = null ) {
83 if ( !$path ) {
84 global $wgStyleDirectory;
85 $path = "$wgStyleDirectory/$skin/skin.json";
86 }
87 ExtensionRegistry::getInstance()->queue( $path );
88 }
89
90 /**
91 * Load multiple skins at once
92 *
93 * @see wfLoadExtensions
94 * @param string[] $skins Array of extension names to load
95 * @since 1.25
96 */
97 function wfLoadSkins( array $skins ) {
98 global $wgStyleDirectory;
99 $registry = ExtensionRegistry::getInstance();
100 foreach ( $skins as $skin ) {
101 $registry->queue( "$wgStyleDirectory/$skin/skin.json" );
102 }
103 }
104
105 /**
106 * Like array_diff( $a, $b ) except that it works with two-dimensional arrays.
107 * @param array $a
108 * @param array $b
109 * @return array
110 */
111 function wfArrayDiff2( $a, $b ) {
112 return array_udiff( $a, $b, 'wfArrayDiff2_cmp' );
113 }
114
115 /**
116 * @param array|string $a
117 * @param array|string $b
118 * @return int
119 */
120 function wfArrayDiff2_cmp( $a, $b ) {
121 if ( is_string( $a ) && is_string( $b ) ) {
122 return strcmp( $a, $b );
123 } elseif ( count( $a ) !== count( $b ) ) {
124 return count( $a ) < count( $b ) ? -1 : 1;
125 } else {
126 reset( $a );
127 reset( $b );
128 while ( key( $a ) !== null && key( $b ) !== null ) {
129 $valueA = current( $a );
130 $valueB = current( $b );
131 $cmp = strcmp( $valueA, $valueB );
132 if ( $cmp !== 0 ) {
133 return $cmp;
134 }
135 next( $a );
136 next( $b );
137 }
138 return 0;
139 }
140 }
141
142 /**
143 * Like array_filter with ARRAY_FILTER_USE_BOTH, but works pre-5.6.
144 *
145 * @param array $arr
146 * @param callable $callback Will be called with the array value and key (in that order) and
147 * should return a bool which will determine whether the array element is kept.
148 * @return array
149 */
150 function wfArrayFilter( array $arr, callable $callback ) {
151 if ( defined( 'ARRAY_FILTER_USE_BOTH' ) ) {
152 return array_filter( $arr, $callback, ARRAY_FILTER_USE_BOTH );
153 }
154 $filteredKeys = array_filter( array_keys( $arr ), function ( $key ) use ( $arr, $callback ) {
155 return call_user_func( $callback, $arr[$key], $key );
156 } );
157 return array_intersect_key( $arr, array_fill_keys( $filteredKeys, true ) );
158 }
159
160 /**
161 * Like array_filter with ARRAY_FILTER_USE_KEY, but works pre-5.6.
162 *
163 * @param array $arr
164 * @param callable $callback Will be called with the array key and should return a bool which
165 * will determine whether the array element is kept.
166 * @return array
167 */
168 function wfArrayFilterByKey( array $arr, callable $callback ) {
169 return wfArrayFilter( $arr, function ( $val, $key ) use ( $callback ) {
170 return call_user_func( $callback, $key );
171 } );
172 }
173
174 /**
175 * Appends to second array if $value differs from that in $default
176 *
177 * @param string|int $key
178 * @param mixed $value
179 * @param mixed $default
180 * @param array &$changed Array to alter
181 * @throws MWException
182 */
183 function wfAppendToArrayIfNotDefault( $key, $value, $default, &$changed ) {
184 if ( is_null( $changed ) ) {
185 throw new MWException( 'GlobalFunctions::wfAppendToArrayIfNotDefault got null' );
186 }
187 if ( $default[$key] !== $value ) {
188 $changed[$key] = $value;
189 }
190 }
191
192 /**
193 * Merge arrays in the style of getUserPermissionsErrors, with duplicate removal
194 * e.g.
195 * wfMergeErrorArrays(
196 * [ [ 'x' ] ],
197 * [ [ 'x', '2' ] ],
198 * [ [ 'x' ] ],
199 * [ [ 'y' ] ]
200 * );
201 * returns:
202 * [
203 * [ 'x', '2' ],
204 * [ 'x' ],
205 * [ 'y' ]
206 * ]
207 *
208 * @param array $array1,...
209 * @return array
210 */
211 function wfMergeErrorArrays( /*...*/ ) {
212 $args = func_get_args();
213 $out = [];
214 foreach ( $args as $errors ) {
215 foreach ( $errors as $params ) {
216 $originalParams = $params;
217 if ( $params[0] instanceof MessageSpecifier ) {
218 $msg = $params[0];
219 $params = array_merge( [ $msg->getKey() ], $msg->getParams() );
220 }
221 # @todo FIXME: Sometimes get nested arrays for $params,
222 # which leads to E_NOTICEs
223 $spec = implode( "\t", $params );
224 $out[$spec] = $originalParams;
225 }
226 }
227 return array_values( $out );
228 }
229
230 /**
231 * Insert array into another array after the specified *KEY*
232 *
233 * @param array $array The array.
234 * @param array $insert The array to insert.
235 * @param mixed $after The key to insert after
236 * @return array
237 */
238 function wfArrayInsertAfter( array $array, array $insert, $after ) {
239 // Find the offset of the element to insert after.
240 $keys = array_keys( $array );
241 $offsetByKey = array_flip( $keys );
242
243 $offset = $offsetByKey[$after];
244
245 // Insert at the specified offset
246 $before = array_slice( $array, 0, $offset + 1, true );
247 $after = array_slice( $array, $offset + 1, count( $array ) - $offset, true );
248
249 $output = $before + $insert + $after;
250
251 return $output;
252 }
253
254 /**
255 * Recursively converts the parameter (an object) to an array with the same data
256 *
257 * @param object|array $objOrArray
258 * @param bool $recursive
259 * @return array
260 */
261 function wfObjectToArray( $objOrArray, $recursive = true ) {
262 $array = [];
263 if ( is_object( $objOrArray ) ) {
264 $objOrArray = get_object_vars( $objOrArray );
265 }
266 foreach ( $objOrArray as $key => $value ) {
267 if ( $recursive && ( is_object( $value ) || is_array( $value ) ) ) {
268 $value = wfObjectToArray( $value );
269 }
270
271 $array[$key] = $value;
272 }
273
274 return $array;
275 }
276
277 /**
278 * Get a random decimal value between 0 and 1, in a way
279 * not likely to give duplicate values for any realistic
280 * number of articles.
281 *
282 * @note This is designed for use in relation to Special:RandomPage
283 * and the page_random database field.
284 *
285 * @return string
286 */
287 function wfRandom() {
288 // The maximum random value is "only" 2^31-1, so get two random
289 // values to reduce the chance of dupes
290 $max = mt_getrandmax() + 1;
291 $rand = number_format( ( mt_rand() * $max + mt_rand() ) / $max / $max, 12, '.', '' );
292 return $rand;
293 }
294
295 /**
296 * Get a random string containing a number of pseudo-random hex characters.
297 *
298 * @note This is not secure, if you are trying to generate some sort
299 * of token please use MWCryptRand instead.
300 *
301 * @param int $length The length of the string to generate
302 * @return string
303 * @since 1.20
304 */
305 function wfRandomString( $length = 32 ) {
306 $str = '';
307 for ( $n = 0; $n < $length; $n += 7 ) {
308 $str .= sprintf( '%07x', mt_rand() & 0xfffffff );
309 }
310 return substr( $str, 0, $length );
311 }
312
313 /**
314 * We want some things to be included as literal characters in our title URLs
315 * for prettiness, which urlencode encodes by default. According to RFC 1738,
316 * all of the following should be safe:
317 *
318 * ;:@&=$-_.+!*'(),
319 *
320 * RFC 1738 says ~ is unsafe, however RFC 3986 considers it an unreserved
321 * character which should not be encoded. More importantly, google chrome
322 * always converts %7E back to ~, and converting it in this function can
323 * cause a redirect loop (T105265).
324 *
325 * But + is not safe because it's used to indicate a space; &= are only safe in
326 * paths and not in queries (and we don't distinguish here); ' seems kind of
327 * scary; and urlencode() doesn't touch -_. to begin with. Plus, although /
328 * is reserved, we don't care. So the list we unescape is:
329 *
330 * ;:@$!*(),/~
331 *
332 * However, IIS7 redirects fail when the url contains a colon (see T24709),
333 * so no fancy : for IIS7.
334 *
335 * %2F in the page titles seems to fatally break for some reason.
336 *
337 * @param string $s
338 * @return string
339 */
340 function wfUrlencode( $s ) {
341 static $needle;
342
343 if ( is_null( $s ) ) {
344 $needle = null;
345 return '';
346 }
347
348 if ( is_null( $needle ) ) {
349 $needle = [ '%3B', '%40', '%24', '%21', '%2A', '%28', '%29', '%2C', '%2F', '%7E' ];
350 if ( !isset( $_SERVER['SERVER_SOFTWARE'] ) ||
351 ( strpos( $_SERVER['SERVER_SOFTWARE'], 'Microsoft-IIS/7' ) === false )
352 ) {
353 $needle[] = '%3A';
354 }
355 }
356
357 $s = urlencode( $s );
358 $s = str_ireplace(
359 $needle,
360 [ ';', '@', '$', '!', '*', '(', ')', ',', '/', '~', ':' ],
361 $s
362 );
363
364 return $s;
365 }
366
367 /**
368 * This function takes one or two arrays as input, and returns a CGI-style string, e.g.
369 * "days=7&limit=100". Options in the first array override options in the second.
370 * Options set to null or false will not be output.
371 *
372 * @param array $array1 ( String|Array )
373 * @param array|null $array2 ( String|Array )
374 * @param string $prefix
375 * @return string
376 */
377 function wfArrayToCgi( $array1, $array2 = null, $prefix = '' ) {
378 if ( !is_null( $array2 ) ) {
379 $array1 = $array1 + $array2;
380 }
381
382 $cgi = '';
383 foreach ( $array1 as $key => $value ) {
384 if ( !is_null( $value ) && $value !== false ) {
385 if ( $cgi != '' ) {
386 $cgi .= '&';
387 }
388 if ( $prefix !== '' ) {
389 $key = $prefix . "[$key]";
390 }
391 if ( is_array( $value ) ) {
392 $firstTime = true;
393 foreach ( $value as $k => $v ) {
394 $cgi .= $firstTime ? '' : '&';
395 if ( is_array( $v ) ) {
396 $cgi .= wfArrayToCgi( $v, null, $key . "[$k]" );
397 } else {
398 $cgi .= urlencode( $key . "[$k]" ) . '=' . urlencode( $v );
399 }
400 $firstTime = false;
401 }
402 } else {
403 if ( is_object( $value ) ) {
404 $value = $value->__toString();
405 }
406 $cgi .= urlencode( $key ) . '=' . urlencode( $value );
407 }
408 }
409 }
410 return $cgi;
411 }
412
413 /**
414 * This is the logical opposite of wfArrayToCgi(): it accepts a query string as
415 * its argument and returns the same string in array form. This allows compatibility
416 * with legacy functions that accept raw query strings instead of nice
417 * arrays. Of course, keys and values are urldecode()d.
418 *
419 * @param string $query Query string
420 * @return string[] Array version of input
421 */
422 function wfCgiToArray( $query ) {
423 if ( isset( $query[0] ) && $query[0] == '?' ) {
424 $query = substr( $query, 1 );
425 }
426 $bits = explode( '&', $query );
427 $ret = [];
428 foreach ( $bits as $bit ) {
429 if ( $bit === '' ) {
430 continue;
431 }
432 if ( strpos( $bit, '=' ) === false ) {
433 // Pieces like &qwerty become 'qwerty' => '' (at least this is what php does)
434 $key = $bit;
435 $value = '';
436 } else {
437 list( $key, $value ) = explode( '=', $bit );
438 }
439 $key = urldecode( $key );
440 $value = urldecode( $value );
441 if ( strpos( $key, '[' ) !== false ) {
442 $keys = array_reverse( explode( '[', $key ) );
443 $key = array_pop( $keys );
444 $temp = $value;
445 foreach ( $keys as $k ) {
446 $k = substr( $k, 0, -1 );
447 $temp = [ $k => $temp ];
448 }
449 if ( isset( $ret[$key] ) ) {
450 $ret[$key] = array_merge( $ret[$key], $temp );
451 } else {
452 $ret[$key] = $temp;
453 }
454 } else {
455 $ret[$key] = $value;
456 }
457 }
458 return $ret;
459 }
460
461 /**
462 * Append a query string to an existing URL, which may or may not already
463 * have query string parameters already. If so, they will be combined.
464 *
465 * @param string $url
466 * @param string|string[] $query String or associative array
467 * @return string
468 */
469 function wfAppendQuery( $url, $query ) {
470 if ( is_array( $query ) ) {
471 $query = wfArrayToCgi( $query );
472 }
473 if ( $query != '' ) {
474 // Remove the fragment, if there is one
475 $fragment = false;
476 $hashPos = strpos( $url, '#' );
477 if ( $hashPos !== false ) {
478 $fragment = substr( $url, $hashPos );
479 $url = substr( $url, 0, $hashPos );
480 }
481
482 // Add parameter
483 if ( false === strpos( $url, '?' ) ) {
484 $url .= '?';
485 } else {
486 $url .= '&';
487 }
488 $url .= $query;
489
490 // Put the fragment back
491 if ( $fragment !== false ) {
492 $url .= $fragment;
493 }
494 }
495 return $url;
496 }
497
498 /**
499 * Expand a potentially local URL to a fully-qualified URL. Assumes $wgServer
500 * is correct.
501 *
502 * The meaning of the PROTO_* constants is as follows:
503 * PROTO_HTTP: Output a URL starting with http://
504 * PROTO_HTTPS: Output a URL starting with https://
505 * PROTO_RELATIVE: Output a URL starting with // (protocol-relative URL)
506 * PROTO_CURRENT: Output a URL starting with either http:// or https:// , depending
507 * on which protocol was used for the current incoming request
508 * PROTO_CANONICAL: For URLs without a domain, like /w/index.php , use $wgCanonicalServer.
509 * For protocol-relative URLs, use the protocol of $wgCanonicalServer
510 * PROTO_INTERNAL: Like PROTO_CANONICAL, but uses $wgInternalServer instead of $wgCanonicalServer
511 *
512 * @todo this won't work with current-path-relative URLs
513 * like "subdir/foo.html", etc.
514 *
515 * @param string $url Either fully-qualified or a local path + query
516 * @param string|int|null $defaultProto One of the PROTO_* constants. Determines the
517 * protocol to use if $url or $wgServer is protocol-relative
518 * @return string|false Fully-qualified URL, current-path-relative URL or false if
519 * no valid URL can be constructed
520 */
521 function wfExpandUrl( $url, $defaultProto = PROTO_CURRENT ) {
522 global $wgServer, $wgCanonicalServer, $wgInternalServer, $wgRequest,
523 $wgHttpsPort;
524 if ( $defaultProto === PROTO_CANONICAL ) {
525 $serverUrl = $wgCanonicalServer;
526 } elseif ( $defaultProto === PROTO_INTERNAL && $wgInternalServer !== false ) {
527 // Make $wgInternalServer fall back to $wgServer if not set
528 $serverUrl = $wgInternalServer;
529 } else {
530 $serverUrl = $wgServer;
531 if ( $defaultProto === PROTO_CURRENT ) {
532 $defaultProto = $wgRequest->getProtocol() . '://';
533 }
534 }
535
536 // Analyze $serverUrl to obtain its protocol
537 $bits = wfParseUrl( $serverUrl );
538 $serverHasProto = $bits && $bits['scheme'] != '';
539
540 if ( $defaultProto === PROTO_CANONICAL || $defaultProto === PROTO_INTERNAL ) {
541 if ( $serverHasProto ) {
542 $defaultProto = $bits['scheme'] . '://';
543 } else {
544 // $wgCanonicalServer or $wgInternalServer doesn't have a protocol.
545 // This really isn't supposed to happen. Fall back to HTTP in this
546 // ridiculous case.
547 $defaultProto = PROTO_HTTP;
548 }
549 }
550
551 $defaultProtoWithoutSlashes = substr( $defaultProto, 0, -2 );
552
553 if ( substr( $url, 0, 2 ) == '//' ) {
554 $url = $defaultProtoWithoutSlashes . $url;
555 } elseif ( substr( $url, 0, 1 ) == '/' ) {
556 // If $serverUrl is protocol-relative, prepend $defaultProtoWithoutSlashes,
557 // otherwise leave it alone.
558 $url = ( $serverHasProto ? '' : $defaultProtoWithoutSlashes ) . $serverUrl . $url;
559 }
560
561 $bits = wfParseUrl( $url );
562
563 // ensure proper port for HTTPS arrives in URL
564 // https://phabricator.wikimedia.org/T67184
565 if ( $defaultProto === PROTO_HTTPS && $wgHttpsPort != 443 ) {
566 $bits['port'] = $wgHttpsPort;
567 }
568
569 if ( $bits && isset( $bits['path'] ) ) {
570 $bits['path'] = wfRemoveDotSegments( $bits['path'] );
571 return wfAssembleUrl( $bits );
572 } elseif ( $bits ) {
573 # No path to expand
574 return $url;
575 } elseif ( substr( $url, 0, 1 ) != '/' ) {
576 # URL is a relative path
577 return wfRemoveDotSegments( $url );
578 }
579
580 # Expanded URL is not valid.
581 return false;
582 }
583
584 /**
585 * This function will reassemble a URL parsed with wfParseURL. This is useful
586 * if you need to edit part of a URL and put it back together.
587 *
588 * This is the basic structure used (brackets contain keys for $urlParts):
589 * [scheme][delimiter][user]:[pass]@[host]:[port][path]?[query]#[fragment]
590 *
591 * @todo Need to integrate this into wfExpandUrl (see T34168)
592 *
593 * @since 1.19
594 * @param array $urlParts URL parts, as output from wfParseUrl
595 * @return string URL assembled from its component parts
596 */
597 function wfAssembleUrl( $urlParts ) {
598 $result = '';
599
600 if ( isset( $urlParts['delimiter'] ) ) {
601 if ( isset( $urlParts['scheme'] ) ) {
602 $result .= $urlParts['scheme'];
603 }
604
605 $result .= $urlParts['delimiter'];
606 }
607
608 if ( isset( $urlParts['host'] ) ) {
609 if ( isset( $urlParts['user'] ) ) {
610 $result .= $urlParts['user'];
611 if ( isset( $urlParts['pass'] ) ) {
612 $result .= ':' . $urlParts['pass'];
613 }
614 $result .= '@';
615 }
616
617 $result .= $urlParts['host'];
618
619 if ( isset( $urlParts['port'] ) ) {
620 $result .= ':' . $urlParts['port'];
621 }
622 }
623
624 if ( isset( $urlParts['path'] ) ) {
625 $result .= $urlParts['path'];
626 }
627
628 if ( isset( $urlParts['query'] ) ) {
629 $result .= '?' . $urlParts['query'];
630 }
631
632 if ( isset( $urlParts['fragment'] ) ) {
633 $result .= '#' . $urlParts['fragment'];
634 }
635
636 return $result;
637 }
638
639 /**
640 * Remove all dot-segments in the provided URL path. For example,
641 * '/a/./b/../c/' becomes '/a/c/'. For details on the algorithm, please see
642 * RFC3986 section 5.2.4.
643 *
644 * @todo Need to integrate this into wfExpandUrl (see T34168)
645 *
646 * @param string $urlPath URL path, potentially containing dot-segments
647 * @return string URL path with all dot-segments removed
648 */
649 function wfRemoveDotSegments( $urlPath ) {
650 $output = '';
651 $inputOffset = 0;
652 $inputLength = strlen( $urlPath );
653
654 while ( $inputOffset < $inputLength ) {
655 $prefixLengthOne = substr( $urlPath, $inputOffset, 1 );
656 $prefixLengthTwo = substr( $urlPath, $inputOffset, 2 );
657 $prefixLengthThree = substr( $urlPath, $inputOffset, 3 );
658 $prefixLengthFour = substr( $urlPath, $inputOffset, 4 );
659 $trimOutput = false;
660
661 if ( $prefixLengthTwo == './' ) {
662 # Step A, remove leading "./"
663 $inputOffset += 2;
664 } elseif ( $prefixLengthThree == '../' ) {
665 # Step A, remove leading "../"
666 $inputOffset += 3;
667 } elseif ( ( $prefixLengthTwo == '/.' ) && ( $inputOffset + 2 == $inputLength ) ) {
668 # Step B, replace leading "/.$" with "/"
669 $inputOffset += 1;
670 $urlPath[$inputOffset] = '/';
671 } elseif ( $prefixLengthThree == '/./' ) {
672 # Step B, replace leading "/./" with "/"
673 $inputOffset += 2;
674 } elseif ( $prefixLengthThree == '/..' && ( $inputOffset + 3 == $inputLength ) ) {
675 # Step C, replace leading "/..$" with "/" and
676 # remove last path component in output
677 $inputOffset += 2;
678 $urlPath[$inputOffset] = '/';
679 $trimOutput = true;
680 } elseif ( $prefixLengthFour == '/../' ) {
681 # Step C, replace leading "/../" with "/" and
682 # remove last path component in output
683 $inputOffset += 3;
684 $trimOutput = true;
685 } elseif ( ( $prefixLengthOne == '.' ) && ( $inputOffset + 1 == $inputLength ) ) {
686 # Step D, remove "^.$"
687 $inputOffset += 1;
688 } elseif ( ( $prefixLengthTwo == '..' ) && ( $inputOffset + 2 == $inputLength ) ) {
689 # Step D, remove "^..$"
690 $inputOffset += 2;
691 } else {
692 # Step E, move leading path segment to output
693 if ( $prefixLengthOne == '/' ) {
694 $slashPos = strpos( $urlPath, '/', $inputOffset + 1 );
695 } else {
696 $slashPos = strpos( $urlPath, '/', $inputOffset );
697 }
698 if ( $slashPos === false ) {
699 $output .= substr( $urlPath, $inputOffset );
700 $inputOffset = $inputLength;
701 } else {
702 $output .= substr( $urlPath, $inputOffset, $slashPos - $inputOffset );
703 $inputOffset += $slashPos - $inputOffset;
704 }
705 }
706
707 if ( $trimOutput ) {
708 $slashPos = strrpos( $output, '/' );
709 if ( $slashPos === false ) {
710 $output = '';
711 } else {
712 $output = substr( $output, 0, $slashPos );
713 }
714 }
715 }
716
717 return $output;
718 }
719
720 /**
721 * Returns a regular expression of url protocols
722 *
723 * @param bool $includeProtocolRelative If false, remove '//' from the returned protocol list.
724 * DO NOT USE this directly, use wfUrlProtocolsWithoutProtRel() instead
725 * @return string
726 */
727 function wfUrlProtocols( $includeProtocolRelative = true ) {
728 global $wgUrlProtocols;
729
730 // Cache return values separately based on $includeProtocolRelative
731 static $withProtRel = null, $withoutProtRel = null;
732 $cachedValue = $includeProtocolRelative ? $withProtRel : $withoutProtRel;
733 if ( !is_null( $cachedValue ) ) {
734 return $cachedValue;
735 }
736
737 // Support old-style $wgUrlProtocols strings, for backwards compatibility
738 // with LocalSettings files from 1.5
739 if ( is_array( $wgUrlProtocols ) ) {
740 $protocols = [];
741 foreach ( $wgUrlProtocols as $protocol ) {
742 // Filter out '//' if !$includeProtocolRelative
743 if ( $includeProtocolRelative || $protocol !== '//' ) {
744 $protocols[] = preg_quote( $protocol, '/' );
745 }
746 }
747
748 $retval = implode( '|', $protocols );
749 } else {
750 // Ignore $includeProtocolRelative in this case
751 // This case exists for pre-1.6 compatibility, and we can safely assume
752 // that '//' won't appear in a pre-1.6 config because protocol-relative
753 // URLs weren't supported until 1.18
754 $retval = $wgUrlProtocols;
755 }
756
757 // Cache return value
758 if ( $includeProtocolRelative ) {
759 $withProtRel = $retval;
760 } else {
761 $withoutProtRel = $retval;
762 }
763 return $retval;
764 }
765
766 /**
767 * Like wfUrlProtocols(), but excludes '//' from the protocol list. Use this if
768 * you need a regex that matches all URL protocols but does not match protocol-
769 * relative URLs
770 * @return string
771 */
772 function wfUrlProtocolsWithoutProtRel() {
773 return wfUrlProtocols( false );
774 }
775
776 /**
777 * parse_url() work-alike, but non-broken. Differences:
778 *
779 * 1) Does not raise warnings on bad URLs (just returns false).
780 * 2) Handles protocols that don't use :// (e.g., mailto: and news:, as well as
781 * protocol-relative URLs) correctly.
782 * 3) Adds a "delimiter" element to the array (see (2)).
783 * 4) Verifies that the protocol is on the $wgUrlProtocols whitelist.
784 * 5) Rejects some invalid URLs that parse_url doesn't, e.g. the empty string or URLs starting with
785 * a line feed character.
786 *
787 * @param string $url A URL to parse
788 * @return string[]|bool Bits of the URL in an associative array, or false on failure.
789 * Possible fields:
790 * - scheme: URI scheme (protocol), e.g. 'http', 'mailto'. Lowercase, always present, but can
791 * be an empty string for protocol-relative URLs.
792 * - delimiter: either '://', ':' or '//'. Always present.
793 * - host: domain name / IP. Always present, but could be an empty string, e.g. for file: URLs.
794 * - user: user name, e.g. for HTTP Basic auth URLs such as http://user:pass@example.com/
795 * Missing when there is no username.
796 * - pass: password, same as above.
797 * - path: path including the leading /. Will be missing when empty (e.g. 'http://example.com')
798 * - query: query string (as a string; see wfCgiToArray() for parsing it), can be missing.
799 * - fragment: the part after #, can be missing.
800 */
801 function wfParseUrl( $url ) {
802 global $wgUrlProtocols; // Allow all protocols defined in DefaultSettings/LocalSettings.php
803
804 // Protocol-relative URLs are handled really badly by parse_url(). It's so
805 // bad that the easiest way to handle them is to just prepend 'http:' and
806 // strip the protocol out later.
807 $wasRelative = substr( $url, 0, 2 ) == '//';
808 if ( $wasRelative ) {
809 $url = "http:$url";
810 }
811 Wikimedia\suppressWarnings();
812 $bits = parse_url( $url );
813 Wikimedia\restoreWarnings();
814 // parse_url() returns an array without scheme for some invalid URLs, e.g.
815 // parse_url("%0Ahttp://example.com") == [ 'host' => '%0Ahttp', 'path' => 'example.com' ]
816 if ( !$bits || !isset( $bits['scheme'] ) ) {
817 return false;
818 }
819
820 // parse_url() incorrectly handles schemes case-sensitively. Convert it to lowercase.
821 $bits['scheme'] = strtolower( $bits['scheme'] );
822
823 // most of the protocols are followed by ://, but mailto: and sometimes news: not, check for it
824 if ( in_array( $bits['scheme'] . '://', $wgUrlProtocols ) ) {
825 $bits['delimiter'] = '://';
826 } elseif ( in_array( $bits['scheme'] . ':', $wgUrlProtocols ) ) {
827 $bits['delimiter'] = ':';
828 // parse_url detects for news: and mailto: the host part of an url as path
829 // We have to correct this wrong detection
830 if ( isset( $bits['path'] ) ) {
831 $bits['host'] = $bits['path'];
832 $bits['path'] = '';
833 }
834 } else {
835 return false;
836 }
837
838 /* Provide an empty host for eg. file:/// urls (see T30627) */
839 if ( !isset( $bits['host'] ) ) {
840 $bits['host'] = '';
841
842 // See T47069
843 if ( isset( $bits['path'] ) ) {
844 /* parse_url loses the third / for file:///c:/ urls (but not on variants) */
845 if ( substr( $bits['path'], 0, 1 ) !== '/' ) {
846 $bits['path'] = '/' . $bits['path'];
847 }
848 } else {
849 $bits['path'] = '';
850 }
851 }
852
853 // If the URL was protocol-relative, fix scheme and delimiter
854 if ( $wasRelative ) {
855 $bits['scheme'] = '';
856 $bits['delimiter'] = '//';
857 }
858 return $bits;
859 }
860
861 /**
862 * Take a URL, make sure it's expanded to fully qualified, and replace any
863 * encoded non-ASCII Unicode characters with their UTF-8 original forms
864 * for more compact display and legibility for local audiences.
865 *
866 * @todo handle punycode domains too
867 *
868 * @param string $url
869 * @return string
870 */
871 function wfExpandIRI( $url ) {
872 return preg_replace_callback(
873 '/((?:%[89A-F][0-9A-F])+)/i',
874 'wfExpandIRI_callback',
875 wfExpandUrl( $url )
876 );
877 }
878
879 /**
880 * Private callback for wfExpandIRI
881 * @param array $matches
882 * @return string
883 */
884 function wfExpandIRI_callback( $matches ) {
885 return urldecode( $matches[1] );
886 }
887
888 /**
889 * Make URL indexes, appropriate for the el_index field of externallinks.
890 *
891 * @param string $url
892 * @return array
893 */
894 function wfMakeUrlIndexes( $url ) {
895 $bits = wfParseUrl( $url );
896
897 // Reverse the labels in the hostname, convert to lower case
898 // For emails reverse domainpart only
899 if ( $bits['scheme'] == 'mailto' ) {
900 $mailparts = explode( '@', $bits['host'], 2 );
901 if ( count( $mailparts ) === 2 ) {
902 $domainpart = strtolower( implode( '.', array_reverse( explode( '.', $mailparts[1] ) ) ) );
903 } else {
904 // No domain specified, don't mangle it
905 $domainpart = '';
906 }
907 $reversedHost = $domainpart . '@' . $mailparts[0];
908 } else {
909 $reversedHost = strtolower( implode( '.', array_reverse( explode( '.', $bits['host'] ) ) ) );
910 }
911 // Add an extra dot to the end
912 // Why? Is it in wrong place in mailto links?
913 if ( substr( $reversedHost, -1, 1 ) !== '.' ) {
914 $reversedHost .= '.';
915 }
916 // Reconstruct the pseudo-URL
917 $prot = $bits['scheme'];
918 $index = $prot . $bits['delimiter'] . $reversedHost;
919 // Leave out user and password. Add the port, path, query and fragment
920 if ( isset( $bits['port'] ) ) {
921 $index .= ':' . $bits['port'];
922 }
923 if ( isset( $bits['path'] ) ) {
924 $index .= $bits['path'];
925 } else {
926 $index .= '/';
927 }
928 if ( isset( $bits['query'] ) ) {
929 $index .= '?' . $bits['query'];
930 }
931 if ( isset( $bits['fragment'] ) ) {
932 $index .= '#' . $bits['fragment'];
933 }
934
935 if ( $prot == '' ) {
936 return [ "http:$index", "https:$index" ];
937 } else {
938 return [ $index ];
939 }
940 }
941
942 /**
943 * Check whether a given URL has a domain that occurs in a given set of domains
944 * @param string $url
945 * @param array $domains Array of domains (strings)
946 * @return bool True if the host part of $url ends in one of the strings in $domains
947 */
948 function wfMatchesDomainList( $url, $domains ) {
949 $bits = wfParseUrl( $url );
950 if ( is_array( $bits ) && isset( $bits['host'] ) ) {
951 $host = '.' . $bits['host'];
952 foreach ( (array)$domains as $domain ) {
953 $domain = '.' . $domain;
954 if ( substr( $host, -strlen( $domain ) ) === $domain ) {
955 return true;
956 }
957 }
958 }
959 return false;
960 }
961
962 /**
963 * Sends a line to the debug log if enabled or, optionally, to a comment in output.
964 * In normal operation this is a NOP.
965 *
966 * Controlling globals:
967 * $wgDebugLogFile - points to the log file
968 * $wgDebugRawPage - if false, 'action=raw' hits will not result in debug output.
969 * $wgDebugComments - if on, some debug items may appear in comments in the HTML output.
970 *
971 * @since 1.25 support for additional context data
972 *
973 * @param string $text
974 * @param string|bool $dest Destination of the message:
975 * - 'all': both to the log and HTML (debug toolbar or HTML comments)
976 * - 'private': excluded from HTML output
977 * For backward compatibility, it can also take a boolean:
978 * - true: same as 'all'
979 * - false: same as 'private'
980 * @param array $context Additional logging context data
981 */
982 function wfDebug( $text, $dest = 'all', array $context = [] ) {
983 global $wgDebugRawPage, $wgDebugLogPrefix;
984 global $wgDebugTimestamps;
985
986 if ( !$wgDebugRawPage && wfIsDebugRawPage() ) {
987 return;
988 }
989
990 $text = trim( $text );
991
992 if ( $wgDebugTimestamps ) {
993 $context['seconds_elapsed'] = sprintf(
994 '%6.4f',
995 microtime( true ) - $_SERVER['REQUEST_TIME_FLOAT']
996 );
997 $context['memory_used'] = sprintf(
998 '%5.1fM',
999 ( memory_get_usage( true ) / ( 1024 * 1024 ) )
1000 );
1001 }
1002
1003 if ( $wgDebugLogPrefix !== '' ) {
1004 $context['prefix'] = $wgDebugLogPrefix;
1005 }
1006 $context['private'] = ( $dest === false || $dest === 'private' );
1007
1008 $logger = LoggerFactory::getInstance( 'wfDebug' );
1009 $logger->debug( $text, $context );
1010 }
1011
1012 /**
1013 * Returns true if debug logging should be suppressed if $wgDebugRawPage = false
1014 * @return bool
1015 */
1016 function wfIsDebugRawPage() {
1017 static $cache;
1018 if ( $cache !== null ) {
1019 return $cache;
1020 }
1021 # Check for raw action using $_GET not $wgRequest, since the latter might not be initialised yet
1022 if ( ( isset( $_GET['action'] ) && $_GET['action'] == 'raw' )
1023 || (
1024 isset( $_SERVER['SCRIPT_NAME'] )
1025 && substr( $_SERVER['SCRIPT_NAME'], -8 ) == 'load.php'
1026 )
1027 ) {
1028 $cache = true;
1029 } else {
1030 $cache = false;
1031 }
1032 return $cache;
1033 }
1034
1035 /**
1036 * Send a line giving PHP memory usage.
1037 *
1038 * @param bool $exact Print exact byte values instead of kibibytes (default: false)
1039 */
1040 function wfDebugMem( $exact = false ) {
1041 $mem = memory_get_usage();
1042 if ( !$exact ) {
1043 $mem = floor( $mem / 1024 ) . ' KiB';
1044 } else {
1045 $mem .= ' B';
1046 }
1047 wfDebug( "Memory usage: $mem\n" );
1048 }
1049
1050 /**
1051 * Send a line to a supplementary debug log file, if configured, or main debug
1052 * log if not.
1053 *
1054 * To configure a supplementary log file, set $wgDebugLogGroups[$logGroup] to
1055 * a string filename or an associative array mapping 'destination' to the
1056 * desired filename. The associative array may also contain a 'sample' key
1057 * with an integer value, specifying a sampling factor. Sampled log events
1058 * will be emitted with a 1 in N random chance.
1059 *
1060 * @since 1.23 support for sampling log messages via $wgDebugLogGroups.
1061 * @since 1.25 support for additional context data
1062 * @since 1.25 sample behavior dependent on configured $wgMWLoggerDefaultSpi
1063 *
1064 * @param string $logGroup
1065 * @param string $text
1066 * @param string|bool $dest Destination of the message:
1067 * - 'all': both to the log and HTML (debug toolbar or HTML comments)
1068 * - 'private': only to the specific log if set in $wgDebugLogGroups and
1069 * discarded otherwise
1070 * For backward compatibility, it can also take a boolean:
1071 * - true: same as 'all'
1072 * - false: same as 'private'
1073 * @param array $context Additional logging context data
1074 */
1075 function wfDebugLog(
1076 $logGroup, $text, $dest = 'all', array $context = []
1077 ) {
1078 $text = trim( $text );
1079
1080 $logger = LoggerFactory::getInstance( $logGroup );
1081 $context['private'] = ( $dest === false || $dest === 'private' );
1082 $logger->info( $text, $context );
1083 }
1084
1085 /**
1086 * Log for database errors
1087 *
1088 * @since 1.25 support for additional context data
1089 *
1090 * @param string $text Database error message.
1091 * @param array $context Additional logging context data
1092 */
1093 function wfLogDBError( $text, array $context = [] ) {
1094 $logger = LoggerFactory::getInstance( 'wfLogDBError' );
1095 $logger->error( trim( $text ), $context );
1096 }
1097
1098 /**
1099 * Throws a warning that $function is deprecated
1100 *
1101 * @param string $function
1102 * @param string|bool $version Version of MediaWiki that the function
1103 * was deprecated in (Added in 1.19).
1104 * @param string|bool $component Added in 1.19.
1105 * @param int $callerOffset How far up the call stack is the original
1106 * caller. 2 = function that called the function that called
1107 * wfDeprecated (Added in 1.20)
1108 *
1109 * @return null
1110 */
1111 function wfDeprecated( $function, $version = false, $component = false, $callerOffset = 2 ) {
1112 MWDebug::deprecated( $function, $version, $component, $callerOffset + 1 );
1113 }
1114
1115 /**
1116 * Send a warning either to the debug log or in a PHP error depending on
1117 * $wgDevelopmentWarnings. To log warnings in production, use wfLogWarning() instead.
1118 *
1119 * @param string $msg Message to send
1120 * @param int $callerOffset Number of items to go back in the backtrace to
1121 * find the correct caller (1 = function calling wfWarn, ...)
1122 * @param int $level PHP error level; defaults to E_USER_NOTICE;
1123 * only used when $wgDevelopmentWarnings is true
1124 */
1125 function wfWarn( $msg, $callerOffset = 1, $level = E_USER_NOTICE ) {
1126 MWDebug::warning( $msg, $callerOffset + 1, $level, 'auto' );
1127 }
1128
1129 /**
1130 * Send a warning as a PHP error and the debug log. This is intended for logging
1131 * warnings in production. For logging development warnings, use WfWarn instead.
1132 *
1133 * @param string $msg Message to send
1134 * @param int $callerOffset Number of items to go back in the backtrace to
1135 * find the correct caller (1 = function calling wfLogWarning, ...)
1136 * @param int $level PHP error level; defaults to E_USER_WARNING
1137 */
1138 function wfLogWarning( $msg, $callerOffset = 1, $level = E_USER_WARNING ) {
1139 MWDebug::warning( $msg, $callerOffset + 1, $level, 'production' );
1140 }
1141
1142 /**
1143 * Log to a file without getting "file size exceeded" signals.
1144 *
1145 * Can also log to TCP or UDP with the syntax udp://host:port/prefix. This will
1146 * send lines to the specified port, prefixed by the specified prefix and a space.
1147 * @since 1.25 support for additional context data
1148 *
1149 * @param string $text
1150 * @param string $file Filename
1151 * @param array $context Additional logging context data
1152 * @throws MWException
1153 * @deprecated since 1.25 Use \MediaWiki\Logger\LegacyLogger::emit or UDPTransport
1154 */
1155 function wfErrorLog( $text, $file, array $context = [] ) {
1156 wfDeprecated( __METHOD__, '1.25' );
1157 $logger = LoggerFactory::getInstance( 'wfErrorLog' );
1158 $context['destination'] = $file;
1159 $logger->info( trim( $text ), $context );
1160 }
1161
1162 /**
1163 * @todo document
1164 * @todo Move logic to MediaWiki.php
1165 */
1166 function wfLogProfilingData() {
1167 global $wgDebugLogGroups, $wgDebugRawPage;
1168
1169 $context = RequestContext::getMain();
1170 $request = $context->getRequest();
1171
1172 $profiler = Profiler::instance();
1173 $profiler->setContext( $context );
1174 $profiler->logData();
1175
1176 // Send out any buffered statsd metrics as needed
1177 MediaWiki::emitBufferedStatsdData(
1178 MediaWikiServices::getInstance()->getStatsdDataFactory(),
1179 $context->getConfig()
1180 );
1181
1182 // Profiling must actually be enabled...
1183 if ( $profiler instanceof ProfilerStub ) {
1184 return;
1185 }
1186
1187 if ( isset( $wgDebugLogGroups['profileoutput'] )
1188 && $wgDebugLogGroups['profileoutput'] === false
1189 ) {
1190 // Explicitly disabled
1191 return;
1192 }
1193 if ( !$wgDebugRawPage && wfIsDebugRawPage() ) {
1194 return;
1195 }
1196
1197 $ctx = [ 'elapsed' => $request->getElapsedTime() ];
1198 if ( !empty( $_SERVER['HTTP_X_FORWARDED_FOR'] ) ) {
1199 $ctx['forwarded_for'] = $_SERVER['HTTP_X_FORWARDED_FOR'];
1200 }
1201 if ( !empty( $_SERVER['HTTP_CLIENT_IP'] ) ) {
1202 $ctx['client_ip'] = $_SERVER['HTTP_CLIENT_IP'];
1203 }
1204 if ( !empty( $_SERVER['HTTP_FROM'] ) ) {
1205 $ctx['from'] = $_SERVER['HTTP_FROM'];
1206 }
1207 if ( isset( $ctx['forwarded_for'] ) ||
1208 isset( $ctx['client_ip'] ) ||
1209 isset( $ctx['from'] ) ) {
1210 $ctx['proxy'] = $_SERVER['REMOTE_ADDR'];
1211 }
1212
1213 // Don't load $wgUser at this late stage just for statistics purposes
1214 // @todo FIXME: We can detect some anons even if it is not loaded.
1215 // See User::getId()
1216 $user = $context->getUser();
1217 $ctx['anon'] = $user->isItemLoaded( 'id' ) && $user->isAnon();
1218
1219 // Command line script uses a FauxRequest object which does not have
1220 // any knowledge about an URL and throw an exception instead.
1221 try {
1222 $ctx['url'] = urldecode( $request->getRequestURL() );
1223 } catch ( Exception $ignored ) {
1224 // no-op
1225 }
1226
1227 $ctx['output'] = $profiler->getOutput();
1228
1229 $log = LoggerFactory::getInstance( 'profileoutput' );
1230 $log->info( "Elapsed: {elapsed}; URL: <{url}>\n{output}", $ctx );
1231 }
1232
1233 /**
1234 * Increment a statistics counter
1235 *
1236 * @param string $key
1237 * @param int $count
1238 * @return void
1239 */
1240 function wfIncrStats( $key, $count = 1 ) {
1241 $stats = MediaWikiServices::getInstance()->getStatsdDataFactory();
1242 $stats->updateCount( $key, $count );
1243 }
1244
1245 /**
1246 * Check whether the wiki is in read-only mode.
1247 *
1248 * @return bool
1249 */
1250 function wfReadOnly() {
1251 return MediaWikiServices::getInstance()->getReadOnlyMode()
1252 ->isReadOnly();
1253 }
1254
1255 /**
1256 * Check if the site is in read-only mode and return the message if so
1257 *
1258 * This checks wfConfiguredReadOnlyReason() and the main load balancer
1259 * for replica DB lag. This may result in DB connection being made.
1260 *
1261 * @return string|bool String when in read-only mode; false otherwise
1262 */
1263 function wfReadOnlyReason() {
1264 return MediaWikiServices::getInstance()->getReadOnlyMode()
1265 ->getReason();
1266 }
1267
1268 /**
1269 * Get the value of $wgReadOnly or the contents of $wgReadOnlyFile.
1270 *
1271 * @return string|bool String when in read-only mode; false otherwise
1272 * @since 1.27
1273 */
1274 function wfConfiguredReadOnlyReason() {
1275 return MediaWikiServices::getInstance()->getConfiguredReadOnlyMode()
1276 ->getReason();
1277 }
1278
1279 /**
1280 * Return a Language object from $langcode
1281 *
1282 * @param Language|string|bool $langcode Either:
1283 * - a Language object
1284 * - code of the language to get the message for, if it is
1285 * a valid code create a language for that language, if
1286 * it is a string but not a valid code then make a basic
1287 * language object
1288 * - a boolean: if it's false then use the global object for
1289 * the current user's language (as a fallback for the old parameter
1290 * functionality), or if it is true then use global object
1291 * for the wiki's content language.
1292 * @return Language
1293 */
1294 function wfGetLangObj( $langcode = false ) {
1295 # Identify which language to get or create a language object for.
1296 # Using is_object here due to Stub objects.
1297 if ( is_object( $langcode ) ) {
1298 # Great, we already have the object (hopefully)!
1299 return $langcode;
1300 }
1301
1302 global $wgContLang, $wgLanguageCode;
1303 if ( $langcode === true || $langcode === $wgLanguageCode ) {
1304 # $langcode is the language code of the wikis content language object.
1305 # or it is a boolean and value is true
1306 return $wgContLang;
1307 }
1308
1309 global $wgLang;
1310 if ( $langcode === false || $langcode === $wgLang->getCode() ) {
1311 # $langcode is the language code of user language object.
1312 # or it was a boolean and value is false
1313 return $wgLang;
1314 }
1315
1316 $validCodes = array_keys( Language::fetchLanguageNames() );
1317 if ( in_array( $langcode, $validCodes ) ) {
1318 # $langcode corresponds to a valid language.
1319 return Language::factory( $langcode );
1320 }
1321
1322 # $langcode is a string, but not a valid language code; use content language.
1323 wfDebug( "Invalid language code passed to wfGetLangObj, falling back to content language.\n" );
1324 return $wgContLang;
1325 }
1326
1327 /**
1328 * This is the function for getting translated interface messages.
1329 *
1330 * @see Message class for documentation how to use them.
1331 * @see https://www.mediawiki.org/wiki/Manual:Messages_API
1332 *
1333 * This function replaces all old wfMsg* functions.
1334 *
1335 * @param string|string[]|MessageSpecifier $key Message key, or array of keys, or a MessageSpecifier
1336 * @param mixed $params,... Normal message parameters
1337 * @return Message
1338 *
1339 * @since 1.17
1340 *
1341 * @see Message::__construct
1342 */
1343 function wfMessage( $key /*...*/ ) {
1344 $message = new Message( $key );
1345
1346 // We call Message::params() to reduce code duplication
1347 $params = func_get_args();
1348 array_shift( $params );
1349 if ( $params ) {
1350 call_user_func_array( [ $message, 'params' ], $params );
1351 }
1352
1353 return $message;
1354 }
1355
1356 /**
1357 * This function accepts multiple message keys and returns a message instance
1358 * for the first message which is non-empty. If all messages are empty then an
1359 * instance of the first message key is returned.
1360 *
1361 * @param string|string[] $keys,... Message keys
1362 * @return Message
1363 *
1364 * @since 1.18
1365 *
1366 * @see Message::newFallbackSequence
1367 */
1368 function wfMessageFallback( /*...*/ ) {
1369 $args = func_get_args();
1370 return call_user_func_array( 'Message::newFallbackSequence', $args );
1371 }
1372
1373 /**
1374 * Replace message parameter keys on the given formatted output.
1375 *
1376 * @param string $message
1377 * @param array $args
1378 * @return string
1379 * @private
1380 */
1381 function wfMsgReplaceArgs( $message, $args ) {
1382 # Fix windows line-endings
1383 # Some messages are split with explode("\n", $msg)
1384 $message = str_replace( "\r", '', $message );
1385
1386 // Replace arguments
1387 if ( is_array( $args ) && $args ) {
1388 if ( is_array( $args[0] ) ) {
1389 $args = array_values( $args[0] );
1390 }
1391 $replacementKeys = [];
1392 foreach ( $args as $n => $param ) {
1393 $replacementKeys['$' . ( $n + 1 )] = $param;
1394 }
1395 $message = strtr( $message, $replacementKeys );
1396 }
1397
1398 return $message;
1399 }
1400
1401 /**
1402 * Fetch server name for use in error reporting etc.
1403 * Use real server name if available, so we know which machine
1404 * in a server farm generated the current page.
1405 *
1406 * @return string
1407 */
1408 function wfHostname() {
1409 static $host;
1410 if ( is_null( $host ) ) {
1411 # Hostname overriding
1412 global $wgOverrideHostname;
1413 if ( $wgOverrideHostname !== false ) {
1414 # Set static and skip any detection
1415 $host = $wgOverrideHostname;
1416 return $host;
1417 }
1418
1419 if ( function_exists( 'posix_uname' ) ) {
1420 // This function not present on Windows
1421 $uname = posix_uname();
1422 } else {
1423 $uname = false;
1424 }
1425 if ( is_array( $uname ) && isset( $uname['nodename'] ) ) {
1426 $host = $uname['nodename'];
1427 } elseif ( getenv( 'COMPUTERNAME' ) ) {
1428 # Windows computer name
1429 $host = getenv( 'COMPUTERNAME' );
1430 } else {
1431 # This may be a virtual server.
1432 $host = $_SERVER['SERVER_NAME'];
1433 }
1434 }
1435 return $host;
1436 }
1437
1438 /**
1439 * Returns a script tag that stores the amount of time it took MediaWiki to
1440 * handle the request in milliseconds as 'wgBackendResponseTime'.
1441 *
1442 * If $wgShowHostnames is true, the script will also set 'wgHostname' to the
1443 * hostname of the server handling the request.
1444 *
1445 * @return string
1446 */
1447 function wfReportTime() {
1448 global $wgShowHostnames;
1449
1450 $elapsed = ( microtime( true ) - $_SERVER['REQUEST_TIME_FLOAT'] );
1451 // seconds to milliseconds
1452 $responseTime = round( $elapsed * 1000 );
1453 $reportVars = [ 'wgBackendResponseTime' => $responseTime ];
1454 if ( $wgShowHostnames ) {
1455 $reportVars['wgHostname'] = wfHostname();
1456 }
1457 return Skin::makeVariablesScript( $reportVars );
1458 }
1459
1460 /**
1461 * Safety wrapper for debug_backtrace().
1462 *
1463 * Will return an empty array if debug_backtrace is disabled, otherwise
1464 * the output from debug_backtrace() (trimmed).
1465 *
1466 * @param int $limit This parameter can be used to limit the number of stack frames returned
1467 *
1468 * @return array Array of backtrace information
1469 */
1470 function wfDebugBacktrace( $limit = 0 ) {
1471 static $disabled = null;
1472
1473 if ( is_null( $disabled ) ) {
1474 $disabled = !function_exists( 'debug_backtrace' );
1475 if ( $disabled ) {
1476 wfDebug( "debug_backtrace() is disabled\n" );
1477 }
1478 }
1479 if ( $disabled ) {
1480 return [];
1481 }
1482
1483 if ( $limit ) {
1484 return array_slice( debug_backtrace( DEBUG_BACKTRACE_PROVIDE_OBJECT, $limit + 1 ), 1 );
1485 } else {
1486 return array_slice( debug_backtrace(), 1 );
1487 }
1488 }
1489
1490 /**
1491 * Get a debug backtrace as a string
1492 *
1493 * @param bool|null $raw If true, the return value is plain text. If false, HTML.
1494 * Defaults to $wgCommandLineMode if unset.
1495 * @return string
1496 * @since 1.25 Supports $raw parameter.
1497 */
1498 function wfBacktrace( $raw = null ) {
1499 global $wgCommandLineMode;
1500
1501 if ( $raw === null ) {
1502 $raw = $wgCommandLineMode;
1503 }
1504
1505 if ( $raw ) {
1506 $frameFormat = "%s line %s calls %s()\n";
1507 $traceFormat = "%s";
1508 } else {
1509 $frameFormat = "<li>%s line %s calls %s()</li>\n";
1510 $traceFormat = "<ul>\n%s</ul>\n";
1511 }
1512
1513 $frames = array_map( function ( $frame ) use ( $frameFormat ) {
1514 $file = !empty( $frame['file'] ) ? basename( $frame['file'] ) : '-';
1515 $line = isset( $frame['line'] ) ? $frame['line'] : '-';
1516 $call = $frame['function'];
1517 if ( !empty( $frame['class'] ) ) {
1518 $call = $frame['class'] . $frame['type'] . $call;
1519 }
1520 return sprintf( $frameFormat, $file, $line, $call );
1521 }, wfDebugBacktrace() );
1522
1523 return sprintf( $traceFormat, implode( '', $frames ) );
1524 }
1525
1526 /**
1527 * Get the name of the function which called this function
1528 * wfGetCaller( 1 ) is the function with the wfGetCaller() call (ie. __FUNCTION__)
1529 * wfGetCaller( 2 ) [default] is the caller of the function running wfGetCaller()
1530 * wfGetCaller( 3 ) is the parent of that.
1531 *
1532 * @param int $level
1533 * @return string
1534 */
1535 function wfGetCaller( $level = 2 ) {
1536 $backtrace = wfDebugBacktrace( $level + 1 );
1537 if ( isset( $backtrace[$level] ) ) {
1538 return wfFormatStackFrame( $backtrace[$level] );
1539 } else {
1540 return 'unknown';
1541 }
1542 }
1543
1544 /**
1545 * Return a string consisting of callers in the stack. Useful sometimes
1546 * for profiling specific points.
1547 *
1548 * @param int $limit The maximum depth of the stack frame to return, or false for the entire stack.
1549 * @return string
1550 */
1551 function wfGetAllCallers( $limit = 3 ) {
1552 $trace = array_reverse( wfDebugBacktrace() );
1553 if ( !$limit || $limit > count( $trace ) - 1 ) {
1554 $limit = count( $trace ) - 1;
1555 }
1556 $trace = array_slice( $trace, -$limit - 1, $limit );
1557 return implode( '/', array_map( 'wfFormatStackFrame', $trace ) );
1558 }
1559
1560 /**
1561 * Return a string representation of frame
1562 *
1563 * @param array $frame
1564 * @return string
1565 */
1566 function wfFormatStackFrame( $frame ) {
1567 if ( !isset( $frame['function'] ) ) {
1568 return 'NO_FUNCTION_GIVEN';
1569 }
1570 return isset( $frame['class'] ) && isset( $frame['type'] ) ?
1571 $frame['class'] . $frame['type'] . $frame['function'] :
1572 $frame['function'];
1573 }
1574
1575 /* Some generic result counters, pulled out of SearchEngine */
1576
1577 /**
1578 * @todo document
1579 *
1580 * @param int $offset
1581 * @param int $limit
1582 * @return string
1583 */
1584 function wfShowingResults( $offset, $limit ) {
1585 return wfMessage( 'showingresults' )->numParams( $limit, $offset + 1 )->parse();
1586 }
1587
1588 /**
1589 * Whether the client accept gzip encoding
1590 *
1591 * Uses the Accept-Encoding header to check if the client supports gzip encoding.
1592 * Use this when considering to send a gzip-encoded response to the client.
1593 *
1594 * @param bool $force Forces another check even if we already have a cached result.
1595 * @return bool
1596 */
1597 function wfClientAcceptsGzip( $force = false ) {
1598 static $result = null;
1599 if ( $result === null || $force ) {
1600 $result = false;
1601 if ( isset( $_SERVER['HTTP_ACCEPT_ENCODING'] ) ) {
1602 # @todo FIXME: We may want to blacklist some broken browsers
1603 $m = [];
1604 if ( preg_match(
1605 '/\bgzip(?:;(q)=([0-9]+(?:\.[0-9]+)))?\b/',
1606 $_SERVER['HTTP_ACCEPT_ENCODING'],
1607 $m
1608 )
1609 ) {
1610 if ( isset( $m[2] ) && ( $m[1] == 'q' ) && ( $m[2] == 0 ) ) {
1611 $result = false;
1612 return $result;
1613 }
1614 wfDebug( "wfClientAcceptsGzip: client accepts gzip.\n" );
1615 $result = true;
1616 }
1617 }
1618 }
1619 return $result;
1620 }
1621
1622 /**
1623 * Escapes the given text so that it may be output using addWikiText()
1624 * without any linking, formatting, etc. making its way through. This
1625 * is achieved by substituting certain characters with HTML entities.
1626 * As required by the callers, "<nowiki>" is not used.
1627 *
1628 * @param string $text Text to be escaped
1629 * @return string
1630 */
1631 function wfEscapeWikiText( $text ) {
1632 global $wgEnableMagicLinks;
1633 static $repl = null, $repl2 = null;
1634 if ( $repl === null || defined( 'MW_PARSER_TEST' ) || defined( 'MW_PHPUNIT_TEST' ) ) {
1635 // Tests depend upon being able to change $wgEnableMagicLinks, so don't cache
1636 // in those situations
1637 $repl = [
1638 '"' => '&#34;', '&' => '&#38;', "'" => '&#39;', '<' => '&#60;',
1639 '=' => '&#61;', '>' => '&#62;', '[' => '&#91;', ']' => '&#93;',
1640 '{' => '&#123;', '|' => '&#124;', '}' => '&#125;', ';' => '&#59;',
1641 "\n#" => "\n&#35;", "\r#" => "\r&#35;",
1642 "\n*" => "\n&#42;", "\r*" => "\r&#42;",
1643 "\n:" => "\n&#58;", "\r:" => "\r&#58;",
1644 "\n " => "\n&#32;", "\r " => "\r&#32;",
1645 "\n\n" => "\n&#10;", "\r\n" => "&#13;\n",
1646 "\n\r" => "\n&#13;", "\r\r" => "\r&#13;",
1647 "\n\t" => "\n&#9;", "\r\t" => "\r&#9;", // "\n\t\n" is treated like "\n\n"
1648 "\n----" => "\n&#45;---", "\r----" => "\r&#45;---",
1649 '__' => '_&#95;', '://' => '&#58;//',
1650 ];
1651
1652 $magicLinks = array_keys( array_filter( $wgEnableMagicLinks ) );
1653 // We have to catch everything "\s" matches in PCRE
1654 foreach ( $magicLinks as $magic ) {
1655 $repl["$magic "] = "$magic&#32;";
1656 $repl["$magic\t"] = "$magic&#9;";
1657 $repl["$magic\r"] = "$magic&#13;";
1658 $repl["$magic\n"] = "$magic&#10;";
1659 $repl["$magic\f"] = "$magic&#12;";
1660 }
1661
1662 // And handle protocols that don't use "://"
1663 global $wgUrlProtocols;
1664 $repl2 = [];
1665 foreach ( $wgUrlProtocols as $prot ) {
1666 if ( substr( $prot, -1 ) === ':' ) {
1667 $repl2[] = preg_quote( substr( $prot, 0, -1 ), '/' );
1668 }
1669 }
1670 $repl2 = $repl2 ? '/\b(' . implode( '|', $repl2 ) . '):/i' : '/^(?!)/';
1671 }
1672 $text = substr( strtr( "\n$text", $repl ), 1 );
1673 $text = preg_replace( $repl2, '$1&#58;', $text );
1674 return $text;
1675 }
1676
1677 /**
1678 * Sets dest to source and returns the original value of dest
1679 * If source is NULL, it just returns the value, it doesn't set the variable
1680 * If force is true, it will set the value even if source is NULL
1681 *
1682 * @param mixed &$dest
1683 * @param mixed $source
1684 * @param bool $force
1685 * @return mixed
1686 */
1687 function wfSetVar( &$dest, $source, $force = false ) {
1688 $temp = $dest;
1689 if ( !is_null( $source ) || $force ) {
1690 $dest = $source;
1691 }
1692 return $temp;
1693 }
1694
1695 /**
1696 * As for wfSetVar except setting a bit
1697 *
1698 * @param int &$dest
1699 * @param int $bit
1700 * @param bool $state
1701 *
1702 * @return bool
1703 */
1704 function wfSetBit( &$dest, $bit, $state = true ) {
1705 $temp = (bool)( $dest & $bit );
1706 if ( !is_null( $state ) ) {
1707 if ( $state ) {
1708 $dest |= $bit;
1709 } else {
1710 $dest &= ~$bit;
1711 }
1712 }
1713 return $temp;
1714 }
1715
1716 /**
1717 * A wrapper around the PHP function var_export().
1718 * Either print it or add it to the regular output ($wgOut).
1719 *
1720 * @param mixed $var A PHP variable to dump.
1721 */
1722 function wfVarDump( $var ) {
1723 global $wgOut;
1724 $s = str_replace( "\n", "<br />\n", var_export( $var, true ) . "\n" );
1725 if ( headers_sent() || !isset( $wgOut ) || !is_object( $wgOut ) ) {
1726 print $s;
1727 } else {
1728 $wgOut->addHTML( $s );
1729 }
1730 }
1731
1732 /**
1733 * Provide a simple HTTP error.
1734 *
1735 * @param int|string $code
1736 * @param string $label
1737 * @param string $desc
1738 */
1739 function wfHttpError( $code, $label, $desc ) {
1740 global $wgOut;
1741 HttpStatus::header( $code );
1742 if ( $wgOut ) {
1743 $wgOut->disable();
1744 $wgOut->sendCacheControl();
1745 }
1746
1747 MediaWiki\HeaderCallback::warnIfHeadersSent();
1748 header( 'Content-type: text/html; charset=utf-8' );
1749 print '<!DOCTYPE html>' .
1750 '<html><head><title>' .
1751 htmlspecialchars( $label ) .
1752 '</title></head><body><h1>' .
1753 htmlspecialchars( $label ) .
1754 '</h1><p>' .
1755 nl2br( htmlspecialchars( $desc ) ) .
1756 "</p></body></html>\n";
1757 }
1758
1759 /**
1760 * Clear away any user-level output buffers, discarding contents.
1761 *
1762 * Suitable for 'starting afresh', for instance when streaming
1763 * relatively large amounts of data without buffering, or wanting to
1764 * output image files without ob_gzhandler's compression.
1765 *
1766 * The optional $resetGzipEncoding parameter controls suppression of
1767 * the Content-Encoding header sent by ob_gzhandler; by default it
1768 * is left. See comments for wfClearOutputBuffers() for why it would
1769 * be used.
1770 *
1771 * Note that some PHP configuration options may add output buffer
1772 * layers which cannot be removed; these are left in place.
1773 *
1774 * @param bool $resetGzipEncoding
1775 */
1776 function wfResetOutputBuffers( $resetGzipEncoding = true ) {
1777 if ( $resetGzipEncoding ) {
1778 // Suppress Content-Encoding and Content-Length
1779 // headers from OutputHandler::handle.
1780 global $wgDisableOutputCompression;
1781 $wgDisableOutputCompression = true;
1782 }
1783 while ( $status = ob_get_status() ) {
1784 if ( isset( $status['flags'] ) ) {
1785 $flags = PHP_OUTPUT_HANDLER_CLEANABLE | PHP_OUTPUT_HANDLER_REMOVABLE;
1786 $deleteable = ( $status['flags'] & $flags ) === $flags;
1787 } elseif ( isset( $status['del'] ) ) {
1788 $deleteable = $status['del'];
1789 } else {
1790 // Guess that any PHP-internal setting can't be removed.
1791 $deleteable = $status['type'] !== 0; /* PHP_OUTPUT_HANDLER_INTERNAL */
1792 }
1793 if ( !$deleteable ) {
1794 // Give up, and hope the result doesn't break
1795 // output behavior.
1796 break;
1797 }
1798 if ( $status['name'] === 'MediaWikiTestCase::wfResetOutputBuffersBarrier' ) {
1799 // Unit testing barrier to prevent this function from breaking PHPUnit.
1800 break;
1801 }
1802 if ( !ob_end_clean() ) {
1803 // Could not remove output buffer handler; abort now
1804 // to avoid getting in some kind of infinite loop.
1805 break;
1806 }
1807 if ( $resetGzipEncoding ) {
1808 if ( $status['name'] == 'ob_gzhandler' ) {
1809 // Reset the 'Content-Encoding' field set by this handler
1810 // so we can start fresh.
1811 header_remove( 'Content-Encoding' );
1812 break;
1813 }
1814 }
1815 }
1816 }
1817
1818 /**
1819 * More legible than passing a 'false' parameter to wfResetOutputBuffers():
1820 *
1821 * Clear away output buffers, but keep the Content-Encoding header
1822 * produced by ob_gzhandler, if any.
1823 *
1824 * This should be used for HTTP 304 responses, where you need to
1825 * preserve the Content-Encoding header of the real result, but
1826 * also need to suppress the output of ob_gzhandler to keep to spec
1827 * and avoid breaking Firefox in rare cases where the headers and
1828 * body are broken over two packets.
1829 */
1830 function wfClearOutputBuffers() {
1831 wfResetOutputBuffers( false );
1832 }
1833
1834 /**
1835 * Converts an Accept-* header into an array mapping string values to quality
1836 * factors
1837 *
1838 * @param string $accept
1839 * @param string $def Default
1840 * @return float[] Associative array of string => float pairs
1841 */
1842 function wfAcceptToPrefs( $accept, $def = '*/*' ) {
1843 # No arg means accept anything (per HTTP spec)
1844 if ( !$accept ) {
1845 return [ $def => 1.0 ];
1846 }
1847
1848 $prefs = [];
1849
1850 $parts = explode( ',', $accept );
1851
1852 foreach ( $parts as $part ) {
1853 # @todo FIXME: Doesn't deal with params like 'text/html; level=1'
1854 $values = explode( ';', trim( $part ) );
1855 $match = [];
1856 if ( count( $values ) == 1 ) {
1857 $prefs[$values[0]] = 1.0;
1858 } elseif ( preg_match( '/q\s*=\s*(\d*\.\d+)/', $values[1], $match ) ) {
1859 $prefs[$values[0]] = floatval( $match[1] );
1860 }
1861 }
1862
1863 return $prefs;
1864 }
1865
1866 /**
1867 * Checks if a given MIME type matches any of the keys in the given
1868 * array. Basic wildcards are accepted in the array keys.
1869 *
1870 * Returns the matching MIME type (or wildcard) if a match, otherwise
1871 * NULL if no match.
1872 *
1873 * @param string $type
1874 * @param array $avail
1875 * @return string
1876 * @private
1877 */
1878 function mimeTypeMatch( $type, $avail ) {
1879 if ( array_key_exists( $type, $avail ) ) {
1880 return $type;
1881 } else {
1882 $mainType = explode( '/', $type )[0];
1883 if ( array_key_exists( "$mainType/*", $avail ) ) {
1884 return "$mainType/*";
1885 } elseif ( array_key_exists( '*/*', $avail ) ) {
1886 return '*/*';
1887 } else {
1888 return null;
1889 }
1890 }
1891 }
1892
1893 /**
1894 * Returns the 'best' match between a client's requested internet media types
1895 * and the server's list of available types. Each list should be an associative
1896 * array of type to preference (preference is a float between 0.0 and 1.0).
1897 * Wildcards in the types are acceptable.
1898 *
1899 * @param array $cprefs Client's acceptable type list
1900 * @param array $sprefs Server's offered types
1901 * @return string
1902 *
1903 * @todo FIXME: Doesn't handle params like 'text/plain; charset=UTF-8'
1904 * XXX: generalize to negotiate other stuff
1905 */
1906 function wfNegotiateType( $cprefs, $sprefs ) {
1907 $combine = [];
1908
1909 foreach ( array_keys( $sprefs ) as $type ) {
1910 $subType = explode( '/', $type )[1];
1911 if ( $subType != '*' ) {
1912 $ckey = mimeTypeMatch( $type, $cprefs );
1913 if ( $ckey ) {
1914 $combine[$type] = $sprefs[$type] * $cprefs[$ckey];
1915 }
1916 }
1917 }
1918
1919 foreach ( array_keys( $cprefs ) as $type ) {
1920 $subType = explode( '/', $type )[1];
1921 if ( $subType != '*' && !array_key_exists( $type, $sprefs ) ) {
1922 $skey = mimeTypeMatch( $type, $sprefs );
1923 if ( $skey ) {
1924 $combine[$type] = $sprefs[$skey] * $cprefs[$type];
1925 }
1926 }
1927 }
1928
1929 $bestq = 0;
1930 $besttype = null;
1931
1932 foreach ( array_keys( $combine ) as $type ) {
1933 if ( $combine[$type] > $bestq ) {
1934 $besttype = $type;
1935 $bestq = $combine[$type];
1936 }
1937 }
1938
1939 return $besttype;
1940 }
1941
1942 /**
1943 * Reference-counted warning suppression
1944 *
1945 * @deprecated since 1.26, use Wikimedia\suppressWarnings() directly
1946 * @param bool $end
1947 */
1948 function wfSuppressWarnings( $end = false ) {
1949 Wikimedia\suppressWarnings( $end );
1950 }
1951
1952 /**
1953 * @deprecated since 1.26, use Wikimedia\restoreWarnings() directly
1954 * Restore error level to previous value
1955 */
1956 function wfRestoreWarnings() {
1957 Wikimedia\restoreWarnings();
1958 }
1959
1960 /**
1961 * Get a timestamp string in one of various formats
1962 *
1963 * @param mixed $outputtype A timestamp in one of the supported formats, the
1964 * function will autodetect which format is supplied and act accordingly.
1965 * @param mixed $ts Optional timestamp to convert, default 0 for the current time
1966 * @return string|bool String / false The same date in the format specified in $outputtype or false
1967 */
1968 function wfTimestamp( $outputtype = TS_UNIX, $ts = 0 ) {
1969 $ret = MWTimestamp::convert( $outputtype, $ts );
1970 if ( $ret === false ) {
1971 wfDebug( "wfTimestamp() fed bogus time value: TYPE=$outputtype; VALUE=$ts\n" );
1972 }
1973 return $ret;
1974 }
1975
1976 /**
1977 * Return a formatted timestamp, or null if input is null.
1978 * For dealing with nullable timestamp columns in the database.
1979 *
1980 * @param int $outputtype
1981 * @param string $ts
1982 * @return string
1983 */
1984 function wfTimestampOrNull( $outputtype = TS_UNIX, $ts = null ) {
1985 if ( is_null( $ts ) ) {
1986 return null;
1987 } else {
1988 return wfTimestamp( $outputtype, $ts );
1989 }
1990 }
1991
1992 /**
1993 * Convenience function; returns MediaWiki timestamp for the present time.
1994 *
1995 * @return string
1996 */
1997 function wfTimestampNow() {
1998 # return NOW
1999 return MWTimestamp::now( TS_MW );
2000 }
2001
2002 /**
2003 * Check if the operating system is Windows
2004 *
2005 * @return bool True if it's Windows, false otherwise.
2006 */
2007 function wfIsWindows() {
2008 static $isWindows = null;
2009 if ( $isWindows === null ) {
2010 $isWindows = strtoupper( substr( PHP_OS, 0, 3 ) ) === 'WIN';
2011 }
2012 return $isWindows;
2013 }
2014
2015 /**
2016 * Check if we are running under HHVM
2017 *
2018 * @return bool
2019 */
2020 function wfIsHHVM() {
2021 return defined( 'HHVM_VERSION' );
2022 }
2023
2024 /**
2025 * Check if we are running from the commandline
2026 *
2027 * @since 1.31
2028 * @return bool
2029 */
2030 function wfIsCLI() {
2031 return PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg';
2032 }
2033
2034 /**
2035 * Tries to get the system directory for temporary files. First
2036 * $wgTmpDirectory is checked, and then the TMPDIR, TMP, and TEMP
2037 * environment variables are then checked in sequence, then
2038 * sys_get_temp_dir(), then upload_tmp_dir from php.ini.
2039 *
2040 * NOTE: When possible, use instead the tmpfile() function to create
2041 * temporary files to avoid race conditions on file creation, etc.
2042 *
2043 * @return string
2044 */
2045 function wfTempDir() {
2046 global $wgTmpDirectory;
2047
2048 if ( $wgTmpDirectory !== false ) {
2049 return $wgTmpDirectory;
2050 }
2051
2052 return TempFSFile::getUsableTempDirectory();
2053 }
2054
2055 /**
2056 * Make directory, and make all parent directories if they don't exist
2057 *
2058 * @param string $dir Full path to directory to create
2059 * @param int $mode Chmod value to use, default is $wgDirectoryMode
2060 * @param string $caller Optional caller param for debugging.
2061 * @throws MWException
2062 * @return bool
2063 */
2064 function wfMkdirParents( $dir, $mode = null, $caller = null ) {
2065 global $wgDirectoryMode;
2066
2067 if ( FileBackend::isStoragePath( $dir ) ) { // sanity
2068 throw new MWException( __FUNCTION__ . " given storage path '$dir'." );
2069 }
2070
2071 if ( !is_null( $caller ) ) {
2072 wfDebug( "$caller: called wfMkdirParents($dir)\n" );
2073 }
2074
2075 if ( strval( $dir ) === '' || is_dir( $dir ) ) {
2076 return true;
2077 }
2078
2079 $dir = str_replace( [ '\\', '/' ], DIRECTORY_SEPARATOR, $dir );
2080
2081 if ( is_null( $mode ) ) {
2082 $mode = $wgDirectoryMode;
2083 }
2084
2085 // Turn off the normal warning, we're doing our own below
2086 Wikimedia\suppressWarnings();
2087 $ok = mkdir( $dir, $mode, true ); // PHP5 <3
2088 Wikimedia\restoreWarnings();
2089
2090 if ( !$ok ) {
2091 // directory may have been created on another request since we last checked
2092 if ( is_dir( $dir ) ) {
2093 return true;
2094 }
2095
2096 // PHP doesn't report the path in its warning message, so add our own to aid in diagnosis.
2097 wfLogWarning( sprintf( "failed to mkdir \"%s\" mode 0%o", $dir, $mode ) );
2098 }
2099 return $ok;
2100 }
2101
2102 /**
2103 * Remove a directory and all its content.
2104 * Does not hide error.
2105 * @param string $dir
2106 */
2107 function wfRecursiveRemoveDir( $dir ) {
2108 wfDebug( __FUNCTION__ . "( $dir )\n" );
2109 // taken from https://secure.php.net/manual/en/function.rmdir.php#98622
2110 if ( is_dir( $dir ) ) {
2111 $objects = scandir( $dir );
2112 foreach ( $objects as $object ) {
2113 if ( $object != "." && $object != ".." ) {
2114 if ( filetype( $dir . '/' . $object ) == "dir" ) {
2115 wfRecursiveRemoveDir( $dir . '/' . $object );
2116 } else {
2117 unlink( $dir . '/' . $object );
2118 }
2119 }
2120 }
2121 reset( $objects );
2122 rmdir( $dir );
2123 }
2124 }
2125
2126 /**
2127 * @param int $nr The number to format
2128 * @param int $acc The number of digits after the decimal point, default 2
2129 * @param bool $round Whether or not to round the value, default true
2130 * @return string
2131 */
2132 function wfPercent( $nr, $acc = 2, $round = true ) {
2133 $ret = sprintf( "%.${acc}f", $nr );
2134 return $round ? round( $ret, $acc ) . '%' : "$ret%";
2135 }
2136
2137 /**
2138 * Safety wrapper around ini_get() for boolean settings.
2139 * The values returned from ini_get() are pre-normalized for settings
2140 * set via php.ini or php_flag/php_admin_flag... but *not*
2141 * for those set via php_value/php_admin_value.
2142 *
2143 * It's fairly common for people to use php_value instead of php_flag,
2144 * which can leave you with an 'off' setting giving a false positive
2145 * for code that just takes the ini_get() return value as a boolean.
2146 *
2147 * To make things extra interesting, setting via php_value accepts
2148 * "true" and "yes" as true, but php.ini and php_flag consider them false. :)
2149 * Unrecognized values go false... again opposite PHP's own coercion
2150 * from string to bool.
2151 *
2152 * Luckily, 'properly' set settings will always come back as '0' or '1',
2153 * so we only have to worry about them and the 'improper' settings.
2154 *
2155 * I frickin' hate PHP... :P
2156 *
2157 * @param string $setting
2158 * @return bool
2159 */
2160 function wfIniGetBool( $setting ) {
2161 return wfStringToBool( ini_get( $setting ) );
2162 }
2163
2164 /**
2165 * Convert string value to boolean, when the following are interpreted as true:
2166 * - on
2167 * - true
2168 * - yes
2169 * - Any number, except 0
2170 * All other strings are interpreted as false.
2171 *
2172 * @param string $val
2173 * @return bool
2174 * @since 1.31
2175 */
2176 function wfStringToBool( $val ) {
2177 $val = strtolower( $val );
2178 // 'on' and 'true' can't have whitespace around them, but '1' can.
2179 return $val == 'on'
2180 || $val == 'true'
2181 || $val == 'yes'
2182 || preg_match( "/^\s*[+-]?0*[1-9]/", $val ); // approx C atoi() function
2183 }
2184
2185 /**
2186 * Version of escapeshellarg() that works better on Windows.
2187 *
2188 * Originally, this fixed the incorrect use of single quotes on Windows
2189 * (https://bugs.php.net/bug.php?id=26285) and the locale problems on Linux in
2190 * PHP 5.2.6+ (bug backported to earlier distro releases of PHP).
2191 *
2192 * @param string $args,... strings to escape and glue together,
2193 * or a single array of strings parameter
2194 * @return string
2195 * @deprecated since 1.30 use MediaWiki\Shell::escape()
2196 */
2197 function wfEscapeShellArg( /*...*/ ) {
2198 $args = func_get_args();
2199
2200 return call_user_func_array( Shell::class . '::escape', $args );
2201 }
2202
2203 /**
2204 * Check if wfShellExec() is effectively disabled via php.ini config
2205 *
2206 * @return bool|string False or 'disabled'
2207 * @since 1.22
2208 * @deprecated since 1.30 use MediaWiki\Shell::isDisabled()
2209 */
2210 function wfShellExecDisabled() {
2211 wfDeprecated( __FUNCTION__, '1.30' );
2212 return Shell::isDisabled() ? 'disabled' : false;
2213 }
2214
2215 /**
2216 * Execute a shell command, with time and memory limits mirrored from the PHP
2217 * configuration if supported.
2218 *
2219 * @param string|string[] $cmd If string, a properly shell-escaped command line,
2220 * or an array of unescaped arguments, in which case each value will be escaped
2221 * Example: [ 'convert', '-font', 'font name' ] would produce "'convert' '-font' 'font name'"
2222 * @param null|mixed &$retval Optional, will receive the program's exit code.
2223 * (non-zero is usually failure). If there is an error from
2224 * read, select, or proc_open(), this will be set to -1.
2225 * @param array $environ Optional environment variables which should be
2226 * added to the executed command environment.
2227 * @param array $limits Optional array with limits(filesize, memory, time, walltime)
2228 * this overwrites the global wgMaxShell* limits.
2229 * @param array $options Array of options:
2230 * - duplicateStderr: Set this to true to duplicate stderr to stdout,
2231 * including errors from limit.sh
2232 * - profileMethod: By default this function will profile based on the calling
2233 * method. Set this to a string for an alternative method to profile from
2234 *
2235 * @return string Collected stdout as a string
2236 * @deprecated since 1.30 use class MediaWiki\Shell\Shell
2237 */
2238 function wfShellExec( $cmd, &$retval = null, $environ = [],
2239 $limits = [], $options = []
2240 ) {
2241 if ( Shell::isDisabled() ) {
2242 $retval = 1;
2243 // Backwards compatibility be upon us...
2244 return 'Unable to run external programs, proc_open() is disabled.';
2245 }
2246
2247 if ( is_array( $cmd ) ) {
2248 $cmd = Shell::escape( $cmd );
2249 }
2250
2251 $includeStderr = isset( $options['duplicateStderr'] ) && $options['duplicateStderr'];
2252 $profileMethod = isset( $options['profileMethod'] ) ? $options['profileMethod'] : wfGetCaller();
2253
2254 try {
2255 $result = Shell::command( [] )
2256 ->unsafeParams( (array)$cmd )
2257 ->environment( $environ )
2258 ->limits( $limits )
2259 ->includeStderr( $includeStderr )
2260 ->profileMethod( $profileMethod )
2261 // For b/c
2262 ->restrict( Shell::RESTRICT_NONE )
2263 ->execute();
2264 } catch ( ProcOpenError $ex ) {
2265 $retval = -1;
2266 return '';
2267 }
2268
2269 $retval = $result->getExitCode();
2270
2271 return $result->getStdout();
2272 }
2273
2274 /**
2275 * Execute a shell command, returning both stdout and stderr. Convenience
2276 * function, as all the arguments to wfShellExec can become unwieldy.
2277 *
2278 * @note This also includes errors from limit.sh, e.g. if $wgMaxShellFileSize is exceeded.
2279 * @param string|string[] $cmd If string, a properly shell-escaped command line,
2280 * or an array of unescaped arguments, in which case each value will be escaped
2281 * Example: [ 'convert', '-font', 'font name' ] would produce "'convert' '-font' 'font name'"
2282 * @param null|mixed &$retval Optional, will receive the program's exit code.
2283 * (non-zero is usually failure)
2284 * @param array $environ Optional environment variables which should be
2285 * added to the executed command environment.
2286 * @param array $limits Optional array with limits(filesize, memory, time, walltime)
2287 * this overwrites the global wgMaxShell* limits.
2288 * @return string Collected stdout and stderr as a string
2289 * @deprecated since 1.30 use class MediaWiki\Shell\Shell
2290 */
2291 function wfShellExecWithStderr( $cmd, &$retval = null, $environ = [], $limits = [] ) {
2292 return wfShellExec( $cmd, $retval, $environ, $limits,
2293 [ 'duplicateStderr' => true, 'profileMethod' => wfGetCaller() ] );
2294 }
2295
2296 /**
2297 * Formerly set the locale for locale-sensitive operations
2298 *
2299 * This is now done in Setup.php.
2300 *
2301 * @deprecated since 1.30, no longer needed
2302 * @see $wgShellLocale
2303 */
2304 function wfInitShellLocale() {
2305 wfDeprecated( __FUNCTION__, '1.30' );
2306 }
2307
2308 /**
2309 * Generate a shell-escaped command line string to run a MediaWiki cli script.
2310 * Note that $parameters should be a flat array and an option with an argument
2311 * should consist of two consecutive items in the array (do not use "--option value").
2312 *
2313 * @deprecated since 1.31, use Shell::makeScriptCommand()
2314 *
2315 * @param string $script MediaWiki cli script path
2316 * @param array $parameters Arguments and options to the script
2317 * @param array $options Associative array of options:
2318 * 'php': The path to the php executable
2319 * 'wrapper': Path to a PHP wrapper to handle the maintenance script
2320 * @return string
2321 */
2322 function wfShellWikiCmd( $script, array $parameters = [], array $options = [] ) {
2323 global $wgPhpCli;
2324 // Give site config file a chance to run the script in a wrapper.
2325 // The caller may likely want to call wfBasename() on $script.
2326 Hooks::run( 'wfShellWikiCmd', [ &$script, &$parameters, &$options ] );
2327 $cmd = isset( $options['php'] ) ? [ $options['php'] ] : [ $wgPhpCli ];
2328 if ( isset( $options['wrapper'] ) ) {
2329 $cmd[] = $options['wrapper'];
2330 }
2331 $cmd[] = $script;
2332 // Escape each parameter for shell
2333 return Shell::escape( array_merge( $cmd, $parameters ) );
2334 }
2335
2336 /**
2337 * wfMerge attempts to merge differences between three texts.
2338 * Returns true for a clean merge and false for failure or a conflict.
2339 *
2340 * @param string $old
2341 * @param string $mine
2342 * @param string $yours
2343 * @param string &$result
2344 * @param string &$mergeAttemptResult
2345 * @return bool
2346 */
2347 function wfMerge( $old, $mine, $yours, &$result, &$mergeAttemptResult = null ) {
2348 global $wgDiff3;
2349
2350 # This check may also protect against code injection in
2351 # case of broken installations.
2352 Wikimedia\suppressWarnings();
2353 $haveDiff3 = $wgDiff3 && file_exists( $wgDiff3 );
2354 Wikimedia\restoreWarnings();
2355
2356 if ( !$haveDiff3 ) {
2357 wfDebug( "diff3 not found\n" );
2358 return false;
2359 }
2360
2361 # Make temporary files
2362 $td = wfTempDir();
2363 $oldtextFile = fopen( $oldtextName = tempnam( $td, 'merge-old-' ), 'w' );
2364 $mytextFile = fopen( $mytextName = tempnam( $td, 'merge-mine-' ), 'w' );
2365 $yourtextFile = fopen( $yourtextName = tempnam( $td, 'merge-your-' ), 'w' );
2366
2367 # NOTE: diff3 issues a warning to stderr if any of the files does not end with
2368 # a newline character. To avoid this, we normalize the trailing whitespace before
2369 # creating the diff.
2370
2371 fwrite( $oldtextFile, rtrim( $old ) . "\n" );
2372 fclose( $oldtextFile );
2373 fwrite( $mytextFile, rtrim( $mine ) . "\n" );
2374 fclose( $mytextFile );
2375 fwrite( $yourtextFile, rtrim( $yours ) . "\n" );
2376 fclose( $yourtextFile );
2377
2378 # Check for a conflict
2379 $cmd = Shell::escape( $wgDiff3, '-a', '--overlap-only', $mytextName,
2380 $oldtextName, $yourtextName );
2381 $handle = popen( $cmd, 'r' );
2382
2383 $mergeAttemptResult = '';
2384 do {
2385 $data = fread( $handle, 8192 );
2386 if ( strlen( $data ) == 0 ) {
2387 break;
2388 }
2389 $mergeAttemptResult .= $data;
2390 } while ( true );
2391 pclose( $handle );
2392
2393 $conflict = $mergeAttemptResult !== '';
2394
2395 # Merge differences
2396 $cmd = Shell::escape( $wgDiff3, '-a', '-e', '--merge', $mytextName,
2397 $oldtextName, $yourtextName );
2398 $handle = popen( $cmd, 'r' );
2399 $result = '';
2400 do {
2401 $data = fread( $handle, 8192 );
2402 if ( strlen( $data ) == 0 ) {
2403 break;
2404 }
2405 $result .= $data;
2406 } while ( true );
2407 pclose( $handle );
2408 unlink( $mytextName );
2409 unlink( $oldtextName );
2410 unlink( $yourtextName );
2411
2412 if ( $result === '' && $old !== '' && !$conflict ) {
2413 wfDebug( "Unexpected null result from diff3. Command: $cmd\n" );
2414 $conflict = true;
2415 }
2416 return !$conflict;
2417 }
2418
2419 /**
2420 * Returns unified plain-text diff of two texts.
2421 * "Useful" for machine processing of diffs.
2422 *
2423 * @deprecated since 1.25, use DiffEngine/UnifiedDiffFormatter directly
2424 *
2425 * @param string $before The text before the changes.
2426 * @param string $after The text after the changes.
2427 * @param string $params Command-line options for the diff command.
2428 * @return string Unified diff of $before and $after
2429 */
2430 function wfDiff( $before, $after, $params = '-u' ) {
2431 if ( $before == $after ) {
2432 return '';
2433 }
2434
2435 global $wgDiff;
2436 Wikimedia\suppressWarnings();
2437 $haveDiff = $wgDiff && file_exists( $wgDiff );
2438 Wikimedia\restoreWarnings();
2439
2440 # This check may also protect against code injection in
2441 # case of broken installations.
2442 if ( !$haveDiff ) {
2443 wfDebug( "diff executable not found\n" );
2444 $diffs = new Diff( explode( "\n", $before ), explode( "\n", $after ) );
2445 $format = new UnifiedDiffFormatter();
2446 return $format->format( $diffs );
2447 }
2448
2449 # Make temporary files
2450 $td = wfTempDir();
2451 $oldtextFile = fopen( $oldtextName = tempnam( $td, 'merge-old-' ), 'w' );
2452 $newtextFile = fopen( $newtextName = tempnam( $td, 'merge-your-' ), 'w' );
2453
2454 fwrite( $oldtextFile, $before );
2455 fclose( $oldtextFile );
2456 fwrite( $newtextFile, $after );
2457 fclose( $newtextFile );
2458
2459 // Get the diff of the two files
2460 $cmd = "$wgDiff " . $params . ' ' . Shell::escape( $oldtextName, $newtextName );
2461
2462 $h = popen( $cmd, 'r' );
2463 if ( !$h ) {
2464 unlink( $oldtextName );
2465 unlink( $newtextName );
2466 throw new Exception( __METHOD__ . '(): popen() failed' );
2467 }
2468
2469 $diff = '';
2470
2471 do {
2472 $data = fread( $h, 8192 );
2473 if ( strlen( $data ) == 0 ) {
2474 break;
2475 }
2476 $diff .= $data;
2477 } while ( true );
2478
2479 // Clean up
2480 pclose( $h );
2481 unlink( $oldtextName );
2482 unlink( $newtextName );
2483
2484 // Kill the --- and +++ lines. They're not useful.
2485 $diff_lines = explode( "\n", $diff );
2486 if ( isset( $diff_lines[0] ) && strpos( $diff_lines[0], '---' ) === 0 ) {
2487 unset( $diff_lines[0] );
2488 }
2489 if ( isset( $diff_lines[1] ) && strpos( $diff_lines[1], '+++' ) === 0 ) {
2490 unset( $diff_lines[1] );
2491 }
2492
2493 $diff = implode( "\n", $diff_lines );
2494
2495 return $diff;
2496 }
2497
2498 /**
2499 * This function works like "use VERSION" in Perl, the program will die with a
2500 * backtrace if the current version of PHP is less than the version provided
2501 *
2502 * This is useful for extensions which due to their nature are not kept in sync
2503 * with releases, and might depend on other versions of PHP than the main code
2504 *
2505 * Note: PHP might die due to parsing errors in some cases before it ever
2506 * manages to call this function, such is life
2507 *
2508 * @see perldoc -f use
2509 *
2510 * @param string|int|float $req_ver The version to check, can be a string, an integer, or a float
2511 *
2512 * @deprecated since 1.30
2513 *
2514 * @throws MWException
2515 */
2516 function wfUsePHP( $req_ver ) {
2517 $php_ver = PHP_VERSION;
2518
2519 if ( version_compare( $php_ver, (string)$req_ver, '<' ) ) {
2520 throw new MWException( "PHP $req_ver required--this is only $php_ver" );
2521 }
2522 }
2523
2524 /**
2525 * This function works like "use VERSION" in Perl except it checks the version
2526 * of MediaWiki, the program will die with a backtrace if the current version
2527 * of MediaWiki is less than the version provided.
2528 *
2529 * This is useful for extensions which due to their nature are not kept in sync
2530 * with releases
2531 *
2532 * Note: Due to the behavior of PHP's version_compare() which is used in this
2533 * function, if you want to allow the 'wmf' development versions add a 'c' (or
2534 * any single letter other than 'a', 'b' or 'p') as a post-fix to your
2535 * targeted version number. For example if you wanted to allow any variation
2536 * of 1.22 use `wfUseMW( '1.22c' )`. Using an 'a' or 'b' instead of 'c' will
2537 * not result in the same comparison due to the internal logic of
2538 * version_compare().
2539 *
2540 * @see perldoc -f use
2541 *
2542 * @deprecated since 1.26, use the "requires" property of extension.json
2543 * @param string|int|float $req_ver The version to check, can be a string, an integer, or a float
2544 * @throws MWException
2545 */
2546 function wfUseMW( $req_ver ) {
2547 global $wgVersion;
2548
2549 if ( version_compare( $wgVersion, (string)$req_ver, '<' ) ) {
2550 throw new MWException( "MediaWiki $req_ver required--this is only $wgVersion" );
2551 }
2552 }
2553
2554 /**
2555 * Return the final portion of a pathname.
2556 * Reimplemented because PHP5's "basename()" is buggy with multibyte text.
2557 * https://bugs.php.net/bug.php?id=33898
2558 *
2559 * PHP's basename() only considers '\' a pathchar on Windows and Netware.
2560 * We'll consider it so always, as we don't want '\s' in our Unix paths either.
2561 *
2562 * @param string $path
2563 * @param string $suffix String to remove if present
2564 * @return string
2565 */
2566 function wfBaseName( $path, $suffix = '' ) {
2567 if ( $suffix == '' ) {
2568 $encSuffix = '';
2569 } else {
2570 $encSuffix = '(?:' . preg_quote( $suffix, '#' ) . ')?';
2571 }
2572
2573 $matches = [];
2574 if ( preg_match( "#([^/\\\\]*?){$encSuffix}[/\\\\]*$#", $path, $matches ) ) {
2575 return $matches[1];
2576 } else {
2577 return '';
2578 }
2579 }
2580
2581 /**
2582 * Generate a relative path name to the given file.
2583 * May explode on non-matching case-insensitive paths,
2584 * funky symlinks, etc.
2585 *
2586 * @param string $path Absolute destination path including target filename
2587 * @param string $from Absolute source path, directory only
2588 * @return string
2589 */
2590 function wfRelativePath( $path, $from ) {
2591 // Normalize mixed input on Windows...
2592 $path = str_replace( '/', DIRECTORY_SEPARATOR, $path );
2593 $from = str_replace( '/', DIRECTORY_SEPARATOR, $from );
2594
2595 // Trim trailing slashes -- fix for drive root
2596 $path = rtrim( $path, DIRECTORY_SEPARATOR );
2597 $from = rtrim( $from, DIRECTORY_SEPARATOR );
2598
2599 $pieces = explode( DIRECTORY_SEPARATOR, dirname( $path ) );
2600 $against = explode( DIRECTORY_SEPARATOR, $from );
2601
2602 if ( $pieces[0] !== $against[0] ) {
2603 // Non-matching Windows drive letters?
2604 // Return a full path.
2605 return $path;
2606 }
2607
2608 // Trim off common prefix
2609 while ( count( $pieces ) && count( $against )
2610 && $pieces[0] == $against[0] ) {
2611 array_shift( $pieces );
2612 array_shift( $against );
2613 }
2614
2615 // relative dots to bump us to the parent
2616 while ( count( $against ) ) {
2617 array_unshift( $pieces, '..' );
2618 array_shift( $against );
2619 }
2620
2621 array_push( $pieces, wfBaseName( $path ) );
2622
2623 return implode( DIRECTORY_SEPARATOR, $pieces );
2624 }
2625
2626 /**
2627 * Reset the session id
2628 *
2629 * @deprecated since 1.27, use MediaWiki\Session\SessionManager instead
2630 * @since 1.22
2631 */
2632 function wfResetSessionID() {
2633 wfDeprecated( __FUNCTION__, '1.27' );
2634 $session = SessionManager::getGlobalSession();
2635 $delay = $session->delaySave();
2636
2637 $session->resetId();
2638
2639 // Make sure a session is started, since that's what the old
2640 // wfResetSessionID() did.
2641 if ( session_id() !== $session->getId() ) {
2642 wfSetupSession( $session->getId() );
2643 }
2644
2645 ScopedCallback::consume( $delay );
2646 }
2647
2648 /**
2649 * Initialise php session
2650 *
2651 * @deprecated since 1.27, use MediaWiki\Session\SessionManager instead.
2652 * Generally, "using" SessionManager will be calling ->getSessionById() or
2653 * ::getGlobalSession() (depending on whether you were passing $sessionId
2654 * here), then calling $session->persist().
2655 * @param bool|string $sessionId
2656 */
2657 function wfSetupSession( $sessionId = false ) {
2658 wfDeprecated( __FUNCTION__, '1.27' );
2659
2660 if ( $sessionId ) {
2661 session_id( $sessionId );
2662 }
2663
2664 $session = SessionManager::getGlobalSession();
2665 $session->persist();
2666
2667 if ( session_id() !== $session->getId() ) {
2668 session_id( $session->getId() );
2669 }
2670 Wikimedia\quietCall( 'session_start' );
2671 }
2672
2673 /**
2674 * Get an object from the precompiled serialized directory
2675 *
2676 * @param string $name
2677 * @return mixed The variable on success, false on failure
2678 */
2679 function wfGetPrecompiledData( $name ) {
2680 global $IP;
2681
2682 $file = "$IP/serialized/$name";
2683 if ( file_exists( $file ) ) {
2684 $blob = file_get_contents( $file );
2685 if ( $blob ) {
2686 return unserialize( $blob );
2687 }
2688 }
2689 return false;
2690 }
2691
2692 /**
2693 * Make a cache key for the local wiki.
2694 *
2695 * @deprecated since 1.30 Call makeKey on a BagOStuff instance
2696 * @param string $args,...
2697 * @return string
2698 */
2699 function wfMemcKey( /*...*/ ) {
2700 return call_user_func_array(
2701 [ ObjectCache::getLocalClusterInstance(), 'makeKey' ],
2702 func_get_args()
2703 );
2704 }
2705
2706 /**
2707 * Make a cache key for a foreign DB.
2708 *
2709 * Must match what wfMemcKey() would produce in context of the foreign wiki.
2710 *
2711 * @param string $db
2712 * @param string $prefix
2713 * @param string $args,...
2714 * @return string
2715 */
2716 function wfForeignMemcKey( $db, $prefix /*...*/ ) {
2717 $args = array_slice( func_get_args(), 2 );
2718 $keyspace = $prefix ? "$db-$prefix" : $db;
2719 return call_user_func_array(
2720 [ ObjectCache::getLocalClusterInstance(), 'makeKeyInternal' ],
2721 [ $keyspace, $args ]
2722 );
2723 }
2724
2725 /**
2726 * Make a cache key with database-agnostic prefix.
2727 *
2728 * Doesn't have a wiki-specific namespace. Uses a generic 'global' prefix
2729 * instead. Must have a prefix as otherwise keys that use a database name
2730 * in the first segment will clash with wfMemcKey/wfForeignMemcKey.
2731 *
2732 * @deprecated since 1.30 Call makeGlobalKey on a BagOStuff instance
2733 * @since 1.26
2734 * @param string $args,...
2735 * @return string
2736 */
2737 function wfGlobalCacheKey( /*...*/ ) {
2738 return call_user_func_array(
2739 [ ObjectCache::getLocalClusterInstance(), 'makeGlobalKey' ],
2740 func_get_args()
2741 );
2742 }
2743
2744 /**
2745 * Get an ASCII string identifying this wiki
2746 * This is used as a prefix in memcached keys
2747 *
2748 * @return string
2749 */
2750 function wfWikiID() {
2751 global $wgDBprefix, $wgDBname;
2752 if ( $wgDBprefix ) {
2753 return "$wgDBname-$wgDBprefix";
2754 } else {
2755 return $wgDBname;
2756 }
2757 }
2758
2759 /**
2760 * Split a wiki ID into DB name and table prefix
2761 *
2762 * @param string $wiki
2763 *
2764 * @return array
2765 */
2766 function wfSplitWikiID( $wiki ) {
2767 $bits = explode( '-', $wiki, 2 );
2768 if ( count( $bits ) < 2 ) {
2769 $bits[] = '';
2770 }
2771 return $bits;
2772 }
2773
2774 /**
2775 * Get a Database object.
2776 *
2777 * @param int $db Index of the connection to get. May be DB_MASTER for the
2778 * master (for write queries), DB_REPLICA for potentially lagged read
2779 * queries, or an integer >= 0 for a particular server.
2780 *
2781 * @param string|string[] $groups Query groups. An array of group names that this query
2782 * belongs to. May contain a single string if the query is only
2783 * in one group.
2784 *
2785 * @param string|bool $wiki The wiki ID, or false for the current wiki
2786 *
2787 * Note: multiple calls to wfGetDB(DB_REPLICA) during the course of one request
2788 * will always return the same object, unless the underlying connection or load
2789 * balancer is manually destroyed.
2790 *
2791 * Note 2: use $this->getDB() in maintenance scripts that may be invoked by
2792 * updater to ensure that a proper database is being updated.
2793 *
2794 * @todo Replace calls to wfGetDB with calls to LoadBalancer::getConnection()
2795 * on an injected instance of LoadBalancer.
2796 *
2797 * @return \Wikimedia\Rdbms\Database
2798 */
2799 function wfGetDB( $db, $groups = [], $wiki = false ) {
2800 return wfGetLB( $wiki )->getConnection( $db, $groups, $wiki );
2801 }
2802
2803 /**
2804 * Get a load balancer object.
2805 *
2806 * @deprecated since 1.27, use MediaWikiServices::getDBLoadBalancer()
2807 * or MediaWikiServices::getDBLoadBalancerFactory() instead.
2808 *
2809 * @param string|bool $wiki Wiki ID, or false for the current wiki
2810 * @return \Wikimedia\Rdbms\LoadBalancer
2811 */
2812 function wfGetLB( $wiki = false ) {
2813 if ( $wiki === false ) {
2814 return MediaWikiServices::getInstance()->getDBLoadBalancer();
2815 } else {
2816 $factory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
2817 return $factory->getMainLB( $wiki );
2818 }
2819 }
2820
2821 /**
2822 * Get the load balancer factory object
2823 *
2824 * @deprecated since 1.27, use MediaWikiServices::getDBLoadBalancerFactory() instead.
2825 *
2826 * @return \Wikimedia\Rdbms\LBFactory
2827 */
2828 function wfGetLBFactory() {
2829 return MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
2830 }
2831
2832 /**
2833 * Find a file.
2834 * Shortcut for RepoGroup::singleton()->findFile()
2835 *
2836 * @param string|Title $title String or Title object
2837 * @param array $options Associative array of options (see RepoGroup::findFile)
2838 * @return File|bool File, or false if the file does not exist
2839 */
2840 function wfFindFile( $title, $options = [] ) {
2841 return RepoGroup::singleton()->findFile( $title, $options );
2842 }
2843
2844 /**
2845 * Get an object referring to a locally registered file.
2846 * Returns a valid placeholder object if the file does not exist.
2847 *
2848 * @param Title|string $title
2849 * @return LocalFile|null A File, or null if passed an invalid Title
2850 */
2851 function wfLocalFile( $title ) {
2852 return RepoGroup::singleton()->getLocalRepo()->newFile( $title );
2853 }
2854
2855 /**
2856 * Should low-performance queries be disabled?
2857 *
2858 * @return bool
2859 * @codeCoverageIgnore
2860 */
2861 function wfQueriesMustScale() {
2862 global $wgMiserMode;
2863 return $wgMiserMode
2864 || ( SiteStats::pages() > 100000
2865 && SiteStats::edits() > 1000000
2866 && SiteStats::users() > 10000 );
2867 }
2868
2869 /**
2870 * Get the path to a specified script file, respecting file
2871 * extensions; this is a wrapper around $wgScriptPath etc.
2872 * except for 'index' and 'load' which use $wgScript/$wgLoadScript
2873 *
2874 * @param string $script Script filename, sans extension
2875 * @return string
2876 */
2877 function wfScript( $script = 'index' ) {
2878 global $wgScriptPath, $wgScript, $wgLoadScript;
2879 if ( $script === 'index' ) {
2880 return $wgScript;
2881 } elseif ( $script === 'load' ) {
2882 return $wgLoadScript;
2883 } else {
2884 return "{$wgScriptPath}/{$script}.php";
2885 }
2886 }
2887
2888 /**
2889 * Get the script URL.
2890 *
2891 * @return string Script URL
2892 */
2893 function wfGetScriptUrl() {
2894 if ( isset( $_SERVER['SCRIPT_NAME'] ) ) {
2895 /* as it was called, minus the query string.
2896 *
2897 * Some sites use Apache rewrite rules to handle subdomains,
2898 * and have PHP set up in a weird way that causes PHP_SELF
2899 * to contain the rewritten URL instead of the one that the
2900 * outside world sees.
2901 *
2902 * If in this mode, use SCRIPT_URL instead, which mod_rewrite
2903 * provides containing the "before" URL.
2904 */
2905 return $_SERVER['SCRIPT_NAME'];
2906 } else {
2907 return $_SERVER['URL'];
2908 }
2909 }
2910
2911 /**
2912 * Convenience function converts boolean values into "true"
2913 * or "false" (string) values
2914 *
2915 * @param bool $value
2916 * @return string
2917 */
2918 function wfBoolToStr( $value ) {
2919 return $value ? 'true' : 'false';
2920 }
2921
2922 /**
2923 * Get a platform-independent path to the null file, e.g. /dev/null
2924 *
2925 * @return string
2926 */
2927 function wfGetNull() {
2928 return wfIsWindows() ? 'NUL' : '/dev/null';
2929 }
2930
2931 /**
2932 * Waits for the replica DBs to catch up to the master position
2933 *
2934 * Use this when updating very large numbers of rows, as in maintenance scripts,
2935 * to avoid causing too much lag. Of course, this is a no-op if there are no replica DBs.
2936 *
2937 * By default this waits on the main DB cluster of the current wiki.
2938 * If $cluster is set to "*" it will wait on all DB clusters, including
2939 * external ones. If the lag being waiting on is caused by the code that
2940 * does this check, it makes since to use $ifWritesSince, particularly if
2941 * cluster is "*", to avoid excess overhead.
2942 *
2943 * Never call this function after a big DB write that is still in a transaction.
2944 * This only makes sense after the possible lag inducing changes were committed.
2945 *
2946 * @param float|null $ifWritesSince Only wait if writes were done since this UNIX timestamp
2947 * @param string|bool $wiki Wiki identifier accepted by wfGetLB
2948 * @param string|bool $cluster Cluster name accepted by LBFactory. Default: false.
2949 * @param int|null $timeout Max wait time. Default: 1 day (cli), ~10 seconds (web)
2950 * @return bool Success (able to connect and no timeouts reached)
2951 * @deprecated since 1.27 Use LBFactory::waitForReplication
2952 */
2953 function wfWaitForSlaves(
2954 $ifWritesSince = null, $wiki = false, $cluster = false, $timeout = null
2955 ) {
2956 if ( $timeout === null ) {
2957 $timeout = wfIsCLI() ? 60 : 10;
2958 }
2959
2960 if ( $cluster === '*' ) {
2961 $cluster = false;
2962 $wiki = false;
2963 } elseif ( $wiki === false ) {
2964 $wiki = wfWikiID();
2965 }
2966
2967 try {
2968 $lbFactory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
2969 $lbFactory->waitForReplication( [
2970 'wiki' => $wiki,
2971 'cluster' => $cluster,
2972 'timeout' => $timeout,
2973 // B/C: first argument used to be "max seconds of lag"; ignore such values
2974 'ifWritesSince' => ( $ifWritesSince > 1e9 ) ? $ifWritesSince : null
2975 ] );
2976 } catch ( DBReplicationWaitError $e ) {
2977 return false;
2978 }
2979
2980 return true;
2981 }
2982
2983 /**
2984 * Count down from $seconds to zero on the terminal, with a one-second pause
2985 * between showing each number. For use in command-line scripts.
2986 *
2987 * @deprecated since 1.31, use Maintenance::countDown()
2988 *
2989 * @codeCoverageIgnore
2990 * @param int $seconds
2991 */
2992 function wfCountDown( $seconds ) {
2993 for ( $i = $seconds; $i >= 0; $i-- ) {
2994 if ( $i != $seconds ) {
2995 echo str_repeat( "\x08", strlen( $i + 1 ) );
2996 }
2997 echo $i;
2998 flush();
2999 if ( $i ) {
3000 sleep( 1 );
3001 }
3002 }
3003 echo "\n";
3004 }
3005
3006 /**
3007 * Replace all invalid characters with '-'.
3008 * Additional characters can be defined in $wgIllegalFileChars (see T22489).
3009 * By default, $wgIllegalFileChars includes ':', '/', '\'.
3010 *
3011 * @param string $name Filename to process
3012 * @return string
3013 */
3014 function wfStripIllegalFilenameChars( $name ) {
3015 global $wgIllegalFileChars;
3016 $illegalFileChars = $wgIllegalFileChars ? "|[" . $wgIllegalFileChars . "]" : '';
3017 $name = preg_replace(
3018 "/[^" . Title::legalChars() . "]" . $illegalFileChars . "/",
3019 '-',
3020 $name
3021 );
3022 // $wgIllegalFileChars may not include '/' and '\', so we still need to do this
3023 $name = wfBaseName( $name );
3024 return $name;
3025 }
3026
3027 /**
3028 * Set PHP's memory limit to the larger of php.ini or $wgMemoryLimit
3029 *
3030 * @return int Resulting value of the memory limit.
3031 */
3032 function wfMemoryLimit() {
3033 global $wgMemoryLimit;
3034 $memlimit = wfShorthandToInteger( ini_get( 'memory_limit' ) );
3035 if ( $memlimit != -1 ) {
3036 $conflimit = wfShorthandToInteger( $wgMemoryLimit );
3037 if ( $conflimit == -1 ) {
3038 wfDebug( "Removing PHP's memory limit\n" );
3039 Wikimedia\suppressWarnings();
3040 ini_set( 'memory_limit', $conflimit );
3041 Wikimedia\restoreWarnings();
3042 return $conflimit;
3043 } elseif ( $conflimit > $memlimit ) {
3044 wfDebug( "Raising PHP's memory limit to $conflimit bytes\n" );
3045 Wikimedia\suppressWarnings();
3046 ini_set( 'memory_limit', $conflimit );
3047 Wikimedia\restoreWarnings();
3048 return $conflimit;
3049 }
3050 }
3051 return $memlimit;
3052 }
3053
3054 /**
3055 * Set PHP's time limit to the larger of php.ini or $wgTransactionalTimeLimit
3056 *
3057 * @return int Prior time limit
3058 * @since 1.26
3059 */
3060 function wfTransactionalTimeLimit() {
3061 global $wgTransactionalTimeLimit;
3062
3063 $timeLimit = ini_get( 'max_execution_time' );
3064 // Note that CLI scripts use 0
3065 if ( $timeLimit > 0 && $wgTransactionalTimeLimit > $timeLimit ) {