X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/4713a14935b83517997f3c88f808eb41da55033d..fc24d733700d6d2bd886ffa9188df5c78069b018:/wp-includes/functions.php diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 88e59fb1..d903349c 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -8,7 +8,7 @@ require( ABSPATH . WPINC . '/option.php' ); /** - * Converts given date string into a different format. + * Convert given date string into a different format. * * $format should be either a PHP date format string, e.g. 'U' for a Unix * timestamp, or 'G' for a Unix timestamp assuming that $date is GMT. @@ -18,10 +18,10 @@ require( ABSPATH . WPINC . '/option.php' ); * * @since 0.71 * - * @param string $format Format of the date to return. - * @param string $date Date string to convert. - * @param bool $translate Whether the return date should be translated. Default is true. - * @return string|int Formatted date string, or Unix timestamp. + * @param string $format Format of the date to return. + * @param string $date Date string to convert. + * @param bool $translate Whether the return date should be translated. Default true. + * @return string|int|bool Formatted date string or Unix timestamp. False if $date is empty. */ function mysql2date( $format, $date, $translate = true ) { if ( empty( $date ) ) @@ -53,21 +53,19 @@ function mysql2date( $format, $date, $translate = true ) { * * @since 1.0.0 * - * @param string $type 'mysql', 'timestamp', or PHP date format string (e.g. 'Y-m-d'). - * @param int|bool $gmt Optional. Whether to use GMT timezone. Default is false. - * @return int|string String if $type is 'gmt', int if $type is 'timestamp'. + * @param string $type Type of time to retrieve. Accepts 'mysql', 'timestamp', or PHP date + * format string (e.g. 'Y-m-d'). + * @param int|bool $gmt Optional. Whether to use GMT timezone. Default false. + * @return int|string Integer if $type is 'timestamp', string otherwise. */ function current_time( $type, $gmt = 0 ) { switch ( $type ) { case 'mysql': return ( $gmt ) ? gmdate( 'Y-m-d H:i:s' ) : gmdate( 'Y-m-d H:i:s', ( time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) ) ); - break; case 'timestamp': return ( $gmt ) ? time() : time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ); - break; default: return ( $gmt ) ? date( $type ) : date( $type, time() + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) ); - break; } } @@ -80,9 +78,10 @@ function current_time( $type, $gmt = 0 ) { * * @since 0.71 * - * @param string $dateformatstring Format to display the date. - * @param int $unixtimestamp Optional. Unix timestamp. - * @param bool $gmt Optional, default is false. Whether to convert to GMT for time. + * @param string $dateformatstring Format to display the date. + * @param bool|int $unixtimestamp Optional. Unix timestamp. Default false. + * @param bool $gmt Optional. Whether to use GMT timezone. Default false. + * * @return string The date, translated if locale specifies it. */ function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) { @@ -99,8 +98,10 @@ function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) { $gmt = true; } - // store original value for language with untypical grammars - // see http://core.trac.wordpress.org/ticket/9396 + /* + * Store original value for language with untypical grammars. + * See https://core.trac.wordpress.org/ticket/9396 + */ $req_format = $dateformatstring; $datefunc = $gmt? 'gmdate' : 'date'; @@ -145,7 +146,7 @@ function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) { * Filter the date formatted based on the locale. * * @since 2.8.0 - * + * * @param string $j Formatted date string. * @param string $req_format Format to display the date. * @param int $i Unix timestamp. @@ -160,8 +161,8 @@ function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) { * * @since 2.3.0 * - * @param int $number The number to convert based on locale. - * @param int $decimals Precision of the number of decimal places. + * @param int $number The number to convert based on locale. + * @param int $decimals Optional. Precision of the number of decimal places. Default 0. * @return string Converted number in string format. */ function number_format_i18n( $number, $decimals = 0 ) { @@ -191,13 +192,12 @@ function number_format_i18n( $number, $decimals = 0 ) { * be converted to a double, which should always have 64 bit length. * * Technically the correct unit names for powers of 1024 are KiB, MiB etc. - * @link http://en.wikipedia.org/wiki/Byte * * @since 2.3.0 * - * @param int|string $bytes Number of bytes. Note max integer size for integers. - * @param int $decimals Precision of number of decimal places. Deprecated. - * @return bool|string False on failure. Number string on success. + * @param int|string $bytes Number of bytes. Note max integer size for integers. + * @param int $decimals Optional. Precision of number of decimal places. Default 0. + * @return string|false False on failure. Number string on success. */ function size_format( $bytes, $decimals = 0 ) { $quant = array( @@ -216,28 +216,41 @@ function size_format( $bytes, $decimals = 0 ) { } /** - * Get the week start and end from the datetime or date string from mysql. + * Get the week start and end from the datetime or date string from MySQL. * * @since 0.71 * - * @param string $mysqlstring Date or datetime field type from mysql. - * @param int $start_of_week Optional. Start of the week as an integer. + * @param string $mysqlstring Date or datetime field type from MySQL. + * @param int|string $start_of_week Optional. Start of the week as an integer. Default empty string. * @return array Keys are 'start' and 'end'. */ function get_weekstartend( $mysqlstring, $start_of_week = '' ) { - $my = substr( $mysqlstring, 0, 4 ); // Mysql string Year - $mm = substr( $mysqlstring, 8, 2 ); // Mysql string Month - $md = substr( $mysqlstring, 5, 2 ); // Mysql string day - $day = mktime( 0, 0, 0, $md, $mm, $my ); // The timestamp for mysqlstring day. - $weekday = date( 'w', $day ); // The day of the week from the timestamp + // MySQL string year. + $my = substr( $mysqlstring, 0, 4 ); + + // MySQL string month. + $mm = substr( $mysqlstring, 8, 2 ); + + // MySQL string day. + $md = substr( $mysqlstring, 5, 2 ); + + // The timestamp for MySQL string day. + $day = mktime( 0, 0, 0, $md, $mm, $my ); + + // The day of the week from the timestamp. + $weekday = date( 'w', $day ); + if ( !is_numeric($start_of_week) ) $start_of_week = get_option( 'start_of_week' ); if ( $weekday < $start_of_week ) $weekday += 7; - $start = $day - DAY_IN_SECONDS * ( $weekday - $start_of_week ); // The most recent week start day on or before $day - $end = $start + 7 * DAY_IN_SECONDS - 1; // $start + 7 days - 1 second + // The most recent week start day on or before $day. + $start = $day - DAY_IN_SECONDS * ( $weekday - $start_of_week ); + + // $start + 7 days - 1 second. + $end = $start + 7 * DAY_IN_SECONDS - 1; return compact( 'start', 'end' ); } @@ -263,12 +276,12 @@ function maybe_unserialize( $original ) { * * @since 2.0.5 * - * @param mixed $data Value to check to see if was serialized. - * @param bool $strict Optional. Whether to be strict about the end of the string. Defaults true. + * @param string $data Value to check to see if was serialized. + * @param bool $strict Optional. Whether to be strict about the end of the string. Default true. * @return bool False if not serialized and true if it was. */ function is_serialized( $data, $strict = true ) { - // if it isn't a string, it isn't serialized + // if it isn't a string, it isn't serialized. if ( ! is_string( $data ) ) { return false; } @@ -327,11 +340,11 @@ function is_serialized( $data, $strict = true ) { * * @since 2.0.5 * - * @param mixed $data Serialized data + * @param string $data Serialized data. * @return bool False if not a serialized string, true if it is. */ function is_serialized_string( $data ) { - // if it isn't a string, it isn't a serialized string + // if it isn't a string, it isn't a serialized string. if ( ! is_string( $data ) ) { return false; } @@ -356,7 +369,7 @@ function is_serialized_string( $data ) { * * @since 2.0.5 * - * @param mixed $data Data that might be serialized. + * @param string|array|object $data Data that might be serialized. * @return mixed A scalar data */ function maybe_serialize( $data ) { @@ -364,7 +377,7 @@ function maybe_serialize( $data ) { return serialize( $data ); // Double serialization is required for backward compatibility. - // See http://core.trac.wordpress.org/ticket/12930 + // See https://core.trac.wordpress.org/ticket/12930 if ( is_serialized( $data, false ) ) return serialize( $data ); @@ -379,7 +392,7 @@ function maybe_serialize( $data ) { * * @since 0.71 * - * @global string $post_default_title Default XMLRPC post title. + * @global string $post_default_title Default XML-RPC post title. * * @param string $content XMLRPC XML Request content * @return string Post title @@ -403,7 +416,7 @@ function xmlrpc_getposttitle( $content ) { * * @since 0.71 * - * @global string $post_default_category Default XMLRPC post category. + * @global string $post_default_category Default XML-RPC post category. * * @param string $content XMLRPC XML Request content * @return string|array List of categories or category name. @@ -424,7 +437,7 @@ function xmlrpc_getpostcategory( $content ) { * * @since 0.71 * - * @param string $content XMLRPC XML Request content + * @param string $content XML-RPC XML Request content. * @return string XMLRPC XML Request content without title and category elements. */ function xmlrpc_removepostdata( $content ) { @@ -435,21 +448,32 @@ function xmlrpc_removepostdata( $content ) { } /** - * Use RegEx to extract URLs from arbitrary content + * Use RegEx to extract URLs from arbitrary content. * * @since 3.7.0 * - * @param string $content - * @return array URLs found in passed string + * @param string $content Content to extract URLs from. + * @return array URLs found in passed string. */ function wp_extract_urls( $content ) { preg_match_all( - "#((?:[\w-]+://?|[\w\d]+[.])[^\s()<>]+[.](?:\([\w\d]+\)|(?:[^`!()\[\]{};:'\".,<>?«»“”‘’\s]|(?:[:]\d+)?/?)+))#", + "#([\"']?)(" + . "(?:([\w-]+:)?//?)" + . "[^\s()<>]+" + . "[.]" + . "(?:" + . "\([\w\d]+\)|" + . "(?:" + . "[^`!()\[\]{};:'\".,<>«»“”‘’\s]|" + . "(?:[:]\d+)?/?" + . ")+" + . ")" + . ")\\1#", $content, $post_links ); - $post_links = array_unique( array_map( 'html_entity_decode', $post_links[0] ) ); + $post_links = array_unique( array_map( 'html_entity_decode', $post_links[2] ) ); return array_values( $post_links ); } @@ -463,10 +487,10 @@ function wp_extract_urls( $content ) { * * @since 1.5.0 * - * @uses $wpdb + * @see $wpdb * - * @param string $content Post Content - * @param int $post_ID Post ID + * @param string $content Post Content. + * @param int $post_ID Post ID. */ function do_enclose( $content, $post_ID ) { global $wpdb; @@ -482,7 +506,7 @@ function do_enclose( $content, $post_ID ) { foreach ( $pung as $link_test ) { if ( ! in_array( $link_test, $post_links_temp ) ) { // link no longer in post - $mids = $wpdb->get_col( $wpdb->prepare("SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = 'enclosure' AND meta_value LIKE (%s)", $post_ID, like_escape( $link_test ) . '%') ); + $mids = $wpdb->get_col( $wpdb->prepare("SELECT meta_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = 'enclosure' AND meta_value LIKE %s", $post_ID, $wpdb->esc_like( $link_test ) . '%') ); foreach ( $mids as $mid ) delete_metadata_by_mid( 'post', $mid ); } @@ -501,7 +525,7 @@ function do_enclose( $content, $post_ID ) { } foreach ( (array) $post_links as $url ) { - if ( $url != '' && !$wpdb->get_var( $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = 'enclosure' AND meta_value LIKE (%s)", $post_ID, like_escape( $url ) . '%' ) ) ) { + if ( $url != '' && !$wpdb->get_var( $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta WHERE post_id = %d AND meta_key = 'enclosure' AND meta_value LIKE %s", $post_ID, $wpdb->esc_like( $url ) . '%' ) ) ) { if ( $headers = wp_get_http_headers( $url) ) { $len = isset( $headers['content-length'] ) ? (int) $headers['content-length'] : 0; @@ -539,9 +563,10 @@ function do_enclose( $content, $post_ID ) { * * @since 2.5.0 * - * @param string $url URL to fetch. - * @param string|bool $file_path Optional. File path to write request to. - * @param int $red (private) The number of Redirects followed, Upon 5 being hit, returns false. + * @param string $url URL to fetch. + * @param string|bool $file_path Optional. File path to write request to. Default false. + * @param int $red Optional. The number of Redirects followed, Upon 5 being hit, + * returns false. Default 1. * @return bool|string False on failure and string of headers if HEAD request. */ function wp_get_http( $url, $file_path = false, $red = 1 ) { @@ -591,8 +616,8 @@ function wp_get_http( $url, $file_path = false, $red = 1 ) { * * @since 1.5.1 * - * @param string $url - * @param bool $deprecated Not Used. + * @param string $url URL to retrieve HTTP headers from. + * @param bool $deprecated Not Used. * @return bool|string False on failure, headers on success. */ function wp_get_http_headers( $url, $deprecated = false ) { @@ -608,11 +633,13 @@ function wp_get_http_headers( $url, $deprecated = false ) { } /** - * Whether today is a new day. + * Whether the publish date of the current post in the loop is different from the + * publish date of the previous post in the loop. * * @since 0.71 - * @uses $day Today - * @uses $previousday Previous day + * + * @global string $currentday The day of the current post in the loop. + * @global string $previousday The day of the previous post in the loop. * * @return int 1 when new day, 0 if not a new day. */ @@ -630,21 +657,38 @@ function is_new_day() { * This is a convenient function for easily building url queries. It sets the * separator to '&' and uses _http_build_query() function. * + * @since 2.3.0 + * * @see _http_build_query() Used to build the query - * @link http://us2.php.net/manual/en/function.http-build-query.php more on what + * @see http://us2.php.net/manual/en/function.http-build-query.php for more on what * http_build_query() does. * - * @since 2.3.0 - * * @param array $data URL-encode key/value pairs. - * @return string URL encoded string + * @return string URL-encoded string. */ function build_query( $data ) { return _http_build_query( $data, null, '&', '', false ); } -// from php.net (modified by Mark Jaquith to behave like the native PHP5 function) -function _http_build_query($data, $prefix=null, $sep=null, $key='', $urlencode=true) { +/** + * From php.net (modified by Mark Jaquith to behave like the native PHP5 function). + * + * @since 3.2.0 + * @access private + * + * @see http://us1.php.net/manual/en/function.http-build-query.php + * + * @param array|object $data An array or object of data. Converted to array. + * @param string $prefix Optional. Numeric index. If set, start parameter numbering with it. + * Default null. + * @param string $sep Optional. Argument separator; defaults to 'arg_separator.output'. + * Default null. + * @param string $key Optional. Used to prefix key name. Default empty. + * @param bool $urlencode Optional. Whether to use urlencode() in the result. Default true. + * + * @return string The query string. + */ +function _http_build_query( $data, $prefix = null, $sep = null, $key = '', $urlencode = true ) { $ret = array(); foreach ( (array) $data as $k => $v ) { @@ -686,13 +730,12 @@ function _http_build_query($data, $prefix=null, $sep=null, $key='', $urlencode=t * * @since 1.5.0 * - * @param mixed $param1 Either newkey or an associative_array - * @param mixed $param2 Either newvalue or oldquery or uri - * @param mixed $param3 Optional. Old query or uri + * @param string|array $param1 Either newkey or an associative_array. + * @param string $param2 Either newvalue or oldquery or URI. + * @param string $param3 Optional. Old query or URI. * @return string New URL query string. */ function add_query_arg() { - $ret = ''; $args = func_get_args(); if ( is_array( $args[0] ) ) { if ( count( $args ) < 2 || false === $args[1] ) @@ -759,11 +802,11 @@ function add_query_arg() { * * @since 1.5.0 * - * @param string|array $key Query key or keys to remove. - * @param bool $query When false uses the $_SERVER value. + * @param string|array $key Query key or keys to remove. + * @param bool|string $query Optional. When false uses the $_SERVER value. Default false. * @return string New URL query string. */ -function remove_query_arg( $key, $query=false ) { +function remove_query_arg( $key, $query = false ) { if ( is_array( $key ) ) { // removing multiple keys foreach ( $key as $k ) $query = add_query_arg( $k, false, $query ); @@ -795,10 +838,11 @@ function add_magic_quotes( $array ) { * HTTP request for URI to retrieve content. * * @since 1.5.1 - * @uses wp_remote_get() + * + * @see wp_safe_remote_get() * * @param string $uri URI/URL of web page to retrieve. - * @return bool|string HTTP content. False on failure. + * @return false|string HTTP content. False on failure. */ function wp_remote_fopen( $uri ) { $parsed_url = @parse_url( $uri ); @@ -920,6 +964,7 @@ function get_status_header_desc( $code ) { * Set HTTP status header. * * @since 2.0.0 + * * @see get_status_header_desc() * * @param int $code HTTP status code. @@ -952,10 +997,10 @@ function status_header( $code ) { } /** - * Gets the header information to prevent caching. + * Get the header information to prevent caching. * - * The several different headers cover the different ways cache prevention is handled - * by different browsers + * The several different headers cover the different ways cache prevention + * is handled by different browsers * * @since 2.8.0 * @@ -974,6 +1019,8 @@ function wp_get_nocache_headers() { * * @since 2.8.0 * + * @see wp_get_nocache_headers() + * * @param array $headers { * Header names and field values. * @@ -989,12 +1036,14 @@ function wp_get_nocache_headers() { } /** - * Sets the headers to prevent caching for the different browsers. + * Set the headers to prevent caching for the different browsers. * - * Different browsers support different nocache headers, so several headers must - * be sent so that all of them get the point that no caching should occur. + * Different browsers support different nocache headers, so several + * headers must be sent so that all of them get the point that no + * caching should occur. * * @since 2.0.0 + * * @see wp_get_nocache_headers() */ function nocache_headers() { @@ -1027,6 +1076,7 @@ function nocache_headers() { */ function cache_javascript_headers() { $expiresOffset = 10 * DAY_IN_SECONDS; + header( "Content-Type: text/javascript; charset=" . get_bloginfo( 'charset' ) ); header( "Vary: Accept-Encoding" ); // Handle proxies header( "Expires: " . gmdate( "D, d M Y H:i:s", time() + $expiresOffset ) . " GMT" ); @@ -1037,7 +1087,9 @@ function cache_javascript_headers() { * * @since 2.0.0 * - * @return int Number of database queries + * @global wpdb $wpdb WordPress database abstraction object. + * + * @return int Number of database queries. */ function get_num_queries() { global $wpdb; @@ -1045,19 +1097,21 @@ function get_num_queries() { } /** - * Whether input is yes or no. Must be 'y' to be true. + * Whether input is yes or no. + * + * Must be 'y' to be true. * * @since 1.0.0 * - * @param string $yn Character string containing either 'y' or 'n' - * @return bool True if yes, false on anything else + * @param string $yn Character string containing either 'y' (yes) or 'n' (no). + * @return bool True if yes, false on anything else. */ function bool_from_yn( $yn ) { return ( strtolower( $yn ) == 'y' ); } /** - * Loads the feed template from the use of an action hook. + * Load the feed template from the use of an action hook. * * If the feed action does not have a hook, then the function will die with a * message telling the visitor that the feed is not valid. @@ -1099,6 +1153,8 @@ function do_feed() { * Load the RDF RSS 0.91 Feed template. * * @since 2.1.0 + * + * @see load_template() */ function do_feed_rdf() { load_template( ABSPATH . WPINC . '/feed-rdf.php' ); @@ -1108,6 +1164,8 @@ function do_feed_rdf() { * Load the RSS 1.0 Feed Template. * * @since 2.1.0 + * + * @see load_template() */ function do_feed_rss() { load_template( ABSPATH . WPINC . '/feed-rss.php' ); @@ -1118,6 +1176,8 @@ function do_feed_rss() { * * @since 2.1.0 * + * @see load_template() + * * @param bool $for_comments True for the comment feed, false for normal feed. */ function do_feed_rss2( $for_comments ) { @@ -1132,6 +1192,8 @@ function do_feed_rss2( $for_comments ) { * * @since 2.1.0 * + * @see load_template() + * * @param bool $for_comments True for the comment feed, false for normal feed. */ function do_feed_atom( $for_comments ) { @@ -1167,7 +1229,6 @@ function do_robots() { $site_url = parse_url( site_url() ); $path = ( !empty( $site_url['path'] ) ) ? $site_url['path'] : ''; $output .= "Disallow: $path/wp-admin/\n"; - $output .= "Disallow: $path/wp-includes/\n"; } /** @@ -1184,21 +1245,25 @@ function do_robots() { /** * Test whether blog is already installed. * - * The cache will be checked first. If you have a cache plugin, which saves the - * cache values, then this will work. If you use the default WordPress cache, - * and the database goes away, then you might have problems. + * The cache will be checked first. If you have a cache plugin, which saves + * the cache values, then this will work. If you use the default WordPress + * cache, and the database goes away, then you might have problems. * - * Checks for the option siteurl for whether WordPress is installed. + * Checks for the 'siteurl' option for whether WordPress is installed. * * @since 2.1.0 - * @uses $wpdb * - * @return bool Whether blog is already installed. + * @global wpdb $wpdb WordPress database abstraction object. + * + * @return bool Whether the blog is already installed. */ function is_blog_installed() { global $wpdb; - // Check cache first. If options table goes away and we have true cached, oh well. + /* + * Check cache first. If options table goes away and we have true + * cached, oh well. + */ if ( wp_cache_get( 'is_blog_installed' ) ) return true; @@ -1225,9 +1290,11 @@ function is_blog_installed() { $suppress = $wpdb->suppress_errors(); - // Loop over the WP tables. If none exist, then scratch install is allowed. - // If one or more exist, suggest table repair since we got here because the options - // table could not be accessed. + /* + * Loop over the WP tables. If none exist, then scratch install is allowed. + * If one or more exist, suggest table repair since we got here because the + * options table could not be accessed. + */ $wp_tables = $wpdb->tables(); foreach ( $wp_tables as $table ) { // The existence of custom user tables shouldn't suggest an insane state or prevent a clean install. @@ -1260,9 +1327,9 @@ function is_blog_installed() { * * @since 2.0.4 * - * @param string $actionurl URL to add nonce action. - * @param string $action Optional. Nonce action name. - * @param string $name Optional. Nonce name. + * @param string $actionurl URL to add nonce action. + * @param int|string $action Optional. Nonce action name. Default -1. + * @param string $name Optional. Nonce name. Default '_wpnonce'. * @return string Escaped URL with nonce action added. */ function wp_nonce_url( $actionurl, $action = -1, $name = '_wpnonce' ) { @@ -1290,11 +1357,11 @@ function wp_nonce_url( $actionurl, $action = -1, $name = '_wpnonce' ) { * * @since 2.0.4 * - * @param string $action Optional. Action name. - * @param string $name Optional. Nonce name. - * @param bool $referer Optional, default true. Whether to set the referer field for validation. - * @param bool $echo Optional, default true. Whether to display or return hidden form field. - * @return string Nonce field. + * @param int|string $action Optional. Action name. Default -1. + * @param string $name Optional. Nonce name. Default '_wpnonce'. + * @param bool $referer Optional. Whether to set the referer field for validation. Default true. + * @param bool $echo Optional. Whether to display or return hidden form field. Default true. + * @return string Nonce field HTML markup. */ function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $echo = true ) { $name = esc_attr( $name ); @@ -1317,8 +1384,8 @@ function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $ec * * @since 2.0.4 * - * @param bool $echo Whether to echo or return the referer field. - * @return string Referer field. + * @param bool $echo Optional. Whether to echo or return the referer field. Default true. + * @return string Referer field HTML markup. */ function wp_referer_field( $echo = true ) { $referer_field = ''; @@ -1332,13 +1399,14 @@ function wp_referer_field( $echo = true ) { * Retrieve or display original referer hidden field for forms. * * The input name is '_wp_original_http_referer' and will be either the same - * value of {@link wp_referer_field()}, if that was posted already or it will - * be the current page, if it doesn't exist. + * value of wp_referer_field(), if that was posted already or it will be the + * current page, if it doesn't exist. * * @since 2.0.4 * - * @param bool $echo Whether to echo the original http referer - * @param string $jump_back_to Optional, default is 'current'. Can be 'previous' or page you want to jump back to. + * @param bool $echo Optional. Whether to echo the original http referer. Default true. + * @param string $jump_back_to Optional. Can be 'previous' or page you want to jump back to. + * Default 'current'. * @return string Original referer field. */ function wp_original_referer_field( $echo = true, $jump_back_to = 'current' ) { @@ -1352,12 +1420,13 @@ function wp_original_referer_field( $echo = true, $jump_back_to = 'current' ) { } /** - * Retrieve referer from '_wp_http_referer' or HTTP referer. If it's the same - * as the current request URL, will return false. + * Retrieve referer from '_wp_http_referer' or HTTP referer. + * + * If it's the same as the current request URL, will return false. * * @since 2.0.4 * - * @return string|bool False on failure. Referer URL on success. + * @return false|string False on failure. Referer URL on success. */ function wp_get_referer() { if ( ! function_exists( 'wp_validate_redirect' ) ) @@ -1378,7 +1447,7 @@ function wp_get_referer() { * * @since 2.0.4 * - * @return string|bool False if no original referer or original referer if set. + * @return string|false False if no original referer or original referer if set. */ function wp_get_original_referer() { if ( ! empty( $_REQUEST['_wp_original_http_referer'] ) && function_exists( 'wp_validate_redirect' ) ) @@ -1399,21 +1468,24 @@ function wp_get_original_referer() { function wp_mkdir_p( $target ) { $wrapper = null; - // strip the protocol + // Strip the protocol. if( wp_is_stream( $target ) ) { list( $wrapper, $target ) = explode( '://', $target, 2 ); } - // from php.net/mkdir user contributed notes + // From php.net/mkdir user contributed notes. $target = str_replace( '//', '/', $target ); - // put the wrapper back on the target + // Put the wrapper back on the target. if( $wrapper !== null ) { $target = $wrapper . '://' . $target; } - // safe mode fails with a trailing slash under certain PHP versions. - $target = rtrim($target, '/'); // Use rtrim() instead of untrailingslashit to avoid formatting.php dependency. + /* + * Safe mode fails with a trailing slash under certain PHP versions. + * Use rtrim() instead of untrailingslashit to avoid formatting.php dependency. + */ + $target = rtrim($target, '/'); if ( empty($target) ) $target = '/'; @@ -1427,7 +1499,6 @@ function wp_mkdir_p( $target ) { } // Get the permission bits. - $dir_perms = false; if ( $stat = @stat( $target_parent ) ) { $dir_perms = $stat['mode'] & 0007777; } else { @@ -1436,7 +1507,10 @@ function wp_mkdir_p( $target ) { if ( @mkdir( $target, $dir_perms, true ) ) { - // If a umask is set that modifies $dir_perms, we'll have to re-set the $dir_perms correctly with chmod() + /* + * If a umask is set that modifies $dir_perms, we'll have to re-set + * the $dir_perms correctly with chmod() + */ if ( $dir_perms != ( $dir_perms & ~umask() ) ) { $folder_parts = explode( '/', substr( $target, strlen( $target_parent ) + 1 ) ); for ( $i = 1; $i <= count( $folder_parts ); $i++ ) { @@ -1451,38 +1525,44 @@ function wp_mkdir_p( $target ) { } /** - * Test if a give filesystem path is absolute ('/foo/bar', 'c:\windows'). + * Test if a give filesystem path is absolute. + * + * For example, '/foo/bar', or 'c:\windows'. * * @since 2.5.0 * - * @param string $path File path + * @param string $path File path. * @return bool True if path is absolute, false is not absolute. */ function path_is_absolute( $path ) { - // this is definitive if true but fails if $path does not exist or contains a symbolic link + /* + * This is definitive if true but fails if $path does not exist or contains + * a symbolic link. + */ if ( realpath($path) == $path ) return true; if ( strlen($path) == 0 || $path[0] == '.' ) return false; - // windows allows absolute paths like this + // Windows allows absolute paths like this. if ( preg_match('#^[a-zA-Z]:\\\\#', $path) ) return true; - // a path starting with / or \ is absolute; anything else is relative + // A path starting with / or \ is absolute; anything else is relative. return ( $path[0] == '/' || $path[0] == '\\' ); } /** - * Join two filesystem paths together (e.g. 'give me $path relative to $base'). + * Join two filesystem paths together. * - * If the $path is absolute, then it the full path is returned. + * For example, 'give me $path relative to $base'. If the $path is absolute, + * then it the full path is returned. * * @since 2.5.0 * - * @param string $base - * @param string $path + * @param string $base Base path. + * @param string $path Path relative to $base. * @return string The path with the base or absolute path. */ function path_join( $base, $path ) { @@ -1495,8 +1575,8 @@ function path_join( $base, $path ) { /** * Normalize a filesystem path. * - * Replaces backslashes with forward slashes for Windows systems, - * and ensures no duplicate slashes exist. + * Replaces backslashes with forward slashes for Windows systems, and ensures + * no duplicate slashes exist. * * @since 3.9.0 * @@ -1510,18 +1590,18 @@ function wp_normalize_path( $path ) { } /** - * Determines a writable directory for temporary files. - * Function's preference is the return value of sys_get_temp_dir(), + * Determine a writable directory for temporary files. + * + * Function's preference is the return value of sys_get_temp_dir(), * followed by your PHP temporary upload directory, followed by WP_CONTENT_DIR, * before finally defaulting to /tmp/ * * In the event that this function does not find a writable location, - * It may be overridden by the WP_TEMP_DIR constant in - * your wp-config.php file. + * It may be overridden by the WP_TEMP_DIR constant in your wp-config.php file. * * @since 2.5.0 * - * @return string Writable temporary directory + * @return string Writable temporary directory. */ function get_temp_dir() { static $temp; @@ -1552,15 +1632,15 @@ function get_temp_dir() { /** * Determine if a directory is writable. * - * This function is used to work around certain ACL issues - * in PHP primarily affecting Windows Servers. - * - * @see win_is_writable() + * This function is used to work around certain ACL issues in PHP primarily + * affecting Windows Servers. * * @since 3.6.0 * - * @param string $path - * @return bool + * @see win_is_writable() + * + * @param string $path Path to check for write-ability. + * @return bool Whether the path is writable. */ function wp_is_writable( $path ) { if ( 'WIN' === strtoupper( substr( PHP_OS, 0, 3 ) ) ) @@ -1577,13 +1657,13 @@ function wp_is_writable( $path ) { * checking the ability to open files rather than relying * upon PHP to interprate the OS ACL. * - * @link http://bugs.php.net/bug.php?id=27609 - * @link http://bugs.php.net/bug.php?id=30931 - * * @since 2.8.0 * - * @param string $path - * @return bool + * @see http://bugs.php.net/bug.php?id=27609 + * @see http://bugs.php.net/bug.php?id=30931 + * + * @param string $path Windows path to check for write-ability. + * @return bool Whether the path is writable. */ function win_is_writable( $path ) { @@ -1632,7 +1712,7 @@ function win_is_writable( $path ) { * * @since 2.0.0 * - * @param string $time Optional. Time formatted in 'yyyy/mm'. + * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. * @return array See above for description. */ function wp_upload_dir( $time = null ) { @@ -1655,8 +1735,10 @@ function wp_upload_dir( $time = null ) { $url = trailingslashit( $siteurl ) . $upload_path; } - // Obey the value of UPLOADS. This happens as long as ms-files rewriting is disabled. - // We also sometimes obey UPLOADS when rewriting is enabled -- see the next block. + /* + * Honor the value of UPLOADS. This happens as long as ms-files rewriting is disabled. + * We also sometimes obey UPLOADS when rewriting is enabled -- see the next block. + */ if ( defined( 'UPLOADS' ) && ! ( is_multisite() && get_site_option( 'ms_files_rewriting' ) ) ) { $dir = ABSPATH . UPLOADS; $url = trailingslashit( $siteurl ) . UPLOADS; @@ -1666,11 +1748,14 @@ function wp_upload_dir( $time = null ) { if ( is_multisite() && ! ( is_main_network() && is_main_site() && defined( 'MULTISITE' ) ) ) { if ( ! get_site_option( 'ms_files_rewriting' ) ) { - // If ms-files rewriting is disabled (networks created post-3.5), it is fairly straightforward: - // Append sites/%d if we're not on the main site (for post-MU networks). (The extra directory - // prevents a four-digit ID from conflicting with a year-based directory for the main site. - // But if a MU-era network has disabled ms-files rewriting manually, they don't need the extra - // directory, as they never had wp-content/uploads for the main site.) + /* + * If ms-files rewriting is disabled (networks created post-3.5), it is fairly + * straightforward: Append sites/%d if we're not on the main site (for post-MU + * networks). (The extra directory prevents a four-digit ID from conflicting with + * a year-based directory for the main site. But if a MU-era network has disabled + * ms-files rewriting manually, they don't need the extra directory, as they never + * had wp-content/uploads for the main site.) + */ if ( defined( 'MULTISITE' ) ) $ms_dir = '/sites/' . get_current_blog_id(); @@ -1681,17 +1766,19 @@ function wp_upload_dir( $time = null ) { $url .= $ms_dir; } elseif ( defined( 'UPLOADS' ) && ! ms_is_switched() ) { - // Handle the old-form ms-files.php rewriting if the network still has that enabled. - // When ms-files rewriting is enabled, then we only listen to UPLOADS when: - // 1) we are not on the main site in a post-MU network, - // as wp-content/uploads is used there, and - // 2) we are not switched, as ms_upload_constants() hardcodes - // these constants to reflect the original blog ID. - // - // Rather than UPLOADS, we actually use BLOGUPLOADDIR if it is set, as it is absolute. - // (And it will be set, see ms_upload_constants().) Otherwise, UPLOADS can be used, as - // as it is relative to ABSPATH. For the final piece: when UPLOADS is used with ms-files - // rewriting in multisite, the resulting URL is /files. (#WP22702 for background.) + /* + * Handle the old-form ms-files.php rewriting if the network still has that enabled. + * When ms-files rewriting is enabled, then we only listen to UPLOADS when: + * 1) We are not on the main site in a post-MU network, as wp-content/uploads is used + * there, and + * 2) We are not switched, as ms_upload_constants() hardcodes these constants to reflect + * the original blog ID. + * + * Rather than UPLOADS, we actually use BLOGUPLOADDIR if it is set, as it is absolute. + * (And it will be set, see ms_upload_constants().) Otherwise, UPLOADS can be used, as + * as it is relative to ABSPATH. For the final piece: when UPLOADS is used with ms-files + * rewriting in multisite, the resulting URL is /files. (#WP22702 for background.) + */ if ( defined( 'BLOGUPLOADDIR' ) ) $dir = untrailingslashit( BLOGUPLOADDIR ); @@ -1735,7 +1822,7 @@ function wp_upload_dir( $time = null ) { 'error' => false, ) ); - // Make sure we have an uploads dir + // Make sure we have an uploads directory. if ( ! wp_mkdir_p( $uploads['path'] ) ) { if ( 0 === strpos( $uploads['basedir'], ABSPATH ) ) $error_path = str_replace( ABSPATH, '', $uploads['basedir'] ) . $uploads['subdir']; @@ -1761,36 +1848,39 @@ function wp_upload_dir( $time = null ) { * * @since 2.5.0 * - * @param string $dir - * @param string $filename - * @param mixed $unique_filename_callback Callback. + * @param string $dir Directory. + * @param string $filename File name. + * @param callback $unique_filename_callback Callback. Default null. * @return string New filename, if given wasn't unique. */ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) { - // sanitize the file name before we begin processing + // Sanitize the file name before we begin processing. $filename = sanitize_file_name($filename); - // separate the filename into a name and extension + // Separate the filename into a name and extension. $info = pathinfo($filename); $ext = !empty($info['extension']) ? '.' . $info['extension'] : ''; $name = basename($filename, $ext); - // edge case: if file is named '.ext', treat as an empty name + // Edge case: if file is named '.ext', treat as an empty name. if ( $name === $ext ) $name = ''; - // Increment the file number until we have a unique file to save in $dir. Use callback if supplied. + /* + * Increment the file number until we have a unique file to save in $dir. + * Use callback if supplied. + */ if ( $unique_filename_callback && is_callable( $unique_filename_callback ) ) { $filename = call_user_func( $unique_filename_callback, $dir, $name, $ext ); } else { $number = ''; - // change '.ext' to lower case + // Change '.ext' to lower case. if ( $ext && strtolower($ext) != $ext ) { $ext2 = strtolower($ext); $filename2 = preg_replace( '|' . preg_quote($ext) . '$|', $ext2, $filename ); - // check for both lower and upper case extension or image sub-sizes may be overwritten + // Check for both lower and upper case extension or image sub-sizes may be overwritten. while ( file_exists($dir . "/$filename") || file_exists($dir . "/$filename2") ) { $new_number = $number + 1; $filename = str_replace( "$number$ext", "$new_number$ext", $filename ); @@ -1828,10 +1918,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) * * @since 2.0.0 * - * @param string $name - * @param null $deprecated Never used. Set to null. - * @param mixed $bits File content - * @param string $time Optional. Time formatted in 'yyyy/mm'. + * @param string $name Filename. + * @param null|string $deprecated Never used. Set to null. + * @param mixed $bits File content + * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. * @return array */ function wp_upload_bits( $name, $deprecated, $bits, $time = null ) { @@ -1925,8 +2015,8 @@ function wp_ext2type( $ext ) { $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' ), - 'video' => array( 'asf', 'avi', 'divx', 'dv', 'flv', 'm4v', 'mkv', 'mov', 'mp4', 'mpeg', 'mpg', 'mpv', 'ogm', 'ogv', 'qt', 'rm', 'vob', 'wmv' ), - 'document' => array( 'doc', 'docx', 'docm', 'dotm', 'odt', 'pages', 'pdf', 'rtf', 'wp', 'wpd' ), + 'video' => array( '3g2', '3gp', '3gpp', 'asf', 'avi', 'divx', 'dv', 'flv', 'm4v', 'mkv', 'mov', 'mp4', 'mpeg', 'mpg', 'mpv', 'ogm', 'ogv', 'qt', 'rm', 'vob', 'wmv' ), + 'document' => array( 'doc', 'docx', 'docm', 'dotm', 'odt', 'pages', 'pdf', 'xps', 'oxps', 'rtf', 'wp', 'wpd', 'psd' ), 'spreadsheet' => array( 'numbers', 'ods', 'xls', 'xlsx', 'xlsm', 'xlsb' ), 'interactive' => array( 'swf', 'key', 'ppt', 'pptx', 'pptm', 'pps', 'ppsx', 'ppsm', 'sldx', 'sldm', 'odp' ), 'text' => array( 'asc', 'csv', 'tsv', 'txt' ), @@ -1949,7 +2039,7 @@ function wp_ext2type( $ext ) { * @since 2.0.4 * * @param string $filename File name or path. - * @param array $mimes Optional. Key is the file extension with value as the mime type. + * @param array $mimes Optional. Key is the file extension with value as the mime type. * @return array Values with extension first and mime type. */ function wp_check_filetype( $filename, $mimes = null ) { @@ -1972,6 +2062,7 @@ function wp_check_filetype( $filename, $mimes = null ) { /** * Attempt to determine the real file type of a file. + * * If unable to, the file name extension will be used to determine type. * * If it's determined that the extension does not match the file's real type, @@ -1981,10 +2072,12 @@ function wp_check_filetype( $filename, $mimes = null ) { * * @since 3.0.0 * - * @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 Optional. Key is the file extension with value as the mime type. - * @return array Values for the extension, MIME, and either a corrected filename or false if original $filename is valid + * @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 Optional. Key is the file extension with value as the mime type. + * @return array Values for the extension, MIME, and either a corrected filename or false + * if original $filename is valid. */ function wp_check_filetype_and_ext( $file, $filename, $mimes = null ) { @@ -1992,11 +2085,13 @@ function wp_check_filetype_and_ext( $file, $filename, $mimes = null ) { // Do basic extension validation and MIME mapping $wp_filetype = wp_check_filetype( $filename, $mimes ); - extract( $wp_filetype ); + $ext = $wp_filetype['ext']; + $type = $wp_filetype['type']; // We can't do any further validation without a file to work with - if ( ! file_exists( $file ) ) + if ( ! file_exists( $file ) ) { return compact( 'ext', 'type', 'proper_filename' ); + } // We're able to validate images using GD if ( $type && 0 === strpos( $type, 'image/' ) && function_exists('getimagesize') ) { @@ -2028,12 +2123,13 @@ function wp_check_filetype_and_ext( $file, $filename, $mimes = null ) { $filename_parts[] = $mime_to_ext[ $imgstats['mime'] ]; $new_filename = implode( '.', $filename_parts ); - if ( $new_filename != $filename ) + if ( $new_filename != $filename ) { $proper_filename = $new_filename; // Mark that it changed - + } // Redefine the extension / MIME $wp_filetype = wp_check_filetype( $new_filename, $mimes ); - extract( $wp_filetype ); + $ext = $wp_filetype['ext']; + $type = $wp_filetype['type']; } } } @@ -2073,14 +2169,14 @@ function wp_get_mime_types() { * corresponding to those types. */ return apply_filters( 'mime_types', array( - // Image formats + // Image formats. 'jpg|jpeg|jpe' => 'image/jpeg', 'gif' => 'image/gif', 'png' => 'image/png', 'bmp' => 'image/bmp', 'tif|tiff' => 'image/tiff', 'ico' => 'image/x-icon', - // Video formats + // Video formats. 'asf|asx' => 'video/x-ms-asf', 'wmv' => 'video/x-ms-wmv', 'wmx' => 'video/x-ms-wmx', @@ -2094,8 +2190,10 @@ function wp_get_mime_types() { 'ogv' => 'video/ogg', 'webm' => 'video/webm', 'mkv' => 'video/x-matroska', - // Text formats - 'txt|asc|c|cc|h' => 'text/plain', + '3gp|3gpp' => 'video/3gpp', // Can also be audio + '3g2|3gp2' => 'video/3gpp2', // Can also be audio + // Text formats. + 'txt|asc|c|cc|h|srt' => 'text/plain', 'csv' => 'text/csv', 'tsv' => 'text/tab-separated-values', 'ics' => 'text/calendar', @@ -2103,7 +2201,8 @@ function wp_get_mime_types() { 'css' => 'text/css', 'htm|html' => 'text/html', 'vtt' => 'text/vtt', - // Audio formats + 'dfxp' => 'application/ttaf+xml', + // Audio formats. 'mp3|m4a|m4b' => 'audio/mpeg', 'ra|ram' => 'audio/x-realaudio', 'wav' => 'audio/wav', @@ -2112,7 +2211,7 @@ function wp_get_mime_types() { 'wma' => 'audio/x-ms-wma', 'wax' => 'audio/x-ms-wax', 'mka' => 'audio/x-matroska', - // Misc application formats + // Misc application formats. 'rtf' => 'application/rtf', 'js' => 'application/javascript', 'pdf' => 'application/pdf', @@ -2124,7 +2223,8 @@ function wp_get_mime_types() { 'rar' => 'application/rar', '7z' => 'application/x-7z-compressed', 'exe' => 'application/x-msdownload', - // MS Office formats + 'psd' => 'application/octet-stream', + // MS Office formats. 'doc' => 'application/msword', 'pot|pps|ppt' => 'application/vnd.ms-powerpoint', 'wri' => 'application/vnd.ms-write', @@ -2151,7 +2251,9 @@ function wp_get_mime_types() { 'sldx' => 'application/vnd.openxmlformats-officedocument.presentationml.slide', 'sldm' => 'application/vnd.ms-powerpoint.slide.macroEnabled.12', 'onetoc|onetoc2|onetmp|onepkg' => 'application/onenote', - // OpenOffice formats + 'oxps' => 'application/oxps', + 'xps' => 'application/vnd.ms-xpsdocument', + // OpenOffice formats. 'odt' => 'application/vnd.oasis.opendocument.text', 'odp' => 'application/vnd.oasis.opendocument.presentation', 'ods' => 'application/vnd.oasis.opendocument.spreadsheet', @@ -2159,9 +2261,9 @@ function wp_get_mime_types() { 'odc' => 'application/vnd.oasis.opendocument.chart', 'odb' => 'application/vnd.oasis.opendocument.database', 'odf' => 'application/vnd.oasis.opendocument.formula', - // WordPerfect formats + // WordPerfect formats. 'wp|wpd' => 'application/wordperfect', - // iWork formats + // iWork formats. 'key' => 'application/vnd.apple.keynote', 'numbers' => 'application/vnd.apple.numbers', 'pages' => 'application/vnd.apple.pages', @@ -2172,10 +2274,9 @@ function wp_get_mime_types() { * * @since 2.8.6 * - * @uses wp_get_upload_mime_types() to fetch the list of mime types - * * @param int|WP_User $user Optional. User to check. Defaults to current user. - * @return array Array of mime types keyed by the file extension regex corresponding to those types. + * @return array Array of mime types keyed by the file extension regex corresponding + * to those types. */ function get_allowed_mime_types( $user = null ) { $t = wp_get_mime_types(); @@ -2203,15 +2304,14 @@ function get_allowed_mime_types( $user = null ) { /** * Display "Are You Sure" message to confirm the action being taken. * - * If the action has the nonce explain message, then it will be displayed along - * with the "Are you sure?" message. + * If the action has the nonce explain message, then it will be displayed + * along with the "Are you sure?" message. * * @since 2.0.4 * * @param string $action The nonce action. */ function wp_nonce_ays( $action ) { - $title = __( 'WordPress Failure Notice' ); if ( 'log-out' == $action ) { $html = sprintf( __( 'You are attempting to log out of %s' ), get_bloginfo( 'name' ) ) . '

