Merge "Improve documentation for wfParseUrl"

diff --combined includes/GlobalFunctions.php
index 2090d90,f7978c5..089ed81
--- 1/includes/GlobalFunctions.php
--- 2/includes/GlobalFunctions.php
+++ b/includes/GlobalFunctions.php
@@@ -203,38 -203,6 +203,38 @@@ function wfArrayDiff2_cmp( $a, $b ) 
        }
  }
  
 +/**
 + * Like array_filter with ARRAY_FILTER_USE_BOTH, but works pre-5.6.
 + *
 + * @param array $arr
 + * @param callable $callback Will be called with the array value and key (in that order) and
 + *   should return a bool which will determine whether the array element is kept.
 + * @return array
 + */
 +function wfArrayFilter( array $arr, callable $callback ) {
 +      if ( defined( 'ARRAY_FILTER_USE_BOTH' ) ) {
 +              return array_filter( $arr, $callback, ARRAY_FILTER_USE_BOTH );
 +      }
 +      $filteredKeys = array_filter( array_keys( $arr ), function ( $key ) use ( $arr, $callback ) {
 +              return call_user_func( $callback, $arr[$key], $key );
 +      } );
 +      return array_intersect_key( $arr, array_fill_keys( $filteredKeys, true ) );
 +}
 +
 +/**
 + * Like array_filter with ARRAY_FILTER_USE_KEY, but works pre-5.6.
 + *
 + * @param array $arr
 + * @param callable $callback Will be called with the array key and should return a bool which
 + *   will determine whether the array element is kept.
 + * @return array
 + */
 +function wfArrayFilterByKey( array $arr, callable $callback ) {
 +      return wfArrayFilter( $arr, function ( $val, $key ) use ( $callback ) {
 +              return call_user_func( $callback, $key );
 +      } );
 +}
 +
  /**
   * Appends to second array if $value differs from that in $default
   *
@@@ -843,10 -811,24 +843,24 @@@ function wfUrlProtocolsWithoutProtRel(
   * 1) Does not raise warnings on bad URLs (just returns false).
   * 2) Handles protocols that don't use :// (e.g., mailto: and news:, as well as
   *    protocol-relative URLs) correctly.
-  * 3) Adds a "delimiter" element to the array, either '://', ':' or '//' (see (2)).
+  * 3) Adds a "delimiter" element to the array (see (2)).
+  * 4) Verifies that the protocol is on the $wgUrlProtocols whitelist.
+  * 5) Rejects some invalid URLs that parse_url doesn't, e.g. the empty string or URLs starting with
+  *    a line feed character.
   *
   * @param string $url A URL to parse
-  * @return string[]|bool Bits of the URL in an associative array, per PHP docs, false on failure
+  * @return string[]|bool Bits of the URL in an associative array, or false on failure.
+  *   Possible fields:
+  *   - scheme: URI scheme (protocol), e.g. 'http', 'mailto'. Lowercase, always present, but can
+  *       be an empty string for protocol-relative URLs.
+  *   - delimiter: either '://', ':' or '//'. Always present.
+  *   - host: domain name / IP. Always present, but could be an empty string, e.g. for file: URLs.
+  *   - user: user name, e.g. for HTTP Basic auth URLs such as http://user:pass@example.com/
+  *       Missing when there is no username.
+  *   - pass: password, same as above.
+  *   - path: path including the leading /. Will be missing when empty (e.g. 'http://example.com')
+  *   - query: query string (as a string; see wfCgiToArray() for parsing it), can be missing.
+  *   - fragment: the part after #, can be missing.
   */
  function wfParseUrl( $url ) {
        global $wgUrlProtocols; // Allow all protocols defined in DefaultSettings/LocalSettings.php