WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
04/14/2014 12:19:37 AM (10 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/functions.php.

Props jesin, GaryJ.
Fixes #27715.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/functions.php

    r28094 r28109  
    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}
    … …  
    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}
    … …  
    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
    … …  
    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;
    … …  
    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() {
    … …  
    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}
    … …  
    10981149 *
    10991150 * @since 2.1.0
    1100  * @uses do_action() Calls 'do_robotstxt' hook for displaying robots.txt rules.
    11011151 */
    11021152function do_robots() {
    11031153    header( 'Content-Type: text/plain; charset=utf-8' );
    11041154
     1155    /**
     1156     * Fires when displaying the robots.txt file.
     1157     *
     1158     * @since 2.1.0
     1159     */
    11051160    do_action( 'do_robotstxt' );
    11061161
    … …  
    11161171    }
    11171172
    1118     echo apply_filters('robots_txt', $output, $public);
     1173    /**
     1174     * Filter the robots.txt output.
     1175     *
     1176     * @since 3.0.0
     1177     *
     1178     * @param string $output Robots.txt output.
     1179     * @param bool   $public Whether the site is considered "public".
     1180     */
     1181    echo apply_filters( 'robots_txt', $output, $public );
    11191182}
    11201183
    … …  
    15691632 *
    15701633 * @since 2.0.0
    1571  * @uses apply_filters() Calls 'upload_dir' on returned array.
    15721634 *
    15731635 * @param string $time Optional. Time formatted in 'yyyy/mm'.
    … …  
    16561718    $url .= $subdir;
    16571719
     1720    /**
     1721     * Filter the uploads directory data.
     1722     *
     1723     * @since 2.0.0
     1724     *
     1725     * @param array $uploads Array of upload directory data with keys of 'path',
     1726     *                       'url', 'subdir, 'basedir', and 'error'.
     1727     */
    16581728    $uploads = apply_filters( 'upload_dir',
    16591729        array(
    … …  
    17811851        return $upload;
    17821852
     1853    /**
     1854     * Filter whether to treat the upload bits as an error.
     1855     *
     1856     * Passing a non-array to the filter will effectively short-circuit preparing
     1857     * the upload bits, returning that value instead.
     1858     *
     1859     * @since 3.0.0
     1860     *
     1861     * @param mixed $upload_bits_error An array of upload bits data, or a non-array error to return.
     1862     */
    17831863    $upload_bits_error = apply_filters( 'wp_upload_bits', array( 'name' => $name, 'bits' => $bits, 'time' => $time ) );
    17841864    if ( !is_array( $upload_bits_error ) ) {
    … …  
    18251905 *
    18261906 * @since 2.5.0
    1827  * @uses apply_filters() Calls 'ext2type' hook on default supported types.
    18281907 *
    18291908 * @param string $ext The extension to search.
    1830  * @return string|null The file type, example: audio, video, document, spreadsheet, etc. Null if not found.
     1909 * @return string|null The file type, example: audio, video, document, spreadsheet, etc.
     1910 *                     Null if not found.
    18311911 */
    18321912function wp_ext2type( $ext ) {
    18331913    $ext = strtolower( $ext );
     1914
     1915    /**
     1916     * Filter file type based on the extension name.
     1917     *
     1918     * @since 2.5.0
     1919     *
     1920     * @see wp_ext2type()
     1921     *
     1922     * @param array $ext2type Multi-dimensional array with extensions for a default set
     1923     *                        of file types.
     1924     */
    18341925    $ext2type = apply_filters( 'ext2type', array(
    18351926        'image'       => array( 'jpg', 'jpeg', 'jpe',  'gif',  'png',  'bmp',   'tif',  'tiff', 'ico' ),
    … …  
    19162007        // If getimagesize() knows what kind of image it really is and if the real MIME doesn't match the claimed MIME
    19172008        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
     2009            /**
     2010             * Filter the list mapping image mime types to their respective extensions.
     2011             *
     2012             * @since 3.0.0
     2013             *
     2014             * @param  array $mime_to_ext Array of image mime types and their matching extensions.
     2015             */
    19202016            $mime_to_ext = apply_filters( 'getimagesize_mimes_to_exts', array(
    19212017                'image/jpeg' => 'jpg',
    … …  
    19432039    }
    19442040
    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 )
     2041    /**
     2042     * Filter the "real" file type of the given file.
     2043     *
     2044     * @since 3.0.0
     2045     *
     2046     * @param array  $wp_check_filetype_and_ext File data array containing 'ext', 'type', and
     2047     *                                          'proper_filename' keys.
     2048     * @param string $file                      Full path to the file.
     2049     * @param string $filename                  The name of the file (may differ from $file due to
     2050     *                                          $file being in a tmp directory).
     2051     * @param array  $mimes                     Key is the file extension with value as the mime type.
     2052     */
    19472053    return apply_filters( 'wp_check_filetype_and_ext', compact( 'ext', 'type', 'proper_filename' ), $file, $filename, $mimes );
    19482054}
    … …  
    19532059 * @since 3.5.0
    19542060 *
    1955  * @uses apply_filters() Calls 'mime_types' on returned array. This filter should
    1956  * be used to add types, not remove them. To remove types use the upload_mimes filter.
    1957  *
    19582061 * @return array Array of mime types keyed by the file extension regex corresponding to those types.
    19592062 */
    19602063function wp_get_mime_types() {
    1961     // Accepted MIME types are set here as PCRE unless provided.
     2064    /**
     2065     * Filter the list of mime types and file extensions.
     2066     *
     2067     * This filter should be used to add, not remove, mime types. To remove
     2068     * mime types, use the 'upload_mimes' filter.
     2069     *
     2070     * @since 3.5.0
     2071     *
     2072     * @param array $wp_get_mime_types Mime types keyed by the file extension regex
     2073     *                                 corresponding to those types.
     2074     */
    19622075    return apply_filters( 'mime_types', array(
    19632076    // Image formats
    … …  
    20602173 * @since 2.8.6
    20612174 *
    2062  * @uses apply_filters() Calls 'upload_mimes' on returned array
    20632175 * @uses wp_get_upload_mime_types() to fetch the list of mime types
    20642176 *
    … …  
    20762188        unset( $t['htm|html'] );
    20772189
     2190    /**
     2191     * Filter list of allowed mime types and file extensions.
     2192     *
     2193     * @since 2.0.0
     2194     *
     2195     * @param array            $t    Mime types keyed by the file extension regex corresponding to
     2196     *                               those types. 'swf' and 'exe' removed from full list. 'htm|html' also
     2197     *                               removed depending on '$user' capabilities.
     2198     * @param int|WP_User|null $user User ID, User object or null if not provided (indicates current user).
     2199     */
    20782200    return apply_filters( 'upload_mimes', $t, $user );
    20792201}
    … …  
    21202242 */
    21212243function wp_die( $message = '', $title = '', $args = array() ) {
    2122     if ( defined( 'DOING_AJAX' ) && DOING_AJAX )
     2244    if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) {
     2245        /**
     2246         * Filter callback for killing WordPress execution for AJAX requests.
     2247         *
     2248         * @since 3.4.0
     2249         *
     2250         * @param callback $function Callback function name.
     2251         */
    21232252        $function = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
    2124     elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST )
     2253    } elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
     2254        /**
     2255         * Filter callback for killing WordPress execution for XML-RPC requests.
     2256         *
     2257         * @since 3.4.0
     2258         *
     2259         * @param callback $function Callback function name.
     2260         */
    21252261        $function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
    2126     else
     2262    } else {
     2263        /**
     2264         * Filter callback for killing WordPress execution for all non-AJAX, non-XML-RPC requests.
     2265         *
     2266         * @since 3.0.0
     2267         *
     2268         * @param callback $function Callback function name.
     2269         */
    21272270        $function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
     2271    }
    21282272
    21292273    call_user_func( $function, $message, $title, $args );
    … …  
    27482892 */
    27492893function wp_maybe_load_widgets() {
    2750     if ( ! apply_filters('load_default_widgets', true) )
     2894    /**
     2895     * Filter whether to load the Widgets library.
     2896     *
     2897     * @since 2.8.0
     2898     *
     2899     * @param bool $wp_maybe_load_widgets Whether to load the Widgets library.
     2900     *                                    Default true.
     2901     */
     2902    if ( ! apply_filters( 'load_default_widgets', true ) ) {
    27512903        return;
     2904    }
    27522905    require_once( ABSPATH . WPINC . '/default-widgets.php' );
    27532906    add_action( '_admin_menu', 'wp_widgets_add_menu' );
    … …  
    28963049 * @access private
    28973050 *
    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  *
    29033051 * @param string $function The function that was called
    29043052 * @param string $version The version of WordPress that deprecated the function
    … …  
    29073055function _deprecated_function( $function, $version, $replacement = null ) {
    29083056
     3057    /**
     3058     * Fires when a deprecated function is called.
     3059     *
     3060     * @since 2.5.0
     3061     *
     3062     * @param string $function    The function that was called.
     3063     * @param string $replacement The function that should have been called.
     3064     * @param string $version     The version of WordPress that deprecated the function.
     3065     */
    29093066    do_action( 'deprecated_function_run', $function, $replacement, $version );
    29103067
    2911     // Allow plugin to filter the output error trigger
     3068    /**
     3069     * Filter whether to trigger an error for deprecated functions.
     3070     *
     3071     * @since 2.5.0
     3072     *
     3073     * @param bool $trigger Whether to trigger the error for deprecated functions. Default true.
     3074     */
    29123075    if ( WP_DEBUG && apply_filters( 'deprecated_function_trigger_error', true ) ) {
    29133076        if ( function_exists( '__' ) ) {
    … …  
    29393102 * @access private
    29403103 *
    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  *
    29463104 * @param string $file The file that was included
    29473105 * @param string $version The version of WordPress that deprecated the file
    … …  
    29513109function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
    29523110
     3111    /**
     3112     * Fires when a deprecated file is called.
     3113     *
     3114     * @since 2.5.0
     3115     *
     3116     * @param string $file        The file that was called.
     3117     * @param string $replacement The file that should have been included based on ABSPATH.
     3118     * @param string $version     The version of WordPress that deprecated the file.
     3119     * @param string $message     A message regarding the change.
     3120     */
    29533121    do_action( 'deprecated_file_included', $file, $replacement, $version, $message );
    29543122
    2955     // Allow plugin to filter the output error trigger
     3123    /**
     3124     * Filter whether to trigger an error for deprecated files.
     3125     *
     3126     * @since 2.5.0
     3127     *
     3128     * @param bool $trigger Whether to trigger the error for deprecated files. Default true.
     3129     */
    29563130    if ( WP_DEBUG && apply_filters( 'deprecated_file_trigger_error', true ) ) {
    29573131        $message = empty( $message ) ? '' : ' ' . $message;
    … …  
    29903164 * @access private
    29913165 *
    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  *
    29973166 * @param string $function The function that was called
    29983167 * @param string $version The version of WordPress that deprecated the argument used
    … …  
    30013170function _deprecated_argument( $function, $version, $message = null ) {
    30023171
     3172    /**
     3173     * Fires when a deprecated argument is called.
     3174     *
     3175     * @since 3.0.0
     3176     *
     3177     * @param string $function The function that was called.
     3178     * @param string $message  A message regarding the change.
     3179     * @param string $version  The version of WordPress that deprecated the argument used.
     3180     */
    30033181    do_action( 'deprecated_argument_run', $function, $message, $version );
    30043182
    3005     // Allow plugin to filter the output error trigger
     3183    /**
     3184     * Filter whether to trigger an error for deprecated arguments.
     3185     *
     3186     * @since 3.0.0
     3187     *
     3188     * @param bool $trigger Whether to trigger the error for deprecated arguments. Default true.
     3189     */
    30063190    if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {
    30073191        if ( function_exists( '__' ) ) {
    … …  
    30313215 * @access private
    30323216 *
    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  *
    30373217 * @param string $function The function that was called.
    30383218 * @param string $message A message explaining what has been done incorrectly.
    … …  
    30413221function _doing_it_wrong( $function, $message, $version ) {
    30423222
     3223    /**
     3224     * Fires when the given function is being used incorrectly.
     3225     *
     3226     * @since 3.1.0
     3227     *
     3228     * @param string $function The function that was called.
     3229     * @param string $message  A message explaining what has been done incorrectly.
     3230     * @param string $version  The version of WordPress where the message was added.
     3231     */
    30433232    do_action( 'doing_it_wrong_run', $function, $message, $version );
    30443233
    3045     // Allow plugin to filter the output error trigger
     3234    /**
     3235     * Filter whether to trigger an error for _doing_it_wrong() calls.
     3236     *
     3237     * @since 3.1.0
     3238     *
     3239     * @param bool $trigger Whether to trigger the error for _doing_it_wrong() calls. Default true.
     3240     */
    30463241    if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
    30473242        if ( function_exists( '__' ) ) {
    … …  
    31233318    }
    31243319
    3125     return apply_filters('iis7_supports_permalinks', $supports_permalinks);
     3320    /**
     3321     * Filter whether IIS 7+ supports pretty permalinks.
     3322     *
     3323     * @since 2.8.0
     3324     *
     3325     * @param bool $supports_permalinks Whether IIS7 supports permalinks. Default false.
     3326     */
     3327    return apply_filters( 'iis7_supports_permalinks', $supports_permalinks );
    31263328}
    31273329
    … …  
    33803582    static $global_terms = null;
    33813583    if ( is_null( $global_terms ) ) {
     3584
     3585        /**
     3586         * Filter whether global terms are enabled.
     3587         *
     3588         * Passing a non-null value to the filter will effectively short-circuit the function,
     3589         * returning the value of the 'global_terms_enabled' site option instead.
     3590         *
     3591         * @since 3.0.0
     3592         *
     3593         * @param null $anbled Whether global terms are enabled.
     3594         */
    33823595        $filter = apply_filters( 'global_terms_enabled', null );
    33833596        if ( ! is_null( $filter ) )
    … …  
    36753888    $file_data = str_replace( "\r", "\n", $file_data );
    36763889
     3890    /**
     3891     * Filter extra file headers by context.
     3892     *
     3893     * The dynamic portion of the hook name, $context, refers to the context
     3894     * where extra headers might be loaded.
     3895     *
     3896     * @since 2.9.0
     3897     *
     3898     * @param array $extra_context_headers Empty array by default.
     3899     */
    36773900    if ( $context && $extra_headers = apply_filters( "extra_{$context}_headers", array() ) ) {
    36783901        $extra_headers = array_combine( $extra_headers, $extra_headers ); // keys equal values
    … …  
    38964119    if ( empty( $protocols ) ) {
    38974120        $protocols = array( 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp' );
     4121
     4122        /**
     4123         * Filter the list of protocols allowed in HTML attributes.
     4124         *
     4125         * @since 3.0.0
     4126         *
     4127         * @param array $protocols Array of allowed protocols e.g. 'http', 'ftp', 'tel', and more.
     4128         */
    38984129        $protocols = apply_filters( 'kses_allowed_protocols', $protocols );
    38994130    }
    … …  
    40134244 */
    40144245function wp_checkdate( $month, $day, $year, $source_date ) {
     4246    /**
     4247     * Filter whether the given date is valid for the Gregorian calendar.
     4248     *
     4249     * @since 3.5.0
     4250     *
     4251     * @param bool   $checkdate   Whether the given date is valid.
     4252     * @param string $source_date Date to check.
     4253     */
    40154254    return apply_filters( 'wp_checkdate', checkdate( $month, $day, $year ), $source_date );
    40164255}
    … …  
    40384277    $show = ! in_array( $screen->id, $hidden );
    40394278
     4279    /**
     4280     * Filter whether to load the authentication check.
     4281     *
     4282     * @since 3.6.0
     4283     *
     4284     * @param bool      $show   Whether to load the authentication check.
     4285     * @param WP_Screen $screen The current screen object.
     4286     */
    40404287    if ( apply_filters( 'wp_auth_check_load', $show, $screen ) ) {
    40414288        wp_enqueue_style( 'wp-auth-check' );
    … …  
    40604307        $same_domain = false;
    40614308
    4062     // Let plugins change this if they know better.
     4309    /**
     4310     * Filter whether the authentication check originated at the same domain.
     4311     *
     4312     * @since 3.6.0
     4313     *
     4314     * @param bool $same_domain Whether the authentication check originated at the same domain.
     4315     */
    40634316    $same_domain = apply_filters( 'wp_auth_check_same_domain', $same_domain );
    40644317    $wrap_class = $same_domain ? 'hidden' : 'hidden fallback';
Note: See TracChangeset for help on using the changeset viewer.