'; $redirect_to = isset( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : ''; @@ -2222,25 +2322,51 @@ function wp_nonce_ays( $action ) { $html .= "

" . __( 'Please try again.' ) . ""; } - wp_die( $html, $title, array('response' => 403) ); + wp_die( $html, __( 'WordPress Failure Notice' ), 403 ); } /** * Kill WordPress execution and display HTML message with error message. * - * This function complements the die() PHP function. The difference is that + * This function complements the `die()` PHP function. The difference is that * HTML will be displayed to the user. It is recommended to use this function - * only, when the execution should not continue any further. It is not - * recommended to call this function very often and try to handle as many errors - * as possible silently. + * only when the execution should not continue any further. It is not recommended + * to call this function very often, and try to handle as many errors as possible + * silently or more gracefully. * - * @since 2.0.4 + * As a shorthand, the desired HTTP response code may be passed as an integer to + * the `$title` parameter (the default title would apply) or the `$args` parameter. * - * @param string $message Error message. - * @param string $title Error title. - * @param string|array $args Optional arguments to control behavior. + * @since 2.0.4 + * @since 4.1.0 The `$title` and `$args` parameters were changed to optionally accept + * an integer to be used as the response code. + * + * @param string|WP_Error $message Optional. Error message. If this is a {@see WP_Error} object, + * the error's messages are used. Default empty. + * @param string|int $title Optional. Error title. If `$message` is a `WP_Error` object, + * error data with the key 'title' may be used to specify the title. + * If `$title` is an integer, then it is treated as the response + * code. Default empty. + * @param string|array|int $args { + * Optional. Arguments to control behavior. If `$args` is an integer, then it is treated + * as the response code. Default empty array. + * + * @type int $response The HTTP response code. Default 500. + * @type bool $back_link Whether to include a link to go back. Default false. + * @type string $text_direction The text direction. This is only useful internally, when WordPress + * is still loading and the site's locale is not set up yet. Accepts 'rtl'. + * Default is the value of {@see is_rtl()}. + * } */ function wp_die( $message = '', $title = '', $args = array() ) { + + if ( is_int( $args ) ) { + $args = array( 'response' => $args ); + } elseif ( is_int( $title ) ) { + $args = array( 'response' => $title ); + $title = ''; + } + if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) { /** * Filter callback for killing WordPress execution for AJAX requests. @@ -2282,9 +2408,9 @@ function wp_die( $message = '', $title = '', $args = array() ) { * @since 3.0.0 * @access private * - * @param string $message Error message. - * @param string $title Error title. - * @param string|array $args Optional arguments to control behavior. + * @param string $message Error message. + * @param string $title Optional. Error title. Default empty. + * @param string|array $args Optional. Arguments to control behavior. Default empty array. */ function _default_wp_die_handler( $message, $title = '', $args = array() ) { $defaults = array( 'response' => 500 ); @@ -2299,7 +2425,7 @@ function _default_wp_die_handler( $message, $title = '', $args = array() ) { $title = $error_data['title']; } $errors = $message->get_error_messages(); - switch ( count( $errors ) ) : + switch ( count( $errors ) ) { case 0 : $message = ''; break; @@ -2309,7 +2435,7 @@ function _default_wp_die_handler( $message, $title = '', $args = array() ) { default : $message = "

