Ticket #27715: 27715.3.diff

src/wp-includes/functions.php

@@ -140 +140 @@
                 }
         }
         $j = @$datefunc( $dateformatstring, $i );
-        // allow plugins to redo this entirely for languages with untypical grammars
+
+        /**
+         * Filter date to allow plugins to redo this entirely for languages with untypical grammars.
+         *
+         * @since 2.8.0
+         * 
+         * @param string $j          Formatted date string.
+         * @param string $req_format Format to display the date.
+         * @param bool   $gmt        Whether to convert to GMT for time.
+         */
         $j = apply_filters('date_i18n', $j, $req_format, $i, $gmt);
         return $j;
 }
@@ -157 +166 @@
 function number_format_i18n( $number, $decimals = 0 ) {
         global $wp_locale;
         $formatted = number_format( $number, absint( $decimals ), $wp_locale->number_format['decimal_point'], $wp_locale->number_format['thousands_sep'] );
+
+        /**
+         * Filter number formatted based on the locale.
+         *
+         * @since  2.8.0
+         *
+         * @param string $formatted Converted number in string format.
+         */
         return apply_filters( 'number_format_i18n', $formatted );
 }
 
@@ -917 +934 @@
                 $protocol = 'HTTP/1.0';
         $status_header = "$protocol $code $description";
         if ( function_exists( 'apply_filters' ) )
+
+                /**
+                 * Filter a status header.
+                 *
+                 * @since 2.2.0
+                 *
+                 * @param string $status_header Status header.
+                 * @param int    $code          HTTP status code.
+                 * @param string $description   Description for the status code, empty string if not found.
+                 * @param string $protocol      Server protocol.
+                 */
                 $status_header = apply_filters( 'status_header', $status_header, $code, $description, $protocol );
 
         @header( $status_header, true, $code );
@@ -940 +968 @@
         );
 
         if ( function_exists('apply_filters') ) {
+
+                /**
+                 * Filter the cache-controlling headers.
+                 *
+                 * @since 2.8.0
+                 *
+                 * @param array $headers {
+                 *     Header names and field values.
+                 *
+                 *     @type string $Expires       Expires header.
+                 *     @type string $Cache-Control Cache-Control header.
+                 *     @type string $Pragma        Pragma header.
+                 * }
+                 */
                 $headers = (array) apply_filters('nocache_headers', $headers);
         }
         $headers['Last-Modified'] = false;
@@ -1041 +1083 @@
         if ( ! has_action( $hook ) )
                 wp_die( __( 'ERROR: This is not a valid feed template.' ), '', array( 'response' => 404 ) );
 
+        /**
+         * Fires contextually for each feed.
+         *
+         * Hook name is `do_feed_{$feed}`.
+         *
+         * @since 2.1.0
+         *
+         * @param bool $is_comment_feed True if feed is a comment feed.
+         */
         do_action( $hook, $wp_query->is_comment_feed );
 }
 
