WordPress.org

Make WordPress Core

Ticket #27715: 27715.4.diff

File 27715.4.diff, 18.9 KB (added by DrewAPicture, 5 years ago)

2nd pass.

  • src/wp-includes/functions.php

     
    140140                }
    141141        }
    142142        $j = @$datefunc( $dateformatstring, $i );
    143         // allow plugins to redo this entirely for languages with untypical grammars
    144         $j = apply_filters('date_i18n', $j, $req_format, $i, $gmt);
     143
     144        /**
     145         * Filter the date formatted based on the locale.
     146         *
     147         * @since 2.8.0
     148         *
     149         * @param string $j          Formatted date string.
     150         * @param string $req_format Format to display the date.
     151         * @param int    $i          Unix timestamp.
     152         * @param bool   $gmt        Whether to convert to GMT for time. Default false.
     153         */
     154        $j = apply_filters( 'date_i18n', $j, $req_format, $i, $gmt );
    145155        return $j;
    146156}
    147157
     
    157167function number_format_i18n( $number, $decimals = 0 ) {
    158168        global $wp_locale;
    159169        $formatted = number_format( $number, absint( $decimals ), $wp_locale->number_format['decimal_point'], $wp_locale->number_format['thousands_sep'] );
     170
     171        /**
     172         * Filter the number formatted based on the locale.
     173         *
     174         * @since  2.8.0
     175         *
     176         * @param string $formatted Converted number in string format.
     177         */
    160178        return apply_filters( 'number_format_i18n', $formatted );
    161179}
    162180
     
    917935                $protocol = 'HTTP/1.0';
    918936        $status_header = "$protocol $code $description";
    919937        if ( function_exists( 'apply_filters' ) )
     938
     939                /**
     940                 * Filter an HTTP status header.
     941                 *
     942                 * @since 2.2.0
     943                 *
     944                 * @param string $status_header HTTP status header.
     945                 * @param int    $code          HTTP status code.
     946                 * @param string $description   Description for the status code.
     947                 * @param string $protocol      Server protocol.
     948                 */
    920949                $status_header = apply_filters( 'status_header', $status_header, $code, $description, $protocol );
    921950
    922951        @header( $status_header, true, $code );
     
    940969        );
    941970
    942971        if ( function_exists('apply_filters') ) {
    943                 $headers = (array) apply_filters('nocache_headers', $headers);
     972                /**
     973                 * Filter the cache-controlling headers.
     974                 *
     975                 * @since 2.8.0
     976                 *
     977                 * @param array $headers {
     978                 *     Header names and field values.
     979                 *
     980                 *     @type string $Expires       Expires header.
     981                 *     @type string $Cache-Control Cache-Control header.
     982                 *     @type string $Pragma        Pragma header.
     983                 * }
     984                 */
     985                $headers = (array) apply_filters( 'nocache_headers', $headers );
    944986        }
    945987        $headers['Last-Modified'] = false;
    946988        return $headers;
     
    10231065 * It is better to only have one hook for each feed.
    10241066 *
    10251067 * @since 2.1.0
     1068 *
    10261069 * @uses $wp_query Used to tell if the use a comment feed.
    1027  * @uses do_action() Calls 'do_feed_$feed' hook, if a hook exists for the feed.
    10281070 */
    10291071function do_feed() {
    10301072        global $wp_query;
     
    10411083        if ( ! has_action( $hook ) )
    10421084                wp_die( __( 'ERROR: This is not a valid feed template.' ), '', array( 'response' => 404 ) );
    10431085
     1086        /**
     1087         * Fires once the given feed is loaded.
     1088         *
     1089         * The dynamic hook name, $hook, refers to the feed name.
     1090         *
     1091         * @since 2.1.0
     1092         *
     1093         * @param bool $is_comment_feed Whether the feed is a comment feed.
     1094         */
    10441095        do_action( $hook, $wp_query->is_comment_feed );
    10451096}
    10461097
     
    11021153function do_robots() {
    11031154        header( 'Content-Type: text/plain; charset=utf-8' );
    11041155
     1156        /**
     1157         * Fires when displaying the robots.txt file.
     1158         *
     1159         * @since 2.1.0
     1160         */
    11051161        do_action( 'do_robotstxt' );
    11061162
    11071163        $output = "User-agent: *\n";
     
    11151171                $output .= "Disallow: $path/wp-includes/\n";
    11161172        }
    11171173
    1118         echo apply_filters('robots_txt', $output, $public);
     1174        /**
     1175         * Filter the robots.txt output.
     1176         *
     1177         * @since 3.0.0
     1178         *
     1179         * @param string $output Robots.txt output.
     1180         * @param bool   $public Whether the site is considered "public".
     1181         */
     1182        echo apply_filters( 'robots_txt', $output, $public );
    11191183}
    11201184
    11211185/**
     
    16551719        $dir .= $subdir;
    16561720        $url .= $subdir;
    16571721
     1722        /**
     1723         * Filter the uploads directory data.
     1724         *
     1725         * @since 2.0.0
     1726         *
     1727         * @param array $uploads Array of upload directory data with keys of 'path',
     1728         *                       'url', 'subdir, 'basedir', and 'error'.
     1729         */
    16581730        $uploads = apply_filters( 'upload_dir',
    16591731                array(
    16601732                        'path'    => $dir,
     
    17801852        if ( $upload['error'] !== false )
    17811853                return $upload;
    17821854
     1855        /**
     1856         * Filter whether to treat the upload bits as an error.
     1857         *
     1858         * Passing a non-array to the filter will effectively short-circuit preparing
     1859         * the upload bits, returning that value instead.
     1860         *
     1861         * @since 3.0.0
     1862         *
     1863         * @param mixed $upload_bits_error An array of upload bits data, or a non-array error to return.
     1864         */
    17831865        $upload_bits_error = apply_filters( 'wp_upload_bits', array( 'name' => $name, 'bits' => $bits, 'time' => $time ) );
    17841866        if ( !is_array( $upload_bits_error ) ) {
    17851867                $upload[ 'error' ] = $upload_bits_error;
     
    18271909 * @uses apply_filters() Calls 'ext2type' hook on default supported types.
    18281910 *
    18291911 * @param string $ext The extension to search.
    1830  * @return string|null The file type, example: audio, video, document, spreadsheet, etc. Null if not found.
     1912 * @return string|null The file type, example: audio, video, document, spreadsheet, etc.
     1913 *                     Null if not found.
    18311914 */
    18321915function wp_ext2type( $ext ) {
    18331916        $ext = strtolower( $ext );
     1917
     1918        /**
     1919         * Filter file type based on the extension name.
     1920         *
     1921         * @since 2.5.0
     1922         *
     1923         * @see wp_ext2type()
     1924         *
     1925         * @param array $ext2type Multi-dimensional array with extensions for a default set
     1926         *                        of file types.
     1927         */
    18341928        $ext2type = apply_filters( 'ext2type', array(
    18351929                'image'       => array( 'jpg', 'jpeg', 'jpe',  'gif',  'png',  'bmp',   'tif',  'tiff', 'ico' ),
    18361930                'audio'       => array( 'aac', 'ac3',  'aif',  'aiff', 'm3a',  'm4a',   'm4b',  'mka',  'mp1',  'mp2',  'mp3', 'ogg', 'oga', 'ram', 'wav', 'wma' ),
     
    19152009
    19162010                // If getimagesize() knows what kind of image it really is and if the real MIME doesn't match the claimed MIME
    19172011                if ( !empty($imgstats['mime']) && $imgstats['mime'] != $type ) {
    1918                         // This is a simplified array of MIMEs that getimagesize() can detect and their extensions
    1919                         // You shouldn't need to use this filter, but it's here just in case
     2012                        /**
     2013                         * Filter the list mapping image mime types to their respective extensions.
     2014                         *
     2015                         * @since 3.0.0
     2016                         *
     2017                         * @param  array $mime_to_ext Array of image mime types and their matching extensions.
     2018                         */
    19202019                        $mime_to_ext = apply_filters( 'getimagesize_mimes_to_exts', array(
    19212020                                'image/jpeg' => 'jpg',
    19222021                                'image/png'  => 'png',
     
    19422041                }
    19432042        }
    19442043
    1945         // Let plugins try and validate other types of files
    1946         // Should return an array in the style of array( 'ext' => $ext, 'type' => $type, 'proper_filename' => $proper_filename )
     2044        /**
     2045         * Filter the "real" file type of the given file.
     2046         *
     2047         * @since 3.0.0
     2048         *
     2049         * @param array  $wp_check_filetype_and_ext File data array containing 'ext', 'type', and
     2050         *                                          'proper_filename' keys.
     2051         * @param string $file                      Full path to the file.
     2052         * @param string $filename                  The name of the file (may differ from $file due to
     2053         *                                          $file being in a tmp directory).
     2054         * @param array  $mimes                     Key is the file extension with value as the mime type.
     2055         */
    19472056        return apply_filters( 'wp_check_filetype_and_ext', compact( 'ext', 'type', 'proper_filename' ), $file, $filename, $mimes );
    19482057}
    19492058
     
    19582067 * @return array Array of mime types keyed by the file extension regex corresponding to those types.
    19592068 */
    19602069function wp_get_mime_types() {
    1961         // Accepted MIME types are set here as PCRE unless provided.
     2070        /**
     2071         * Filter the list of mime types and file extensions.
     2072         *
     2073         * @since 3.5.0
     2074         *
     2075         * @param array $wp_get_mime_types Mime types keyed by the file extension regex
     2076         *                                 corresponding to those types.
     2077         */
    19622078        return apply_filters( 'mime_types', array(
    19632079        // Image formats
    19642080        'jpg|jpeg|jpe' => 'image/jpeg',
     
    20752191        if ( empty( $unfiltered ) )
    20762192                unset( $t['htm|html'] );
    20772193
     2194        /**
     2195         * Filter list of allowed mime types and file extensions.
     2196         *
     2197         * @since 2.0.0
     2198         *
     2199         * @param array            $t Mime types keyed by the file extension regex corresponding to
     2200         *                         those types. 'swf' and 'exe' removed from full list. 'htm|html' also
     2201         *                         removed depending on '$user' capabilities.
     2202         * @param int|WP_User|null $user User ID, User object or null if not provided (indicates current
     2203         *                         user).
     2204         */
    20782205        return apply_filters( 'upload_mimes', $t, $user );
    20792206}
    20802207
     
    21192246 * @param string|array $args Optional arguments to control behavior.
    21202247 */
    21212248function wp_die( $message = '', $title = '', $args = array() ) {
    2122         if ( defined( 'DOING_AJAX' ) && DOING_AJAX )
     2249        if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) {
     2250
     2251                /**
     2252                 * Filter callback for killing WordPress execution for AJAX requests.
     2253                 *
     2254                 * @since 3.4.0
     2255                 *
     2256                 * @param callback $function Callback function name.
     2257                 */
    21232258                $function = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
    2124         elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST )
     2259        } elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
     2260
     2261                /**
     2262                 * Filter callback for killing WordPress execution for XML-RPC requests.
     2263                 *
     2264                 * @since 3.4.0
     2265                 *
     2266                 * @param callback $function Callback function name.
     2267                 */
    21252268                $function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
    2126         else
     2269        } else {
     2270
     2271                /**
     2272                 * Filter callback for killing WordPress execution for all non-AJAX, non-XML-RPC requests.
     2273                 *
     2274                 * @since 3.0.0
     2275                 *
     2276                 * @param callback $function Callback function name.
     2277                 */
    21272278                $function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
     2279        }
    21282280
    21292281        call_user_func( $function, $message, $title, $args );
    21302282}
     
    27472899 * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value.
    27482900 */
    27492901function wp_maybe_load_widgets() {
    2750         if ( ! apply_filters('load_default_widgets', true) )
     2902        /**
     2903         * Filter whether to load the Widgets library.
     2904         *
     2905         * @since 2.8.0
     2906         *
     2907         * @param bool $wp_maybe_load_widgets Whether to load the Widgets library.
     2908         *                                    Default true.
     2909         */
     2910        if ( ! apply_filters( 'load_default_widgets', true ) ) {
    27512911                return;
     2912        }
    27522913        require_once( ABSPATH . WPINC . '/default-widgets.php' );
    27532914        add_action( '_admin_menu', 'wp_widgets_add_menu' );
    27542915}
     
    28953056 * @since 2.5.0
    28963057 * @access private
    28973058 *
    2898  * @uses do_action() Calls 'deprecated_function_run' and passes the function name, what to use instead,
    2899  *   and the version the function was deprecated in.
    2900  * @uses apply_filters() Calls 'deprecated_function_trigger_error' and expects boolean value of true to do
    2901  *   trigger or false to not trigger error.
    2902  *
    29033059 * @param string $function The function that was called
    29043060 * @param string $version The version of WordPress that deprecated the function
    29053061 * @param string $replacement Optional. The function that should have been called
    29063062 */
    29073063function _deprecated_function( $function, $version, $replacement = null ) {
    29083064
     3065        /**
     3066         * Fires when a deprecated function is called.
     3067         *
     3068         * @since 2.5.0
     3069         *
     3070         * @param string $function    The function that was called.
     3071         * @param string $replacement The function that should have been called.
     3072         * @param string $version     The version of WordPress that deprecated the function.
     3073         */
    29093074        do_action( 'deprecated_function_run', $function, $replacement, $version );
    29103075
    2911         // Allow plugin to filter the output error trigger
     3076        /**
     3077         * Filter whether to trigger an error for deprecated functions.
     3078         *
     3079         * @since 2.5.0
     3080         *
     3081         * @param bool $trigger Whether to trigger the error for deprecated functions. Default true.
     3082         */
    29123083        if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {
    29133084                if ( function_exists( '__' ) ) {
    29143085                        if ( ! is_null( $replacement ) )
     
    29383109 * @since 2.5.0
    29393110 * @access private
    29403111 *
    2941  * @uses do_action() Calls 'deprecated_file_included' and passes the file name, what to use instead,
    2942  *   the version in which the file was deprecated, and any message regarding the change.
    2943  * @uses apply_filters() Calls 'deprecated_file_trigger_error' and expects boolean value of true to do
    2944  *   trigger or false to not trigger error.
    2945  *
    29463112 * @param string $file The file that was included
    29473113 * @param string $version The version of WordPress that deprecated the file
    29483114 * @param string $replacement Optional. The file that should have been included based on ABSPATH
     
    29503116 */
    29513117function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
    29523118
     3119        /**
     3120         * Fires when a deprecated file is called.
     3121         *
     3122         * @since 2.5.0
     3123         *
     3124         * @param string $file        The file that was called.
     3125         * @param string $replacement The file that should have been included based on ABSPATH.
     3126         * @param string $version     The version of WordPress that deprecated the file.
     3127         * @param string $message     A message regarding the change.
     3128         */
    29533129        do_action( 'deprecated_file_included', $file, $replacement, $version, $message );
    29543130
    2955         // Allow plugin to filter the output error trigger
     3131        /**
     3132         * Filter whether to trigger an error for deprecated files.
     3133         *
     3134         * @since 2.5.0
     3135         *
     3136         * @param bool $trigger Whether to trigger the error for deprecated files. Default true.
     3137         */
    29563138        if ( WP_DEBUG && apply_filters( 'deprecated_file_trigger_error', true ) ) {
    29573139                $message = empty( $message ) ? '' : ' ' . $message;
    29583140                if ( function_exists( '__' ) ) {
     
    29893171 * @since 3.0.0
    29903172 * @access private
    29913173 *
    2992  * @uses do_action() Calls 'deprecated_argument_run' and passes the function name, a message on the change,
    2993  *   and the version in which the argument was deprecated.
    2994  * @uses apply_filters() Calls 'deprecated_argument_trigger_error' and expects boolean value of true to do
    2995  *   trigger or false to not trigger error.
    2996  *
    29973174 * @param string $function The function that was called
    29983175 * @param string $version The version of WordPress that deprecated the argument used
    29993176 * @param string $message Optional. A message regarding the change.
    30003177 */
    30013178function _deprecated_argument( $function, $version, $message = null ) {
    30023179
     3180        /**
     3181         * Fires when a deprecated argument is called.
     3182         *
     3183         * @since 3.0.0
     3184         *
     3185         * @param string $function The function that was called.
     3186         * @param string $message  A message regarding the change.
     3187         * @param string $version  The version of WordPress that deprecated the argument used.
     3188         */
    30033189        do_action( 'deprecated_argument_run', $function, $message, $version );
    30043190
    3005         // Allow plugin to filter the output error trigger
     3191        /**
     3192         * Filter whether to trigger an error for deprecated arguments.
     3193         *
     3194         * @since 3.0.0
     3195         *
     3196         * @param bool $trigger Whether to trigger the error for deprecated arguments. Default true.
     3197         */
    30063198        if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {
    30073199                if ( function_exists( '__' ) ) {
    30083200                        if ( ! is_null( $message ) )
     
    30303222 * @since 3.1.0
    30313223 * @access private
    30323224 *
    3033  * @uses do_action() Calls 'doing_it_wrong_run' and passes the function arguments.
    3034  * @uses apply_filters() Calls 'doing_it_wrong_trigger_error' and expects boolean value of true to do
    3035  *   trigger or false to not trigger error.
    3036  *
    30373225 * @param string $function The function that was called.
    30383226 * @param string $message A message explaining what has been done incorrectly.
    30393227 * @param string $version The version of WordPress where the message was added.
    30403228 */
    30413229function _doing_it_wrong( $function, $message, $version ) {
    30423230
     3231        /**
     3232         * Fires when the given function is being used incorrectly.
     3233         *
     3234         * @since 3.1.0
     3235         *
     3236         * @param string $function The function that was called.
     3237         * @param string $message  A message explaining what has been done incorrectly.
     3238         * @param string $version  The version of WordPress where the message was added.
     3239         */
    30433240        do_action( 'doing_it_wrong_run', $function, $message, $version );
    30443241
    3045         // Allow plugin to filter the output error trigger
     3242        /**
     3243         * Filter whether to trigger an error for _doing_it_wrong() calls.
     3244         *
     3245         * @since 3.1.0
     3246         *
     3247         * @param bool $trigger Whether to trigger the error for _doing_it_wrong() calls. Default true.
     3248         */
    30463249        if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
    30473250                if ( function_exists( '__' ) ) {
    30483251                        $version = is_null( $version ) ? '' : sprintf( __( '(This message was added in version %s.)' ), $version );
     
    31223325                $supports_permalinks = class_exists('DOMDocument') && isset($_SERVER['IIS_UrlRewriteModule']) && ( php_sapi_name() == 'cgi-fcgi' );
    31233326        }
    31243327
     3328        /**
     3329         * Filter whether IIS 7+ supports pretty permalinks.
     3330     *
     3331         * @since 2.8.0
     3332         *
     3333         * @param bool $supports_permalinks Whether IIS7 supports permalinks. Default false.
     3334         */
    31253335        return apply_filters('iis7_supports_permalinks', $supports_permalinks);
    31263336}
    31273337
     
    33793589
    33803590        static $global_terms = null;
    33813591        if ( is_null( $global_terms ) ) {
     3592
     3593                /**
     3594                 * Filter whether global terms are enabled.
     3595                 *
     3596                 * Passing a non-null value to the filter will effectively short-circuit the function,
     3597                 * returning the value of the 'global_terms_enabled' site option instead.
     3598                 *
     3599                 * @since 3.0.0
     3600                 *
     3601                 * @param null $anbled Whether global terms are enabled.
     3602                 */
    33823603                $filter = apply_filters( 'global_terms_enabled', null );
    33833604                if ( ! is_null( $filter ) )
    33843605                        $global_terms = (bool) $filter;
     
    36743895        // Make sure we catch CR-only line endings.
    36753896        $file_data = str_replace( "\r", "\n", $file_data );
    36763897
     3898        /**
     3899         * Filter extra file headers by context.
     3900         *
     3901         * The dynamic portion of the hook name, $context, refers to the context where extra headers might be loaded.
     3902         *
     3903         * @since 2.9.0
     3904         *
     3905         * @param array $extra_context_headers Empty array by default.
     3906         */
    36773907        if ( $context && $extra_headers = apply_filters( "extra_{$context}_headers", array() ) ) {
    36783908                $extra_headers = array_combine( $extra_headers, $extra_headers ); // keys equal values
    36793909                $all_headers = array_merge( $extra_headers, (array) $default_headers );
     
    38954125
    38964126        if ( empty( $protocols ) ) {
    38974127                $protocols = array( 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp' );
     4128                /**
     4129                 * Filter the list of protocols allowed in HTML attributes.
     4130                 *
     4131                 * @since 3.0.0
     4132                 *
     4133                 * @param array $protocols Array of allowed protocols e.g. 'http', 'ftp', 'tel', and more.
     4134                 */
    38984135                $protocols = apply_filters( 'kses_allowed_protocols', $protocols );
    38994136        }
    39004137
     
    40594296        if ( $same_domain && force_ssl_login() && ! force_ssl_admin() )
    40604297                $same_domain = false;
    40614298
    4062         // Let plugins change this if they know better.
     4299        /**
     4300         * Filter whether the authentication check originated at the same domain.
     4301         *
     4302         * Filter the auth check same domain.
     4303         *
     4304         * @since 3.6.0
     4305         *
     4306         * @param bool $same_domain Whether the authentication check originated at the same domain.
     4307         */
    40634308        $same_domain = apply_filters( 'wp_auth_check_same_domain', $same_domain );
    40644309        $wrap_class = $same_domain ? 'hidden' : 'hidden fallback';
    40654310