"; break; - endswitch; + } } elseif ( is_string( $message ) ) { $message = "

$message

"; } @@ -2460,9 +2586,9 @@ function _default_wp_die_handler( $message, $title = '', $args = array() ) { * @since 3.2.0 * @access private * - * @param string $message Error message. - * @param string $title Error title. - * @param string|array $args Optional arguments to control behavior. + * @param string $message Error message. + * @param string $title Optional. Error title. Default empty. + * @param string|array $args Optional. Arguments to control behavior. Default empty array. */ function _xmlrpc_wp_die_handler( $message, $title = '', $args = array() ) { global $wp_xmlrpc_server; @@ -2485,7 +2611,7 @@ function _xmlrpc_wp_die_handler( $message, $title = '', $args = array() ) { * @since 3.4.0 * @access private * - * @param string $message Optional. Response to print. + * @param string $message Optional. Response to print. Default empty. */ function _ajax_wp_die_handler( $message = '' ) { if ( is_scalar( $message ) ) @@ -2501,7 +2627,7 @@ function _ajax_wp_die_handler( $message = '' ) { * @since 3.4.0 * @access private * - * @param string $message Optional. Response to print. + * @param string $message Optional. Response to print. Default empty. */ function _scalar_wp_die_handler( $message = '' ) { if ( is_scalar( $message ) ) @@ -2509,16 +2635,153 @@ function _scalar_wp_die_handler( $message = '' ) { die(); } +/** + * Encode a variable into JSON, with some sanity checks. + * + * @since 4.1.0 + * + * @param mixed $data Variable (usually an array or object) to encode as JSON. + * @param int $options Optional. Options to be passed to json_encode(). Default 0. + * @param int $depth Optional. Maximum depth to walk through $data. Must be + * greater than 0. Default 512. + * @return bool|string The JSON encoded string, or false if it cannot be encoded. + */ +function wp_json_encode( $data, $options = 0, $depth = 512 ) { + /* + * json_encode() has had extra params added over the years. + * $options was added in 5.3, and $depth in 5.5. + * We need to make sure we call it with the correct arguments. + */ + if ( version_compare( PHP_VERSION, '5.5', '>=' ) ) { + $args = array( $data, $options, $depth ); + } elseif ( version_compare( PHP_VERSION, '5.3', '>=' ) ) { + $args = array( $data, $options ); + } else { + $args = array( $data ); + } + + $json = call_user_func_array( 'json_encode', $args ); + + // If json_encode() was successful, no need to do more sanity checking. + // ... unless we're in an old version of PHP, and json_encode() returned + // a string containing 'null'. Then we need to do more sanity checking. + if ( false !== $json && ( version_compare( PHP_VERSION, '5.5', '>=' ) || false === strpos( $json, 'null' ) ) ) { + return $json; + } + + try { + $args[0] = _wp_json_sanity_check( $data, $depth ); + } catch ( Exception $e ) { + return false; + } + + return call_user_func_array( 'json_encode', $args ); +} + +/** + * Perform sanity checks on data that shall be encoded to JSON. + * + * @see wp_json_encode() + * + * @since 4.1.0 + * @access private + * @internal + * + * @param mixed $data Variable (usually an array or object) to encode as JSON. + * @param int $depth Maximum depth to walk through $data. Must be greater than 0. + * @return mixed The sanitized data that shall be encoded to JSON. + */ +function _wp_json_sanity_check( $data, $depth ) { + if ( $depth < 0 ) { + throw new Exception( 'Reached depth limit' ); + } + + if ( is_array( $data ) ) { + $output = array(); + foreach ( $data as $id => $el ) { + // Don't forget to sanitize the ID! + if ( is_string( $id ) ) { + $clean_id = _wp_json_convert_string( $id ); + } else { + $clean_id = $id; + } + + // Check the element type, so that we're only recursing if we really have to. + if ( is_array( $el ) || is_object( $el ) ) { + $output[ $clean_id ] = _wp_json_sanity_check( $el, $depth - 1 ); + } elseif ( is_string( $el ) ) { + $output[ $clean_id ] = _wp_json_convert_string( $el ); + } else { + $output[ $clean_id ] = $el; + } + } + } elseif ( is_object( $data ) ) { + $output = new stdClass; + foreach ( $data as $id => $el ) { + if ( is_string( $id ) ) { + $clean_id = _wp_json_convert_string( $id ); + } else { + $clean_id = $id; + } + + if ( is_array( $el ) || is_object( $el ) ) { + $output->$clean_id = _wp_json_sanity_check( $el, $depth - 1 ); + } elseif ( is_string( $el ) ) { + $output->$clean_id = _wp_json_convert_string( $el ); + } else { + $output->$clean_id = $el; + } + } + } elseif ( is_string( $data ) ) { + return _wp_json_convert_string( $data ); + } else { + return $data; + } + + return $output; +} + +/** + * Convert a string to UTF-8, so that it can be safely encoded to JSON. + * + * @see _wp_json_sanity_check() + * + * @since 4.1.0 + * @access private + * @internal + * + * @param string $string The string which is to be converted. + * @return string The checked string. + */ +function _wp_json_convert_string( $string ) { + static $use_mb = null; + if ( is_null( $use_mb ) ) { + $use_mb = function_exists( 'mb_convert_encoding' ); + } + + if ( $use_mb ) { + $encoding = mb_detect_encoding( $string, mb_detect_order(), true ); + if ( $encoding ) { + return mb_convert_encoding( $string, 'UTF-8', $encoding ); + } else { + return mb_convert_encoding( $string, 'UTF-8', 'UTF-8' ); + } + } else { + return wp_check_invalid_utf8( $string, true ); + } +} + /** * Send a JSON response back to an Ajax request. * * @since 3.5.0 * - * @param mixed $response Variable (usually an array or object) to encode as JSON, then print and die. + * @param mixed $response Variable (usually an array or object) to encode as JSON, + * then print and die. */ function wp_send_json( $response ) { @header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) ); - echo json_encode( $response ); + echo wp_json_encode( $response ); if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) wp_die(); else @@ -2544,15 +2807,34 @@ function wp_send_json_success( $data = null ) { /** * Send a JSON response back to an Ajax request, indicating failure. * + * If the `$data` parameter is a {@see WP_Error} object, the errors + * within the object are processed and output as an array of error + * codes and corresponding messages. All other types are output + * without further processing. + * * @since 3.5.0 + * @since 4.1.0 The `$data` parameter is now processed if a {@see WP_Error} + * object is passed in. * * @param mixed $data Data to encode as JSON, then print and die. */ function wp_send_json_error( $data = null ) { $response = array( 'success' => false ); - if ( isset( $data ) ) - $response['data'] = $data; + if ( isset( $data ) ) { + if ( is_wp_error( $data ) ) { + $result = array(); + foreach ( $data->errors as $code => $messages ) { + foreach ( $messages as $message ) { + $result[] = array( 'code' => $code, 'message' => $message ); + } + } + + $response['data'] = $result; + } else { + $response['data'] = $data; + } + } wp_send_json( $response ); } @@ -2560,14 +2842,16 @@ function wp_send_json_error( $data = null ) { /** * Retrieve the WordPress home page URL. * - * If the constant named 'WP_HOME' exists, then it will be used and returned by - * the function. This can be used to counter the redirection on your local + * If the constant named 'WP_HOME' exists, then it will be used and returned + * by the function. This can be used to counter the redirection on your local * development environment. * - * @access private * @since 2.2.0 + * @access private + * + * @see WP_HOME * - * @param string $url URL for the home location + * @param string $url URL for the home location. * @return string Homepage location. */ function _config_wp_home( $url = '' ) { @@ -2580,14 +2864,16 @@ function _config_wp_home( $url = '' ) { * Retrieve the WordPress site URL. * * If the constant named 'WP_SITEURL' is defined, then the value in that - * constant will always be returned. This can be used for debugging a site on - * your localhost while not having to change the database to your URL. + * constant will always be returned. This can be used for debugging a site + * on your localhost while not having to change the database to your URL. * - * @access private * @since 2.2.0 + * @access private + * + * @see WP_SITEURL * * @param string $url URL to set the WordPress site location. - * @return string The WordPress Site URL + * @return string The WordPress Site URL. */ function _config_wp_siteurl( $url = '' ) { if ( defined( 'WP_SITEURL' ) ) @@ -2598,15 +2884,16 @@ function _config_wp_siteurl( $url = '' ) { /** * Set the localized direction for MCE plugin. * - * Will only set the direction to 'rtl', if the WordPress locale has the text - * direction set to 'rtl'. + * Will only set the direction to 'rtl', if the WordPress locale has + * the text direction set to 'rtl'. * - * Fills in the 'directionality' setting, enables the 'directionality' plugin, - * and adds the 'ltr' button to 'toolbar1', formerly 'theme_advanced_buttons1' array - * keys. These keys are then returned in the $input (TinyMCE settings) array. + * Fills in the 'directionality' setting, enables the 'directionality' + * plugin, and adds the 'ltr' button to 'toolbar1', formerly + * 'theme_advanced_buttons1' array keys. These keys are then returned + * in the $input (TinyMCE settings) array. * - * @access private * @since 2.1.0 + * @access private * * @param array $input MCE settings array. * @return array Direction set for 'rtl', if needed by locale. @@ -2641,6 +2928,7 @@ function _mce_set_direction( $input ) { * * @global array $wpsmiliestrans * @global array $wp_smiliessearch + * * @since 2.2.0 */ function smilies_init() { @@ -2711,7 +2999,10 @@ function smilies_init() { */ krsort($wpsmiliestrans); - $wp_smiliessearch = '/((?:\s|^)'; + $spaces = wp_spaces_regexp(); + + // Begin first "subpattern" + $wp_smiliessearch = '/(?<=' . $spaces . '|^)'; $subchar = ''; foreach ( (array) $wpsmiliestrans as $smiley => $img ) { @@ -2721,7 +3012,8 @@ function smilies_init() { // new subpattern? if ($firstchar != $subchar) { if ($subchar != '') { - $wp_smiliessearch .= ')(?=\s|$))|((?:\s|^)'; ; + $wp_smiliessearch .= ')(?=' . $spaces . '|$)'; // End previous "subpattern" + $wp_smiliessearch .= '|(?<=' . $spaces . '|^)'; // Begin another "subpattern" } $subchar = $firstchar; $wp_smiliessearch .= preg_quote($firstchar, '/') . '(?:'; @@ -2731,7 +3023,7 @@ function smilies_init() { $wp_smiliessearch .= preg_quote($rest, '/'); } - $wp_smiliessearch .= ')(?=\s|$))/m'; + $wp_smiliessearch .= ')(?=' . $spaces . '|$)/m'; } @@ -2743,8 +3035,8 @@ function smilies_init() { * * @since 2.2.0 * - * @param string|array $args Value to merge with $defaults - * @param array $defaults Array that serves as the defaults. + * @param string|array $args Value to merge with $defaults + * @param array $defaults Optional. Array that serves as the defaults. Default empty. * @return array Merged user defined values with defaults. */ function wp_parse_args( $args, $defaults = '' ) { @@ -2765,8 +3057,8 @@ function wp_parse_args( $args, $defaults = '' ) { * * @since 3.0.0 * - * @param array|string $list - * @return array Sanitized array of IDs + * @param array|string $list List of ids. + * @return array Sanitized array of IDs. */ function wp_parse_id_list( $list ) { if ( !is_array($list) ) @@ -2780,9 +3072,9 @@ function wp_parse_id_list( $list ) { * * @since 3.1.0 * - * @param array $array The original array - * @param array $keys The list of keys - * @return array The array slice + * @param array $array The original array. + * @param array $keys The list of keys. + * @return array The array slice. */ function wp_array_slice_assoc( $array, $keys ) { $slice = array(); @@ -2798,12 +3090,15 @@ function wp_array_slice_assoc( $array, $keys ) { * * @since 3.0.0 * - * @param array $list An array of objects to filter - * @param array $args An array of key => value arguments to match against each object - * @param string $operator The logical operation to perform. 'or' means only one element - * from the array needs to match; 'and' means all elements must match. The default is 'and'. - * @param bool|string $field A field from the object to place instead of the entire object - * @return array A list of objects or object fields + * @param array $list An array of objects to filter + * @param array $args Optional. An array of key => value arguments to match + * against each object. Default empty array. + * @param string $operator Optional. The logical operation to perform. 'or' means + * only one element from the array needs to match; 'and' + * means all elements must match. Default 'and'. + * @param bool|string $field A field from the object to place instead of the entire object. + * Default false. + * @return array A list of objects or object fields. */ function wp_filter_object_list( $list, $args = array(), $operator = 'and', $field = false ) { if ( ! is_array( $list ) ) @@ -2822,14 +3117,14 @@ function wp_filter_object_list( $list, $args = array(), $operator = 'and', $fiel * * @since 3.1.0 * - * @param array $list An array of objects to filter - * @param array $args An array of key => value arguments to match against each object - * @param string $operator The logical operation to perform: - * 'AND' means all elements from the array must match; - * 'OR' means only one element needs to match; - * 'NOT' means no elements may match. - * The default is 'AND'. - * @return array + * @param array $list An array of objects to filter. + * @param array $args Optional. An array of key => value arguments to match + * against each object. Default empty array. + * @param string $operator Optional. The logical operation to perform. 'AND' means + * all elements from the array must match. 'OR' means only + * one element needs to match. 'NOT' means no elements may + * match. Default 'AND'. + * @return array Array of found values. */ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) { if ( ! is_array( $list ) ) @@ -2864,36 +3159,74 @@ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) { /** * Pluck a certain field out of each object in a list. * - * @since 3.1.0 + * This has the same functionality and prototype of + * array_column() (PHP 5.5) but also supports objects. * - * @param array $list A list of objects or arrays - * @param int|string $field A field from the object to place instead of the entire object - * @return array - */ -function wp_list_pluck( $list, $field ) { - foreach ( $list as $key => $value ) { - if ( is_object( $value ) ) - $list[ $key ] = $value->$field; - else - $list[ $key ] = $value[ $field ]; + * @since 3.1.0 + * @since 4.0.0 $index_key parameter added. + * + * @param array $list List of objects or arrays + * @param int|string $field Field from the object to place instead of the entire object + * @param int|string $index_key Optional. Field from the object to use as keys for the new array. + * Default null. + * @return array Array of found values. If $index_key is set, an array of found values with keys + * corresponding to $index_key. + */ +function wp_list_pluck( $list, $field, $index_key = null ) { + if ( ! $index_key ) { + /* + * This is simple. Could at some point wrap array_column() + * if we knew we had an array of arrays. + */ + foreach ( $list as $key => $value ) { + if ( is_object( $value ) ) { + $list[ $key ] = $value->$field; + } else { + $list[ $key ] = $value[ $field ]; + } + } + return $list; } - return $list; + /* + * When index_key is not set for a particular item, push the value + * to the end of the stack. This is how array_column() behaves. + */ + $newlist = array(); + foreach ( $list as $value ) { + if ( is_object( $value ) ) { + if ( isset( $value->$index_key ) ) { + $newlist[ $value->$index_key ] = $value->$field; + } else { + $newlist[] = $value->$field; + } + } else { + if ( isset( $value[ $index_key ] ) ) { + $newlist[ $value[ $index_key ] ] = $value[ $field ]; + } else { + $newlist[] = $value[ $field ]; + } + } + } + + return $newlist; } /** * Determines if Widgets library should be loaded. * - * Checks to make sure that the widgets library hasn't already been loaded. If - * it hasn't, then it will load the widgets library and run an action hook. + * Checks to make sure that the widgets library hasn't already been loaded. + * If it hasn't, then it will load the widgets library and run an action hook. * * @since 2.2.0 - * @uses add_action() Calls '_admin_menu' hook with 'wp_widgets_add_menu' value. */ function wp_maybe_load_widgets() { /** * Filter whether to load the Widgets library. * + * Passing a falsey value to the filter will effectively short-circuit + * the Widgets library from loading. + * * @since 2.8.0 * * @param bool $wp_maybe_load_widgets Whether to load the Widgets library. @@ -2902,7 +3235,9 @@ function wp_maybe_load_widgets() { if ( ! apply_filters( 'load_default_widgets', true ) ) { return; } + require_once( ABSPATH . WPINC . '/default-widgets.php' ); + add_action( '_admin_menu', 'wp_widgets_add_menu' ); } @@ -2910,7 +3245,6 @@ function wp_maybe_load_widgets() { * Append the Widgets menu to the themes main menu. * * @since 2.2.0 - * @uses $submenu The administration submenu list. */ function wp_widgets_add_menu() { global $submenu; @@ -2925,7 +3259,7 @@ function wp_widgets_add_menu() { /** * Flush all output buffers for PHP 5.2. * - * Make sure all output buffers are flushed before our singletons our destroyed. + * Make sure all output buffers are flushed before our singletons are destroyed. * * @since 2.2.0 */ @@ -2950,7 +3284,8 @@ function wp_ob_end_flush_all() { * in WordPress 2.5.0. * * @since 2.3.2 - * @uses $wpdb + * + * @global wpdb $wpdb WordPress database abstraction object. */ function dead_db() { global $wpdb; @@ -2988,54 +3323,19 @@ function dead_db() { } /** - * Converts value to nonnegative integer. + * Convert a value to non-negative integer. * * @since 2.5.0 * - * @param mixed $maybeint Data you wish to have converted to a nonnegative integer - * @return int An nonnegative integer + * @param mixed $maybeint Data you wish to have converted to a non-negative integer. + * @return int A non-negative integer. */ function absint( $maybeint ) { return abs( intval( $maybeint ) ); } /** - * Determines if the blog can be accessed over SSL. - * - * Determines if blog can be accessed over SSL by using cURL to access the site - * using the https in the siteurl. Requires cURL extension to work correctly. - * - * @since 2.5.0 - * - * @param string $url - * @return bool Whether SSL access is available - */ -function url_is_accessable_via_ssl($url) -{ - if ( in_array( 'curl', get_loaded_extensions() ) ) { - $ssl = set_url_scheme( $url, 'https' ); - - $ch = curl_init(); - curl_setopt($ch, CURLOPT_URL, $ssl); - curl_setopt($ch, CURLOPT_FAILONERROR, true); - curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); - curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); - curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5); - - curl_exec($ch); - - $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); - curl_close ($ch); - - if ($status == 200 || $status == 401) { - return true; - } - } - return false; -} - -/** - * Marks a function as deprecated and informs when it has been used. + * Mark a function as deprecated and inform when it has been used. * * There is a hook deprecated_function_run that will be called that can be used * to get the backtrace up to what file and function called the deprecated @@ -3048,9 +3348,9 @@ function url_is_accessable_via_ssl($url) * @since 2.5.0 * @access private * - * @param string $function The function that was called - * @param string $version The version of WordPress that deprecated the function - * @param string $replacement Optional. The function that should have been called + * @param string $function The function that was called. + * @param string $version The version of WordPress that deprecated the function. + * @param string $replacement Optional. The function that should have been called. Default null. */ function _deprecated_function( $function, $version, $replacement = null ) { @@ -3088,7 +3388,7 @@ function _deprecated_function( $function, $version, $replacement = null ) { } /** - * Marks a file as deprecated and informs when it has been used. + * Mark a file as deprecated and inform when it has been used. * * There is a hook deprecated_file_included that will be called that can be used * to get the backtrace up to what file and function included the deprecated @@ -3101,10 +3401,11 @@ function _deprecated_function( $function, $version, $replacement = null ) { * @since 2.5.0 * @access private * - * @param string $file The file that was included - * @param string $version The version of WordPress that deprecated the file - * @param string $replacement Optional. The file that should have been included based on ABSPATH - * @param string $message Optional. A message regarding the change + * @param string $file The file that was included. + * @param string $version The version of WordPress that deprecated the file. + * @param string $replacement Optional. The file that should have been included based on ABSPATH. + * Default null. + * @param string $message Optional. A message regarding the change. Default empty. */ function _deprecated_file( $file, $version, $replacement = null, $message = '' ) { @@ -3143,16 +3444,17 @@ function _deprecated_file( $file, $version, $replacement = null, $message = '' ) } } /** - * Marks a function argument as deprecated and informs when it has been used. + * Mark a function argument as deprecated and inform when it has been used. * * This function is to be used whenever a deprecated function argument is used. * Before this function is called, the argument must be checked for whether it was * used by comparing it to its default value or evaluating whether it is empty. * For example: - * - * if ( !empty($deprecated) ) - * _deprecated_argument( __FUNCTION__, '3.0' ); - * + * + * if ( ! empty( $deprecated ) ) { + * _deprecated_argument( __FUNCTION__, '3.0' ); + * } + * * * There is a hook deprecated_argument_run that will be called that can be used * to get the backtrace up to what file and function used the deprecated @@ -3163,9 +3465,9 @@ function _deprecated_file( $file, $version, $replacement = null, $message = '' ) * @since 3.0.0 * @access private * - * @param string $function The function that was called - * @param string $version The version of WordPress that deprecated the argument used - * @param string $message Optional. A message regarding the change. + * @param string $function The function that was called. + * @param string $version The version of WordPress that deprecated the argument used. + * @param string $message Optional. A message regarding the change. Default null. */ function _deprecated_argument( $function, $version, $message = null ) { @@ -3203,7 +3505,7 @@ function _deprecated_argument( $function, $version, $message = null ) { } /** - * Marks something as being incorrectly called. + * Mark something as being incorrectly called. * * There is a hook doing_it_wrong_run that will be called that can be used * to get the backtrace up to what file and function called the deprecated @@ -3215,8 +3517,8 @@ function _deprecated_argument( $function, $version, $message = null ) { * @access private * * @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. + * @param string $message A message explaining what has been done incorrectly. + * @param string $version The version of WordPress where the message was added. */ function _doing_it_wrong( $function, $message, $version ) { @@ -3256,7 +3558,7 @@ function _doing_it_wrong( $function, $message, $version ) { * * @since 2.5.0 * - * @return bool Whether the server is running lighttpd < 1.5.0 + * @return bool Whether the server is running lighttpd < 1.5.0. */ function is_lighttpd_before_150() { $server_parts = explode( '/', isset( $_SERVER['SERVER_SOFTWARE'] )? $_SERVER['SERVER_SOFTWARE'] : '' ); @@ -3269,9 +3571,9 @@ function is_lighttpd_before_150() { * * @since 2.5.0 * - * @param string $mod e.g. mod_rewrite - * @param bool $default The default return value if the module is not found - * @return bool + * @param string $mod The module, e.g. mod_rewrite. + * @param bool $default Optional. The default return value if the module is not found. Default false. + * @return bool Whether the specified module is loaded. */ function apache_mod_loaded($mod, $default = false) { global $is_apache; @@ -3279,11 +3581,11 @@ function apache_mod_loaded($mod, $default = false) { if ( !$is_apache ) return false; - if ( function_exists('apache_get_modules') ) { + if ( function_exists( 'apache_get_modules' ) ) { $mods = apache_get_modules(); if ( in_array($mod, $mods) ) return true; - } elseif ( function_exists('phpinfo') ) { + } elseif ( function_exists( 'phpinfo' ) && false === strpos( ini_get( 'disable_functions' ), 'phpinfo' ) ) { ob_start(); phpinfo(8); $phpinfo = ob_get_clean(); @@ -3298,7 +3600,7 @@ function apache_mod_loaded($mod, $default = false) { * * @since 2.8.0 * - * @return bool + * @return bool Whether IIS7 supports permalinks. */ function iis7_supports_permalinks() { global $is_iis7; @@ -3381,19 +3683,13 @@ function is_ssl() { * * @since 2.6.0 * - * @param string|bool $force Optional. + * @see force_ssl_admin() + * + * @param string|bool $force Optional Whether to force SSL login. Default null. * @return bool True if forced, false if not forced. */ function force_ssl_login( $force = null ) { - static $forced = false; - - if ( !is_null( $force ) ) { - $old_forced = $forced; - $forced = $force; - return $old_forced; - } - - return $forced; + return force_ssl_admin( $force ); } /** @@ -3401,7 +3697,7 @@ function force_ssl_login( $force = null ) { * * @since 2.6.0 * - * @param string|bool $force + * @param string|bool $force Optional. Whether to force SSL in admin screens. Default null. * @return bool True if forced, false if not forced. */ function force_ssl_admin( $force = null ) { @@ -3424,7 +3720,7 @@ function force_ssl_admin( $force = null ) { * * @since 2.6.0 * - * @return string + * @return string The guessed URL. */ function wp_guess_url() { if ( defined('WP_SITEURL') && '' != WP_SITEURL ) { @@ -3492,16 +3788,16 @@ function wp_suspend_cache_addition( $suspend = null ) { /** * Suspend cache invalidation. * - * Turns cache invalidation on and off. Useful during imports where you don't wont to do invalidations - * every time a post is inserted. Callers must be sure that what they are doing won't lead to an inconsistent - * cache when invalidation is suspended. + * Turns cache invalidation on and off. Useful during imports where you don't wont to do + * invalidations every time a post is inserted. Callers must be sure that what they are + * doing won't lead to an inconsistent cache when invalidation is suspended. * * @since 2.7.0 * - * @param bool $suspend Whether to suspend or enable cache invalidation - * @return bool The current suspend setting + * @param bool $suspend Optional. Whether to suspend or enable cache invalidation. Default true. + * @return bool The current suspend setting. */ -function wp_suspend_cache_invalidation($suspend = true) { +function wp_suspend_cache_invalidation( $suspend = true ) { global $_wp_suspend_cache_invalidation; $current_suspend = $_wp_suspend_cache_invalidation; @@ -3510,12 +3806,14 @@ function wp_suspend_cache_invalidation($suspend = true) { } /** - * Whether a site is the main site of the current network. + * Determine whether a site is the main site of the current network. * * @since 3.0.0 * * @param int $site_id Optional. Site ID to test. Defaults to current site. - * @return bool True if $site_id is the main site of the network, or if not running multisite. + * Defaults to current site. + * @return bool True if $site_id is the main site of the network, or if not + * running Multisite. */ function is_main_site( $site_id = null ) { // This is the current network's information; 'site' is old terminology. @@ -3531,12 +3829,12 @@ function is_main_site( $site_id = null ) { } /** - * Whether a network is the main network of the multisite install. + * Determine whether a network is the main network of the Multisite install. * * @since 3.7.0 * * @param int $network_id Optional. Network ID to test. Defaults to current network. - * @return bool True if $network_id is the main network, or if not running multisite. + * @return bool True if $network_id is the main network, or if not running Multisite. */ function is_main_network( $network_id = null ) { global $wpdb; @@ -3568,12 +3866,11 @@ function is_main_network( $network_id = null ) { } /** - * Whether global terms are enabled. - * + * Determine whether global terms are enabled. * * @since 3.0.0 * - * @return bool True if multisite and global terms enabled + * @return bool True if multisite and global terms enabled. */ function global_terms_enabled() { if ( ! is_multisite() ) @@ -3608,7 +3905,7 @@ function global_terms_enabled() { * * @since 2.8.0 * - * @return float|bool + * @return float|bool Timezone GMT offset, false otherwise. */ function wp_timezone_override_offset() { if ( !$timezone_string = get_option( 'timezone_string' ) ) { @@ -3627,6 +3924,7 @@ function wp_timezone_override_offset() { * Sort-helper for timezones. * * @since 2.9.0 + * @access private * * @param array $a * @param array $b @@ -3671,11 +3969,11 @@ function _wp_timezone_choice_usort_callback( $a, $b ) { } /** - * Gives a nicely formatted list of timezone strings. + * Gives a nicely-formatted list of timezone strings. * * @since 2.9.0 * - * @param string $selected_zone Selected Zone + * @param string $selected_zone Selected timezone. * @return string */ function wp_timezone_choice( $selected_zone ) { @@ -3801,19 +4099,22 @@ function wp_timezone_choice( $selected_zone ) { /** * Strip close comment and close php tags from file headers used by WP. - * See http://core.trac.wordpress.org/ticket/8497 * * @since 2.8.0 + * @access private * - * @param string $str + * @see https://core.trac.wordpress.org/ticket/8497 + * + * @param string $str Header comment to clean up. * @return string */ -function _cleanup_header_comment($str) { +function _cleanup_header_comment( $str ) { return trim(preg_replace("/\s*(?:\*\/|\?>).*/", '', $str)); } /** - * Permanently deletes posts, pages, attachments, and comments which have been in the trash for EMPTY_TRASH_DAYS. + * Permanently delete posts, pages, attachments, and comments which have been + * in the trash for EMPTY_TRASH_DAYS. * * @since 2.9.0 */ @@ -3867,12 +4168,15 @@ function wp_scheduled_delete() { * If the file data is not within that first 8kiB, then the author should correct * their plugin file and move the data headers to the top. * - * @see http://codex.wordpress.org/File_Header + * @link http://codex.wordpress.org/File_Header * * @since 2.9.0 - * @param string $file Path to the file - * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name') - * @param string $context If specified adds filter hook "extra_{$context}_headers" + * + * @param string $file Path to the file. + * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name'). + * @param string $context Optional. If specified adds filter hook "extra_{$context}_headers". + * Default empty. + * @return array Array of file headers in `HeaderKey => Header Value` format. */ function get_file_data( $file, $default_headers, $context = '' ) { // We don't need to write to the file, so just open for reading. @@ -3890,8 +4194,8 @@ function get_file_data( $file, $default_headers, $context = '' ) { /** * Filter extra file headers by context. * - * The dynamic portion of the hook name, $context, refers to the context - * where extra headers might be loaded. + * The dynamic portion of the hook name, `$context`, refers to + * the context where extra headers might be loaded. * * @since 2.9.0 * @@ -3920,8 +4224,10 @@ function get_file_data( $file, $default_headers, $context = '' ) { * Useful for returning true to filters easily. * * @since 3.0.0 + * * @see __return_false() - * @return bool true + * + * @return bool True. */ function __return_true() { return true; @@ -3933,8 +4239,10 @@ function __return_true() { * Useful for returning false to filters easily. * * @since 3.0.0 + * * @see __return_true() - * @return bool false + * + * @return bool False. */ function __return_false() { return false; @@ -3946,7 +4254,8 @@ function __return_false() { * Useful for returning 0 to filters easily. * * @since 3.0.0 - * @return int 0 + * + * @return int 0. */ function __return_zero() { return 0; @@ -3958,7 +4267,8 @@ function __return_zero() { * Useful for returning an empty array to filters easily. * * @since 3.0.0 - * @return array Empty array + * + * @return array Empty array. */ function __return_empty_array() { return array(); @@ -3970,7 +4280,8 @@ function __return_empty_array() { * Useful for returning null to filters easily. * * @since 3.4.0 - * @return null + * + * @return null Null value. */ function __return_null() { return null; @@ -3982,8 +4293,10 @@ function __return_null() { * Useful for returning an empty string to filters easily. * * @since 3.7.0 + * * @see __return_null() - * @return string Empty string + * + * @return string Empty string. */ function __return_empty_string() { return ''; @@ -3992,29 +4305,26 @@ function __return_empty_string() { /** * Send a HTTP header to disable content type sniffing in browsers which support it. * - * @link http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx - * @link http://src.chromium.org/viewvc/chrome?view=rev&revision=6985 - * * @since 3.0.0 - * @return none + * + * @see http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx + * @see http://src.chromium.org/viewvc/chrome?view=rev&revision=6985 */ function send_nosniff_header() { @header( 'X-Content-Type-Options: nosniff' ); } /** - * Returns a MySQL expression for selecting the week number based on the start_of_week option. + * Return a MySQL expression for selecting the week number based on the start_of_week option. * * @internal * @since 3.0.0 - * @param string $column - * @return string + * + * @param string $column Database column. + * @return string SQL clause. */ function _wp_mysql_week( $column ) { switch ( $start_of_week = (int) get_option( 'start_of_week' ) ) { - default : - case 0 : - return "WEEK( $column, 0 )"; case 1 : return "WEEK( $column, 1 )"; case 2 : @@ -4023,20 +4333,24 @@ function _wp_mysql_week( $column ) { case 5 : case 6 : return "WEEK( DATE_SUB( $column, INTERVAL $start_of_week DAY ), 0 )"; + case 0 : + default : + return "WEEK( $column, 0 )"; } } /** - * Finds hierarchy loops using a callback function that maps object IDs to parent IDs. + * Find hierarchy loops using a callback function that maps object IDs to parent IDs. * * @since 3.1.0 * @access private * - * @param callback $callback function that accepts ( ID, $callback_args ) and outputs parent_ID - * @param int $start The ID to start the loop check at - * @param int $start_parent the parent_ID of $start to use instead of calling $callback( $start ). Use null to always use $callback - * @param array $callback_args optional additional arguments to send to $callback - * @return array IDs of all members of loop + * @param callback $callback Function that accepts ( ID, $callback_args ) and outputs parent_ID. + * @param int $start The ID to start the loop check at. + * @param int $start_parent The parent_ID of $start to use instead of calling $callback( $start ). + * Use null to always use $callback + * @param array $callback_args Optional. Additional arguments to send to $callback. + * @return array IDs of all members of loop. */ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) { $override = is_null( $start_parent ) ? array() : array( $start => $start_parent ); @@ -4048,7 +4362,7 @@ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_arg } /** - * Uses the "The Tortoise and the Hare" algorithm to detect loops. + * Use the "The Tortoise and the Hare" algorithm to detect loops. * * For every step of the algorithm, the hare takes two steps and the tortoise one. * If the hare ever laps the tortoise, there must be a loop. @@ -4056,14 +4370,16 @@ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_arg * @since 3.1.0 * @access private * - * @param callback $callback function that accepts ( ID, callback_arg, ... ) and outputs parent_ID - * @param int $start The ID to start the loop check at - * @param array $override an array of ( ID => parent_ID, ... ) to use instead of $callback - * @param array $callback_args optional additional arguments to send to $callback - * @param bool $_return_loop Return loop members or just detect presence of loop? - * Only set to true if you already know the given $start is part of a loop - * (otherwise the returned array might include branches) - * @return mixed scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if $_return_loop + * @param callback $callback Function that accepts ( ID, callback_arg, ... ) and outputs parent_ID. + * @param int $start The ID to start the loop check at. + * @param array $override Optional. An array of ( ID => parent_ID, ... ) to use instead of $callback. + * Default empty array. + * @param array $callback_args Optional. Additional arguments to send to $callback. Default empty array. + * @param bool $_return_loop Optional. Return loop members or just detect presence of loop? Only set + * to true if you already know the given $start is part of a loop (otherwise + * the returned array might include branches). Default false. + * @return mixed Scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if + * $_return_loop */ function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) { $tortoise = $hare = $evanescent_hare = $start; @@ -4095,10 +4411,9 @@ function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = ar /** * Send a HTTP header to limit rendering of pages to same origin iframes. * - * @link https://developer.mozilla.org/en/the_x-frame-options_response_header - * * @since 3.1.3 - * @return none + * + * @see https://developer.mozilla.org/en/the_x-frame-options_response_header */ function send_frame_options_header() { @header( 'X-Frame-Options: SAMEORIGIN' ); @@ -4108,10 +4423,11 @@ function send_frame_options_header() { * Retrieve a list of protocols to allow in HTML attributes. * * @since 3.3.0 + * * @see wp_kses() * @see esc_url() * - * @return array Array of allowed protocols + * @return array Array of allowed protocols. */ function wp_allowed_protocols() { static $protocols; @@ -4121,8 +4437,8 @@ function wp_allowed_protocols() { /** * Filter the list of protocols allowed in HTML attributes. - * - * @since 3.0.0 + * + * @since 3.0.0 * * @param array $protocols Array of allowed protocols e.g. 'http', 'ftp', 'tel', and more. */ @@ -4133,15 +4449,21 @@ function wp_allowed_protocols() { } /** - * Return a comma separated string of functions that have been called to get to the current point in code. + * Return a comma-separated string of functions that have been called to get + * to the current point in code. * - * @link http://core.trac.wordpress.org/ticket/19589 * @since 3.4.0 * - * @param string $ignore_class A class to ignore all function calls within - useful when you want to just give info about the callee - * @param int $skip_frames A number of stack frames to skip - useful for unwinding back to the source of the issue - * @param bool $pretty Whether or not you want a comma separated string or raw array returned - * @return string|array Either a string containing a reversed comma separated trace or an array of individual calls. + * @see https://core.trac.wordpress.org/ticket/19589 + * + * @param string $ignore_class Optional. A class to ignore all function calls within - useful + * when you want to just give info about the callee. Default null. + * @param int $skip_frames Optional. A number of stack frames to skip - useful for unwinding + * back to the source of the issue. Default 0. + * @param bool $pretty Optional. Whether or not you want a comma separated string or raw + * array returned. Default true. + * @return string|array Either a string containing a reversed comma separated trace or an array + * of individual calls. */ function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) { if ( version_compare( PHP_VERSION, '5.2.5', '>=' ) ) @@ -4178,14 +4500,15 @@ function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pr } /** - * Retrieve ids that are not already present in the cache + * Retrieve ids that are not already present in the cache. * * @since 3.4.0 + * @access private * - * @param array $object_ids ID list - * @param string $cache_key The cache bucket to check against + * @param array $object_ids ID list. + * @param string $cache_key The cache bucket to check against. * - * @return array + * @return array List of ids not present in the cache. */ function _get_non_cached_ids( $object_ids, $cache_key ) { $clean = array(); @@ -4205,7 +4528,7 @@ function _get_non_cached_ids( $object_ids, $cache_key ) { * @since 3.4.0 * @access private * - * @return bool true|false + * @return bool true|false Whether the device is able to upload files. */ function _device_can_upload() { if ( ! wp_is_mobile() ) @@ -4225,8 +4548,8 @@ function _device_can_upload() { /** * Test if a given path is a stream URL * - * @param string $path The resource path or URL - * @return bool True if the path is a stream URL + * @param string $path The resource path or URL. + * @return bool True if the path is a stream URL. */ function wp_is_stream( $path ) { $wrappers = stream_get_wrappers(); @@ -4236,11 +4559,17 @@ function wp_is_stream( $path ) { } /** - * Test if the supplied date is valid for the Gregorian calendar + * Test if the supplied date is valid for the Gregorian calendar. * * @since 3.5.0 * - * @return bool true|false + * @see checkdate() + * + * @param int $month Month number. + * @param int $day Day number. + * @param int $year Year number. + * @param string $source_date The date to filter. + * @return bool True if valid date, false if not valid date. */ function wp_checkdate( $month, $day, $year, $source_date ) { /** @@ -4279,6 +4608,9 @@ function wp_auth_check_load() { /** * Filter whether to load the authentication check. * + * Passing a falsey value to the filter will effectively short-circuit + * loading the authentication check. + * * @since 3.6.0 * * @param bool $show Whether to load the authentication check. @@ -4303,9 +4635,6 @@ function wp_auth_check_html() { $current_domain = ( is_ssl() ? 'https://' : 'http://' ) . $_SERVER['HTTP_HOST']; $same_domain = ( strpos( $login_url, $current_domain ) === 0 ); - if ( $same_domain && force_ssl_login() && ! force_ssl_admin() ) - $same_domain = false; - /** * Filter whether the authentication check originated at the same domain. * @@ -4347,6 +4676,10 @@ function wp_auth_check_html() { * or if their cookie is within the grace period. * * @since 3.6.0 + * + * @param array|object $response The Heartbeat response object or array. + * @return array|object $response The Heartbeat response object or array with 'wp-auth-check' + * value set. */ function wp_auth_check( $response ) { $response['wp-auth-check'] = is_user_logged_in() && empty( $GLOBALS['login_grace_period'] ); @@ -4354,17 +4687,20 @@ function wp_auth_check( $response ) { } /** - * Return RegEx body to liberally match an opening HTML tag that: + * Return RegEx body to liberally match an opening HTML tag. + * + * Matches an opening HTML tag that: * 1. Is self-closing or * 2. Has no body but has a closing tag of the same name or * 3. Contains a body and a closing tag of the same name * - * Note: this RegEx does not balance inner tags and does not attempt to produce valid HTML + * Note: this RegEx does not balance inner tags and does not attempt + * to produce valid HTML * * @since 3.6.0 * - * @param string $tag An HTML tag name. Example: 'video' - * @return string + * @param string $tag An HTML tag name. Example: 'video'. + * @return string Tag RegEx. */ function get_tag_regex( $tag ) { if ( empty( $tag ) ) @@ -4373,14 +4709,16 @@ function get_tag_regex( $tag ) { } /** - * Return a canonical form of the provided charset appropriate for passing to PHP + * Retrieve a canonical form of the provided charset appropriate for passing to PHP * functions such as htmlspecialchars() and charset html attributes. * - * @link http://core.trac.wordpress.org/ticket/23688 * @since 3.6.0 + * @access private + * + * @see https://core.trac.wordpress.org/ticket/23688 * - * @param string A charset name - * @return string The canonical form of the charset + * @param string $charset A charset name. + * @return string The canonical form of the charset. */ function _canonical_charset( $charset ) { if ( 'UTF-8' === $charset || 'utf-8' === $charset || 'utf8' === $charset || @@ -4395,22 +4733,27 @@ function _canonical_charset( $charset ) { } /** - * Sets the mbstring internal encoding to a binary safe encoding whne func_overload is enabled. + * Set the mbstring internal encoding to a binary safe encoding when func_overload + * is enabled. * - * When mbstring.func_overload is in use for multi-byte encodings, the results from strlen() and - * similar functions respect the utf8 characters, causing binary data to return incorrect lengths. + * When mbstring.func_overload is in use for multi-byte encodings, the results from + * strlen() and similar functions respect the utf8 characters, causing binary data + * to return incorrect lengths. * - * This function overrides the mbstring encoding to a binary-safe encoding, and resets it to the - * users expected encoding afterwards through the `reset_mbstring_encoding` function. + * This function overrides the mbstring encoding to a binary-safe encoding, and + * resets it to the users expected encoding afterwards through the + * `reset_mbstring_encoding` function. * - * It is safe to recursively call this function, however each `mbstring_binary_safe_encoding()` - * call must be followed up with an equal number of `reset_mbstring_encoding()` calls. - * - * @see reset_mbstring_encoding() + * It is safe to recursively call this function, however each + * `mbstring_binary_safe_encoding()` call must be followed up with an equal number + * of `reset_mbstring_encoding()` calls. * * @since 3.7.0 * - * @param bool $reset Whether to reset the encoding back to a previously-set encoding. + * @see reset_mbstring_encoding() + * + * @param bool $reset Optional. Whether to reset the encoding back to a previously-set encoding. + * Default false. */ function mbstring_binary_safe_encoding( $reset = false ) { static $encodings = array(); @@ -4435,7 +4778,7 @@ function mbstring_binary_safe_encoding( $reset = false ) { } /** - * Resets the mbstring internal encoding to a users previously set encoding. + * Reset the mbstring internal encoding to a users previously set encoding. * * @see mbstring_binary_safe_encoding() * @@ -4444,3 +4787,25 @@ function mbstring_binary_safe_encoding( $reset = false ) { function reset_mbstring_encoding() { mbstring_binary_safe_encoding( true ); } + +/** + * Filter/validate a variable as a boolean. + * + * Alternative to `filter_var( $var, FILTER_VALIDATE_BOOLEAN )`. + * + * @since 4.0.0 + * + * @param mixed $var Boolean value to validate. + * @return bool Whether the value is validated. + */ +function wp_validate_boolean( $var ) { + if ( is_bool( $var ) ) { + return $var; + } + + if ( is_string( $var ) && 'false' === strtolower( $var ) ) { + return false; + } + + return (bool) $var; +}