@@ -1102 +1153 @@
 function do_robots() {
         header( 'Content-Type: text/plain; charset=utf-8' );
 
+        /**
+         * Fires when displaying the robots.txt file.
+         *
+         * @since 2.1.0
+         */
         do_action( 'do_robotstxt' );
 
         $output = "User-agent: *\n";
@@ -1655 +1711 @@
         $dir .= $subdir;
         $url .= $subdir;
 
+        /**
+         * Filter the uploads directory data.
+         *
+         * @since 2.0.0
+         *
+         * @param array $uploads Array of upload directory data with keys of `path`, `url`, `subdir`,
+         *                       `basedir` and `error`.
+         */
         $uploads = apply_filters( 'upload_dir',
                 array(
                         'path'    => $dir,
@@ -1780 +1844 @@
         if ( $upload['error'] !== false )
                 return $upload;
 
+        /**
+         * Filter whether upload bits produces an error.
+         *
+         * If it is an error, then filter should not return an array.
+         *
+         * @since 3.0.0
+         *
+         * @param array $upload_bits_error Array with keys for `name`, `bits` and `time`.
+         */
         $upload_bits_error = apply_filters( 'wp_upload_bits', array( 'name' => $name, 'bits' => $bits, 'time' => $time ) );
         if ( !is_array( $upload_bits_error ) ) {
                 $upload[ 'error' ] = $upload_bits_error;
@@ -1831 +1904 @@
  */
 function wp_ext2type( $ext ) {
         $ext = strtolower( $ext );
+
+        /**
+         * Filter file type based on the extension name.
+         *
+         * @since 2.5.0
+         *
+         * @param array $ext2type Multi-dimensional array with extensions for the default keys of
+         *                        `image`, `audio`, `video`, `document`, `spreadsheet`, `interactive`,
+         *                        `text`, `archive` and `code`.
+         */
         $ext2type = apply_filters( 'ext2type', array(
                 'image'       => array( 'jpg', 'jpeg', 'jpe',  'gif',  'png',  'bmp',   'tif',  'tiff', 'ico' ),
                 'audio'       => array( 'aac', 'ac3',  'aif',  'aiff', 'm3a',  'm4a',   'm4b',  'mka',  'mp1',  'mp2',  'mp3', 'ogg', 'oga', 'ram', 'wav', 'wma' ),
@@ -1915 +1998 @@
 
                 // If getimagesize() knows what kind of image it really is and if the real MIME doesn't match the claimed MIME
                 if ( !empty($imgstats['mime']) && $imgstats['mime'] != $type ) {
-                        // This is a simplified array of MIMEs that getimagesize() can detect and their extensions
-                        // You shouldn't need to use this filter, but it's here just in case
+                        /**
+                         * Filter a simplified array of MIMEs that getimagesize() can detect and their extensions.
+                         * 
+                         * You shouldn't need to use this filter, but it's here just in case.
+                         *
+                         * @since 3.0.0
+                         *
+                         * @param  array $mime_to_ext Array of image MIMEs to extensions.
+                         */
                         $mime_to_ext = apply_filters( 'getimagesize_mimes_to_exts', array(
                                 'image/jpeg' => 'jpg',
                                 'image/png'  => 'png',
@@ -1942 +2032 @@
                 }
         }
 
-        // Let plugins try and validate other types of files
-        // Should return an array in the style of array( 'ext' => $ext, 'type' => $type, 'proper_filename' => $proper_filename )
+        /**
+         * Filter to let plugins try and validate other types of files.
+         *
+         * Should return an array in the style of:
+         * `array( 'ext' => $ext, 'type' => $type, 'proper_filename' => $proper_filename )`
+         *
+         * @since 3.0.0
+         *
+         * @param array  $wp_check_filetype_and_ext Array with keys of `ext`, `type` and
+         *                                         `proper_filename`.
+         * @param string $file                      Full path to the file.
+         * @param string $filename                  The name of the file (may differ from $file due to
+         *                                          `$file` being in a tmp directory).
+         * @param array  $mimes                     Key is the file extension with value as the mime
+         *                                          type.
+         */
         return apply_filters( 'wp_check_filetype_and_ext', compact( 'ext', 'type', 'proper_filename' ), $file, $filename, $mimes );
 }
 
@@ -1958 +2062 @@
  * @return array Array of mime types keyed by the file extension regex corresponding to those types.
  */
 function wp_get_mime_types() {
-        // Accepted MIME types are set here as PCRE unless provided.
+
+        /**
+         * Filter list of MIME types and file extensions.
+         *
+         * Accepted MIME types are set here as PCRE unless provided.
+         *
+         * @since 3.5.0
+         *
+         * @param array $wp_get_mime_types MIME types keyed by the file extension regex corresponding to those types.
+         */
         return apply_filters( 'mime_types', array(
         // Image formats
         'jpg|jpeg|jpe' => 'image/jpeg',
@@ -2075 +2188 @@
         if ( empty( $unfiltered ) )
                 unset( $t['htm|html'] );
 
+        /**
+         * Filter list of allowed MIME types and file extensions.
+         *
+         * @since 2.0.0
+         *
+         * @param array            $t MIME types keyed by the file extension regex corresponding to
+         *                         those types. `swf` and `exe` removed from full list. `htm|html` also
+         *                         removed depending on `$user` capabilities.
+         * @param int|WP_User|null $user User ID, User object or null if not provided (indicates current
+         *                         user).
+         */
         return apply_filters( 'upload_mimes', $t, $user );
 }
 
@@ -2120 +2244 @@
  */
 function wp_die( $message = '', $title = '', $args = array() ) {
         if ( defined( 'DOING_AJAX' ) && DOING_AJAX )
+                /**
+                 * Filter callback function when in `DOING_AJAX` context during `wp_die()`.
+                 *
+                 * @since 3.4.0
+                 *
+                 * @param string $function Callback function name.
+                 */
                 $function = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
         elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST )
+                /**
+                 * Filter callback function when in `XMLRPC_REQUEST` context during `wp_die()`.
+                 *
+                 * @since 3.4.0
+                 *
+                 * @param string $function Callback function name.
+                 */
                 $function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
         else
+                /**
+                 * Filter callback function when not in `DOING_AJAX` or `XMLRPC_REQUEST` contexts during
+                 * `wp_die()`.
+                 *
+                 * @since 3.0.0
+                 *
+                 * @param string $function Callback function name.
+                 */
                 $function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
 
         call_user_func( $function, $message, $title, $args );
@@ -2746 +2892 @@
  * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value.
  */
 function wp_maybe_load_widgets() {
+        /**
+         * Filter if Widgets library should be loaded.
+         *
+         * @since 2.8.0
+         *
+         * @param bool $wp_maybe_load_widgets Default is true.
+         */
         if ( ! apply_filters('load_default_widgets', true) )
                 return;
         require_once( ABSPATH . WPINC . '/default-widgets.php' );
@@ -2905 +3058 @@
  */
 function _deprecated_function( $function, $version, $replacement = null ) {
 
+        /**
+         * Fires when a function is marked as deprecated.
+         *
+         * @since 2.5.0
+         *
+         * @param string $function    The function that was called.
+         * @param string $replacement The function that should have been called.
+         * @param string $version     The version of WordPress that deprecated the function.
+         */
         do_action( 'deprecated_function_run', $function, $replacement, $version );
 
-        // Allow plugin to filter the output error trigger
+        /**
+         * Filter the deprecated function output error trigger.
+         *
+         * Allows plugins to override if just the `WP_DEBUG` being true is sufficient to trigger the
+         * error.
+         *
+         * @since 2.5.0
+         *
+         * @param bool $deprecated_function_trigger_error Default is true.
+         */
         if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {
                 if ( function_exists( '__' ) ) {
                         if ( ! is_null( $replacement ) )
@@ -2949 +3120 @@
  */
 function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
 
+        /**
+         * Fires when a file is marked as deprecated.
+         *
+         * @since 2.5.0
+         *
+         * @param string $file        The file that was called.
+         * @param string $replacement The file that should have been included based on ABSPATH.
+         * @param string $version     The version of WordPress that deprecated the file.
+         * @param string $message     A message regarding the change.
+         */
         do_action( 'deprecated_file_included', $file, $replacement, $version, $message );
 
-        // Allow plugin to filter the output error trigger
+        /**
+         * Filter the deprecated file output error trigger.
+         *
+         * Allows plugins to override if just the `WP_DEBUG` being true is sufficient to trigger the
+         * error.
+         *
+         * @since 2.5.0
+         *
+         * @param bool $deprecated_file_trigger_error Default is true.
+         */
         if ( WP_DEBUG && apply_filters( 'deprecated_file_trigger_error', true ) ) {
                 $message = empty( $message ) ? '' : ' ' . $message;
                 if ( function_exists( '__' ) ) {
@@ -2999 +3189 @@
  */
 function _deprecated_argument( $function, $version, $message = null ) {
 
+        /**
+         * Fires when an argument is marked as deprecated.
+         *
+         * @since 3.0.0
+         *
+         * @param string $function The function that was called.
+         * @param string $message  A message regarding the change.
+         * @param string $version  The version of WordPress that deprecated the argument used.
+         */
         do_action( 'deprecated_argument_run', $function, $message, $version );
 
-        // Allow plugin to filter the output error trigger
+        /**
+         * Filter the deprecated argument output error trigger.
+         *
+         * Allows plugins to override if just the `WP_DEBUG` being true is sufficient to trigger the
+         * error.
+         *
+         * @since 3.0.0
+         *
+         * @param bool $deprecated_argument_trigger_error Default is true.
+         */
         if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {
                 if ( function_exists( '__' ) ) {
                         if ( ! is_null( $message ) )
@@ -3039 +3247 @@
  */
 function _doing_it_wrong( $function, $message, $version ) {
 
+        /**
+         * Fires when something is marked as being called incorrectly.
+         *
+         * @since 3.1.0
+         *
+         * @param string $function The function that was called.
+         * @param string $message  A message explaining what has been done incorrectly.
+         * @param string $version  The version of WordPress where the message was added.
+         */
         do_action( 'doing_it_wrong_run', $function, $message, $version );
 
-        // Allow plugin to filter the output error trigger
+        /**
+         * Filter the "doing it wrong" output error trigger.
+         *
+         * Allows plugins to override if just the `WP_DEBUG` being true is sufficient to trigger the
+         * error.
+         *
+         * @since 3.1.0
+         *
+         * @param bool $doing_it_wrong_trigger_error Default is true.
+         */
         if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
                 if ( function_exists( '__' ) ) {
                         $version = is_null( $version ) ? '' : sprintf( __( '(This message was added in version %s.)' ), $version );
@@ -3121 +3347 @@
                 $supports_permalinks = class_exists('DOMDocument') && isset($_SERVER['IIS_UrlRewriteModule']) && ( php_sapi_name() == 'cgi-fcgi' );
         }
 
+        /**
+         * Filter if IIS 7+ supports pretty permalinks.
+     *
+         * @since 2.8.0
+         *
+         * @param bool $iis7_supports_permalinks True if permalinks are supported, false otherwise.
+         */
         return apply_filters('iis7_supports_permalinks', $supports_permalinks);
 }
 
@@ -3378 +3611 @@
 
         static $global_terms = null;
         if ( is_null( $global_terms ) ) {
+
+                /**
+                 * Filter to short circuit whether global terms are enabled.
+                 *
+                 * @since 3.0.0
+                 *
+                 * @param null $global_terms_enabled Expects a filter to return a truthy or falsy value.
+                 */
                 $filter = apply_filters( 'global_terms_enabled', null );
                 if ( ! is_null( $filter ) )
                         $global_terms = (bool) $filter;
@@ -3673 +3914 @@
         // Make sure we catch CR-only line endings.
         $file_data = str_replace( "\r", "\n", $file_data );
 
+        /**
+         * Filter extra file headers by context.
+         *
+         * The dynamic part of the hook, `$context`, comes directly from the `$context` function
+         * argument. If the value is the default empty string, this filter will not be called.
+         *
+         * @since 2.9.0
+         *
+         * @param array $extra_context_headers Empty array by default.
+         */
         if ( $context && $extra_headers = apply_filters( "extra_{$context}_headers", array() ) ) {
                 $extra_headers = array_combine( $extra_headers, $extra_headers ); // keys equal values
                 $all_headers = array_merge( $extra_headers, (array) $default_headers );
@@ -3894 +4145 @@
 
         if ( empty( $protocols ) ) {
                 $protocols = array( 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp' );
+                /**
+                 * Filter the list of protocols allowed in HTML atributes.
+                 * 
+                 * @since 3.0.0 
+                 *
+                 * @param array $protocols Array of allowed protocols e.g. `http`, `ftp`, `tel` and more.
+                 */
                 $protocols = apply_filters( 'kses_allowed_protocols', $protocols );
         }
 
@@ -4058 +4316 @@
         if ( $same_domain && force_ssl_login() && ! force_ssl_admin() )
                 $same_domain = false;
 
-        // Let plugins change this if they know better.
+        /**
+         * Filter the auth check same domain.
+         *
+         * @since 3.6.0
+         *
+         * @param bool $same_domain True if current domain matches login URL domain. If force SSL login
+         *                          is true and force SSL admin is false, this value becomes false.
+         */
         $same_domain = apply_filters( 'wp_auth_check_same_domain', $same_domain );
         $wrap_class = $same_domain ? 'hidden' : 'hidden fallback';