sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add missing doc blocks to formatting.php.

Browse Source 
Rehabilitate the spacing of various doc blocks.
Standardize some return values that are adjacent to similar functions.

See #32444.


git-svn-id: https://develop.svn.wordpress.org/trunk@32590 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Scott Taylor 2015-05-25 02:58:00 +00:00
parent 09d6c51801
commit 928dc46a3b
1 changed files with 159 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

277
src/wp-includes/formatting.php
View File

@ -21,13 +21,22 @@
* Code within certain html blocks are skipped. * Code within certain html blocks are skipped.
* *
* @since 0.71 * @since 0.71
* @uses $wp_cockneyreplace Array of formatted entities for certain common phrases *
* @global array $wp_cockneyreplace Array of formatted entities for certain common phrases
* @global array $shortcode_tags
* @staticvar array $static_characters
* @staticvar array $static_replacements
* @staticvar array $dynamic_characters
* @staticvar array $dynamic_replacements
* @staticvar array $default_no_texturize_tags
* @staticvar array $default_no_texturize_shortcodes
* @staticvar bool $run_texturize
* *
* @param string $text The text to be formatted * @param string $text The text to be formatted
* @param bool $reset Set to true for unit testing. Translated patterns will reset. * @param bool $reset Set to true for unit testing. Translated patterns will reset.
* @return string The string replaced with html entities * @return string The string replaced with html entities
*/ */
function wptexturize($text, $reset = false) { function wptexturize( $text, $reset = false ) {
global $wp_cockneyreplace, $shortcode_tags; global $wp_cockneyreplace, $shortcode_tags;
static $static_characters, $static_replacements, $dynamic_characters, $dynamic_replacements, static $static_characters, $static_replacements, $dynamic_characters, $dynamic_replacements,
$default_no_texturize_tags, $default_no_texturize_shortcodes, $run_texturize = true; $default_no_texturize_tags, $default_no_texturize_shortcodes, $run_texturize = true;
@ -297,9 +306,7 @@ function wptexturize($text, $reset = false) {
$text = implode( '', $textarr ); $text = implode( '', $textarr );
// Replace each & with & unless it already looks like an entity. // Replace each & with & unless it already looks like an entity.
$text = preg_replace('/&(?!#(?:\d+|x[a-f0-9]+);|[a-z1-4]{1,8};)/i', '&', $text); return preg_replace( '/&(?!#(?:\d+|x[a-f0-9]+);|[a-z1-4]{1,8};)/i', '&', $text );
return $text;
} }
/** /**
@ -313,10 +320,10 @@ function wptexturize($text, $reset = false) {
* @access private * @access private
* *
* @param string $text Text to check. Must be a tag like `<html>` or `[shortcode]`. * @param string $text Text to check. Must be a tag like `<html>` or `[shortcode]`.
* @param array $stack List of open tag elements. * @param array $stack List of open tag elements.
* @param array $disabled_elements The tag names to match against. Spaces are not allowed in tag names. * @param array $disabled_elements The tag names to match against. Spaces are not allowed in tag names.
*/ */
function _wptexturize_pushpop_element($text, &$stack, $disabled_elements) { function _wptexturize_pushpop_element( $text, &$stack, $disabled_elements ) {
// Is it an opening tag or closing tag? // Is it an opening tag or closing tag?
if ( '/' !== $text[1] ) { if ( '/' !== $text[1] ) {
$opening_tag = true; $opening_tag = true;
@ -370,7 +377,7 @@ function _wptexturize_pushpop_element($text, &$stack, $disabled_elements) {
* after paragraphing. Default true. * after paragraphing. Default true.
* @return string Text which has been converted into correct paragraph tags. * @return string Text which has been converted into correct paragraph tags.
*/ */
function wpautop($pee, $br = true) { function wpautop( $pee, $br = true ) {
$pre_tags = array(); $pre_tags = array();
if ( trim($pee) === '' ) if ( trim($pee) === '' )
@ -419,7 +426,7 @@ function wpautop($pee, $br = true) {
$pee = preg_replace('!(</' . $allblocks . '>)!', "$1\n\n", $pee); $pee = preg_replace('!(</' . $allblocks . '>)!', "$1\n\n", $pee);
// Standardize newline characters to "\n". // Standardize newline characters to "\n".
$pee = str_replace(array("\r\n", "\r"), "\n", $pee); $pee = str_replace(array("\r\n", "\r"), "\n", $pee);
// Collapse line breaks before and after <option> elements so they don't get autop'd. // Collapse line breaks before and after <option> elements so they don't get autop'd.
if ( strpos( $pee, '<option' ) !== false ) { if ( strpos( $pee, '<option' ) !== false ) {
@ -462,24 +469,24 @@ function wpautop($pee, $br = true) {
} }
// Under certain strange conditions it could create a P of entirely whitespace. // Under certain strange conditions it could create a P of entirely whitespace.
$pee = preg_replace('|<p>\s*</p>|', '', $pee); $pee = preg_replace('|<p>\s*</p>|', '', $pee);
// Add a closing <p> inside <div>, <address>, or <form> tag if missing. // Add a closing <p> inside <div>, <address>, or <form> tag if missing.
$pee = preg_replace('!<p>([^<]+)</(div|address|form)>!', "<p>$1</p></$2>", $pee); $pee = preg_replace('!<p>([^<]+)</(div|address|form)>!', "<p>$1</p></$2>", $pee);
// If an opening or closing block element tag is wrapped in a <p>, unwrap it. // If an opening or closing block element tag is wrapped in a <p>, unwrap it.
$pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee); $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
// In some cases <li> may get wrapped in <p>, fix them. // In some cases <li> may get wrapped in <p>, fix them.
$pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee); $pee = preg_replace("|<p>(<li.+?)</p>|", "$1", $pee);
// If a <blockquote> is wrapped with a <p>, move it inside the <blockquote>. // If a <blockquote> is wrapped with a <p>, move it inside the <blockquote>.
$pee = preg_replace('|<p><blockquote([^>]*)>|i', "<blockquote$1><p>", $pee); $pee = preg_replace('|<p><blockquote([^>]*)>|i', "<blockquote$1><p>", $pee);
$pee = str_replace('</blockquote></p>', '</p></blockquote>', $pee); $pee = str_replace('</blockquote></p>', '</p></blockquote>', $pee);
// If an opening or closing block element tag is preceded by an opening <p> tag, remove it. // If an opening or closing block element tag is preceded by an opening <p> tag, remove it.
$pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)!', "$1", $pee); $pee = preg_replace('!<p>\s*(</?' . $allblocks . '[^>]*>)!', "$1", $pee);
// If an opening or closing block element tag is followed by a closing <p> tag, remove it. // If an opening or closing block element tag is followed by a closing <p> tag, remove it.
$pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee); $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*</p>!', "$1", $pee);
@ -489,7 +496,7 @@ function wpautop($pee, $br = true) {
$pee = preg_replace_callback('/<(script|style).*?<\/\\1>/s', '_autop_newline_preservation_helper', $pee); $pee = preg_replace_callback('/<(script|style).*?<\/\\1>/s', '_autop_newline_preservation_helper', $pee);
// Replace any new line characters that aren't preceded by a <br /> with a <br />. // Replace any new line characters that aren't preceded by a <br /> with a <br />.
$pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee); $pee = preg_replace('|(?<!<br />)\s*\n|', "<br />\n", $pee);
// Replace newline placeholders with newlines. // Replace newline placeholders with newlines.
$pee = str_replace('<WPPreserveNewline />', "\n", $pee); $pee = str_replace('<WPPreserveNewline />', "\n", $pee);
@ -497,7 +504,7 @@ function wpautop($pee, $br = true) {
// If a <br /> tag is after an opening or closing block tag, remove it. // If a <br /> tag is after an opening or closing block tag, remove it.
$pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*<br />!', "$1", $pee); $pee = preg_replace('!(</?' . $allblocks . '[^>]*>)\s*<br />!', "$1", $pee);
// If a <br /> tag is before a subset of opening or closing block tags, remove it. // If a <br /> tag is before a subset of opening or closing block tags, remove it.
$pee = preg_replace('!<br />(\s*</?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol)[^>]*>)!', '$1', $pee); $pee = preg_replace('!<br />(\s*</?(?:p|li|div|dl|dd|dt|th|pre|td|ul|ol)[^>]*>)!', '$1', $pee);
$pee = preg_replace( "|\n</p>$|", '</p>', $pee ); $pee = preg_replace( "|\n</p>$|", '</p>', $pee );
@ -519,7 +526,7 @@ function wpautop($pee, $br = true) {
* @return string * @return string
*/ */
function _autop_newline_preservation_helper( $matches ) { function _autop_newline_preservation_helper( $matches ) {
return str_replace("\n", "<WPPreserveNewline />", $matches[0]); return str_replace( "\n", "<WPPreserveNewline />", $matches[0] );
} }
/** /**
@ -529,6 +536,8 @@ function _autop_newline_preservation_helper( $matches ) {
* *
* @since 2.9.0 * @since 2.9.0
* *
* @global array $shortcode_tags
*
* @param string $pee The content. * @param string $pee The content.
* @return string The filtered content. * @return string The filtered content.
*/ */
@ -589,7 +598,7 @@ function shortcode_unautop( $pee ) {
* @param string $str The string to be checked * @param string $str The string to be checked
* @return bool True if $str fits a UTF-8 model, false otherwise. * @return bool True if $str fits a UTF-8 model, false otherwise.
*/ */
function seems_utf8($str) { function seems_utf8( $str ) {
mbstring_binary_safe_encoding(); mbstring_binary_safe_encoding();
$length = strlen($str); $length = strlen($str);
reset_mbstring_encoding(); reset_mbstring_encoding();
@ -621,10 +630,12 @@ function seems_utf8($str) {
* @since 1.2.2 * @since 1.2.2
* @access private * @access private
* *
* @param string $string The text which is to be encoded. * @staticvar string|false $_charset
* @param int $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES. *
* @param string $charset Optional. The character encoding of the string. Default is false. * @param string $string The text which is to be encoded.
* @param boolean $double_encode Optional. Whether to encode existing html entities. Default is false. * @param int $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES.
* @param string $charset Optional. The character encoding of the string. Default is false.
* @param bool $double_encode Optional. Whether to encode existing html entities. Default is false.
* @return string The encoded text with HTML entities. * @return string The encoded text with HTML entities.
*/ */
function _wp_specialchars( $string, $quote_style = ENT_NOQUOTES, $charset = false, $double_encode = false ) { function _wp_specialchars( $string, $quote_style = ENT_NOQUOTES, $charset = false, $double_encode = false ) {
@ -701,8 +712,14 @@ function _wp_specialchars( $string, $quote_style = ENT_NOQUOTES, $charset = fals
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $string The text which is to be decoded. * @param string $string The text which is to be decoded.
* @param mixed $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old _wp_specialchars() values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES. * @param string|int $quote_style Optional. Converts double quotes if set to ENT_COMPAT,
* both single and double if set to ENT_QUOTES or
* none if set to ENT_NOQUOTES.
* Also compatible with old _wp_specialchars() values;
* converting single quotes if set to 'single',
* double if set to 'double' or both if otherwise set.
* Default is ENT_NOQUOTES.
* @return string The decoded text without HTML entities. * @return string The decoded text without HTML entities.
*/ */
function wp_specialchars_decode( $string, $quote_style = ENT_NOQUOTES ) { function wp_specialchars_decode( $string, $quote_style = ENT_NOQUOTES ) {
@ -758,8 +775,11 @@ function wp_specialchars_decode( $string, $quote_style = ENT_NOQUOTES ) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $string The text which is to be checked. * @staticvar bool $is_utf8
* @param boolean $strip Optional. Whether to attempt to strip out invalid UTF8. Default is false. * @staticvar bool $utf8_pcre
*
* @param string $string The text which is to be checked.
* @param bool $strip Optional. Whether to attempt to strip out invalid UTF8. Default is false.
* @return string The checked text. * @return string The checked text.
*/ */
function wp_check_invalid_utf8( $string, $strip = false ) { function wp_check_invalid_utf8( $string, $strip = false ) {
@ -807,7 +827,7 @@ function wp_check_invalid_utf8( $string, $strip = false ) {
* @since 1.5.0 * @since 1.5.0
* *
* @param string $utf8_string * @param string $utf8_string
* @param int $length Max length of the string * @param int $length Max length of the string
* @return string String with Unicode encoded for URI. * @return string String with Unicode encoded for URI.
*/ */
function utf8_uri_encode( $utf8_string, $length = 0 ) { function utf8_uri_encode( $utf8_string, $length = 0 ) {
@ -870,7 +890,7 @@ function utf8_uri_encode( $utf8_string, $length = 0 ) {
* @param string $string Text that might have accent characters * @param string $string Text that might have accent characters
* @return string Filtered string with replaced "nice" characters. * @return string Filtered string with replaced "nice" characters.
*/ */
function remove_accents($string) { function remove_accents( $string ) {
if ( !preg_match('/[\x80-\xff]/', $string) ) if ( !preg_match('/[\x80-\xff]/', $string) )
return $string; return $string;
@ -1187,7 +1207,7 @@ function sanitize_file_name( $filename ) {
* @since 2.0.0 * @since 2.0.0
* *
* @param string $username The username to be sanitized. * @param string $username The username to be sanitized.
* @param bool $strict If set limits $username to specific characters. Default false. * @param bool $strict If set limits $username to specific characters. Default false.
* @return string The sanitized username, after passing through filters. * @return string The sanitized username, after passing through filters.
*/ */
function sanitize_user( $username, $strict = false ) { function sanitize_user( $username, $strict = false ) {
@ -1253,9 +1273,9 @@ function sanitize_key( $key ) {
* *
* @since 1.0.0 * @since 1.0.0
* *
* @param string $title The string to be sanitized. * @param string $title The string to be sanitized.
* @param string $fallback_title Optional. A title to use if $title is empty. * @param string $fallback_title Optional. A title to use if $title is empty.
* @param string $context Optional. The operation for which the string is sanitized * @param string $context Optional. The operation for which the string is sanitized
* @return string The sanitized string. * @return string The sanitized string.
*/ */
function sanitize_title( $title, $fallback_title = '', $context = 'save' ) { function sanitize_title( $title, $fallback_title = '', $context = 'save' ) {
@ -1303,9 +1323,9 @@ function sanitize_title_for_query( $title ) {
* *
* @since 1.2.0 * @since 1.2.0
* *
* @param string $title The title to be sanitized. * @param string $title The title to be sanitized.
* @param string $raw_title Optional. Not used. * @param string $raw_title Optional. Not used.
* @param string $context Optional. The operation for which the string is sanitized. * @param string $context Optional. The operation for which the string is sanitized.
* @return string The sanitized title. * @return string The sanitized title.
*/ */
function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) { function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
@ -1372,7 +1392,7 @@ function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'displa
* @since 2.5.1 * @since 2.5.1
* *
* @param string $orderby Order by clause to be validated. * @param string $orderby Order by clause to be validated.
* @return string|bool Returns $orderby if valid, false otherwise. * @return string|false Returns $orderby if valid, false otherwise.
*/ */
function sanitize_sql_orderby( $orderby ) { function sanitize_sql_orderby( $orderby ) {
if ( preg_match( '/^\s*(([a-z0-9_]+|`[a-z0-9_]+`)(\s+(ASC|DESC))?\s*(,\s*(?=[a-z0-9_`])|$))+$/i', $orderby ) || preg_match( '/^\s*RAND\(\s*\)\s*$/i', $orderby ) ) { if ( preg_match( '/^\s*(([a-z0-9_]+|`[a-z0-9_]+`)(\s+(ASC|DESC))?\s*(,\s*(?=[a-z0-9_`])|$))+$/i', $orderby ) || preg_match( '/^\s*RAND\(\s*\)\s*$/i', $orderby ) ) {
@ -1391,7 +1411,7 @@ function sanitize_sql_orderby( $orderby ) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $class The classname to be sanitized * @param string $class The classname to be sanitized
* @param string $fallback Optional. The value to return if the sanitization ends up as an empty string. * @param string $fallback Optional. The value to return if the sanitization ends up as an empty string.
* Defaults to an empty string. * Defaults to an empty string.
* @return string The sanitized value * @return string The sanitized value
@ -1427,11 +1447,11 @@ function sanitize_html_class( $class, $fallback = '' ) {
* *
* @since 0.71 * @since 0.71
* *
* @param string $content String of characters to be converted. * @param string $content String of characters to be converted.
* @param string $deprecated Not used. * @param string $deprecated Not used.
* @return string Converted string. * @return string Converted string.
*/ */
function convert_chars($content, $deprecated = '') { function convert_chars( $content, $deprecated = '' ) {
if ( !empty( $deprecated ) ) if ( !empty( $deprecated ) )
_deprecated_argument( __FUNCTION__, '0.71' ); _deprecated_argument( __FUNCTION__, '0.71' );
@ -1493,8 +1513,8 @@ function convert_chars($content, $deprecated = '') {
* *
* @since 0.71 * @since 0.71
* *
* @param string $text Text to be balanced * @param string $text Text to be balanced
* @param bool $force If true, forces balancing, ignoring the value of the option. Default false. * @param bool $force If true, forces balancing, ignoring the value of the option. Default false.
* @return string Balanced text * @return string Balanced text
*/ */
function balanceTags( $text, $force = false ) { function balanceTags( $text, $force = false ) {
@ -1645,8 +1665,8 @@ function force_balance_tags( $text ) {
* *
* @since 0.71 * @since 0.71
* *
* @param string $content The text about to be edited. * @param string $content The text about to be edited.
* @param bool $richedit Whether the $content should not pass through htmlspecialchars(). Default false (meaning it will be passed). * @param bool $richedit Whether the $content should not pass through htmlspecialchars(). Default false (meaning it will be passed).
* @return string The text after the filter (and possibly htmlspecialchars()) has been run. * @return string The text after the filter (and possibly htmlspecialchars()) has been run.
*/ */
function format_to_edit( $content, $richedit = false ) { function format_to_edit( $content, $richedit = false ) {
@ -1676,12 +1696,12 @@ function format_to_edit( $content, $richedit = false ) {
* *
* @since 0.71 * @since 0.71
* *
* @param mixed $number Number to append zeros to if not greater than threshold. * @param int $number Number to append zeros to if not greater than threshold.
* @param int $threshold Digit places number needs to be to not have zeros added. * @param int $threshold Digit places number needs to be to not have zeros added.
* @return string Adds leading zeros to number if needed. * @return string Adds leading zeros to number if needed.
*/ */
function zeroise($number, $threshold) { function zeroise( $number, $threshold ) {
return sprintf('%0'.$threshold.'s', $number); return sprintf( '%0' . $threshold . 's', $number );
} }
/** /**
@ -1692,7 +1712,7 @@ function zeroise($number, $threshold) {
* @param string $string Value to which backslashes will be added. * @param string $string Value to which backslashes will be added.
* @return string String with backslashes inserted. * @return string String with backslashes inserted.
*/ */
function backslashit($string) { function backslashit( $string ) {
if ( isset( $string[0] ) && $string[0] >= '0' && $string[0] <= '9' ) if ( isset( $string[0] ) && $string[0] >= '0' && $string[0] <= '9' )
$string = '\\\\' . $string; $string = '\\\\' . $string;
return addcslashes( $string, 'A..Za..z' ); return addcslashes( $string, 'A..Za..z' );
@ -1760,7 +1780,7 @@ function addslashes_gpc($gpc) {
* @param mixed $value The value to be stripped. * @param mixed $value The value to be stripped.
* @return mixed Stripped value. * @return mixed Stripped value.
*/ */
function stripslashes_deep($value) { function stripslashes_deep( $value ) {
if ( is_array($value) ) { if ( is_array($value) ) {
$value = array_map('stripslashes_deep', $value); $value = array_map('stripslashes_deep', $value);
} elseif ( is_object($value) ) { } elseif ( is_object($value) ) {
@ -1784,9 +1804,8 @@ function stripslashes_deep($value) {
* @param array|string $value The array or string to be encoded. * @param array|string $value The array or string to be encoded.
* @return array|string $value The encoded array (or string from the callback). * @return array|string $value The encoded array (or string from the callback).
*/ */
function urlencode_deep($value) { function urlencode_deep( $value ) {
$value = is_array($value) ? array_map('urlencode_deep', $value) : urlencode($value); return is_array( $value ) ? array_map( 'urlencode_deep', $value ) : urlencode( $value );
return $value;
} }
/** /**
@ -1807,7 +1826,7 @@ function rawurlencode_deep( $value ) {
* @since 0.71 * @since 0.71
* *
* @param string $email_address Email address. * @param string $email_address Email address.
* @param int $hex_encoding Optional. Set to 1 to enable hex encoding. * @param int $hex_encoding Optional. Set to 1 to enable hex encoding.
* @return string Converted email address. * @return string Converted email address.
*/ */
function antispambot( $email_address, $hex_encoding = 0 ) { function antispambot( $email_address, $hex_encoding = 0 ) {
@ -1823,9 +1842,7 @@ function antispambot( $email_address, $hex_encoding = 0 ) {
} }
} }
$email_no_spam_address = str_replace( '@', '&#64;', $email_no_spam_address ); return str_replace( '@', '&#64;', $email_no_spam_address );
return $email_no_spam_address;
} }
/** /**
@ -1840,7 +1857,7 @@ function antispambot( $email_address, $hex_encoding = 0 ) {
* @param array $matches Single Regex Match. * @param array $matches Single Regex Match.
* @return string HTML A element with URI address. * @return string HTML A element with URI address.
*/ */
function _make_url_clickable_cb($matches) { function _make_url_clickable_cb( $matches ) {
$url = $matches[2]; $url = $matches[2];
if ( ')' == $matches[3] && strpos( $url, '(' ) ) { if ( ')' == $matches[3] && strpos( $url, '(' ) ) {
@ -1877,7 +1894,7 @@ function _make_url_clickable_cb($matches) {
* @param array $matches Single Regex Match. * @param array $matches Single Regex Match.
* @return string HTML A element with URL address. * @return string HTML A element with URL address.
*/ */
function _make_web_ftp_clickable_cb($matches) { function _make_web_ftp_clickable_cb( $matches ) {
$ret = ''; $ret = '';
$dest = $matches[2]; $dest = $matches[2];
$dest = 'http://' . $dest; $dest = 'http://' . $dest;
@ -1905,7 +1922,7 @@ function _make_web_ftp_clickable_cb($matches) {
* @param array $matches Single Regex Match. * @param array $matches Single Regex Match.
* @return string HTML A element with email address. * @return string HTML A element with email address.
*/ */
function _make_email_clickable_cb($matches) { function _make_email_clickable_cb( $matches ) {
$email = $matches[2] . '@' . $matches[3]; $email = $matches[2] . '@' . $matches[3];
return $matches[1] . "<a href=\"mailto:$email\">$email</a>"; return $matches[1] . "<a href=\"mailto:$email\">$email</a>";
} }
@ -1976,8 +1993,7 @@ function make_clickable( $text ) {
} }
// Cleanup of accidental links within links // Cleanup of accidental links within links
$r = preg_replace( '#(<a([ \r\n\t]+[^>]+?>|>))<a [^>]+?>([^>]+?)</a></a>#i', "$1$3</a>", $r ); return preg_replace( '#(<a([ \r\n\t]+[^>]+?>|>))<a [^>]+?>([^>]+?)</a></a>#i', "$1$3</a>", $r );
return $r;
} }
/** /**
@ -2006,7 +2022,7 @@ function make_clickable( $text ) {
* @access private * @access private
* *
* @param string $string The string to split. * @param string $string The string to split.
* @param int $goal The desired chunk length. * @param int $goal The desired chunk length.
* @return array Numeric array of chunks. * @return array Numeric array of chunks.
*/ */
function _split_str_by_whitespace( $string, $goal ) { function _split_str_by_whitespace( $string, $goal ) {
@ -2048,8 +2064,7 @@ function wp_rel_nofollow( $text ) {
// This is a pre save filter, so text is already escaped. // This is a pre save filter, so text is already escaped.
$text = stripslashes($text); $text = stripslashes($text);
$text = preg_replace_callback('|<a (.+?)>|i', 'wp_rel_nofollow_callback', $text); $text = preg_replace_callback('|<a (.+?)>|i', 'wp_rel_nofollow_callback', $text);
$text = wp_slash($text); return wp_slash( $text );
return $text;
} }
/** /**
@ -2076,9 +2091,10 @@ function wp_rel_nofollow_callback( $matches ) {
* Looks up one smiley code in the $wpsmiliestrans global array and returns an * Looks up one smiley code in the $wpsmiliestrans global array and returns an
* `<img>` string for that smiley. * `<img>` string for that smiley.
* *
* @global array $wpsmiliestrans
* @since 2.8.0 * @since 2.8.0
* *
* @global array $wpsmiliestrans
*
* @param array $matches Single match. Smiley code to convert to image. * @param array $matches Single match. Smiley code to convert to image.
* @return string Image string for smiley. * @return string Image string for smiley.
*/ */
@ -2121,7 +2137,8 @@ function translate_smiley( $matches ) {
* used in the function isn't empty. * used in the function isn't empty.
* *
* @since 0.71 * @since 0.71
* @uses $wp_smiliessearch *
* @global string|array $wp_smiliessearch
* *
* @param string $text Content to convert smilies from text. * @param string $text Content to convert smilies from text.
* @return string Converted content with text smilies replaced with images. * @return string Converted content with text smilies replaced with images.
@ -2172,8 +2189,8 @@ function convert_smilies( $text ) {
* *
* @since 0.71 * @since 0.71
* *
* @param string $email Email address to verify. * @param string $email Email address to verify.
* @param boolean $deprecated Deprecated. * @param bool $deprecated Deprecated.
* @return string|bool Either false or the valid email address. * @return string|bool Either false or the valid email address.
*/ */
function is_email( $email, $deprecated = false ) { function is_email( $email, $deprecated = false ) {
@ -2265,14 +2282,13 @@ function is_email( $email, $deprecated = false ) {
* @param string $string Subject line * @param string $string Subject line
* @return string Converted string to ASCII * @return string Converted string to ASCII
*/ */
function wp_iso_descrambler($string) { function wp_iso_descrambler( $string ) {
/* this may only work with iso-8859-1, I'm afraid */ /* this may only work with iso-8859-1, I'm afraid */
if (!preg_match('#\=\?(.+)\?Q\?(.+)\?\=#i', $string, $matches)) { if (!preg_match('#\=\?(.+)\?Q\?(.+)\?\=#i', $string, $matches)) {
return $string; return $string;
} else { } else {
$subject = str_replace('_', ' ', $matches[2]); $subject = str_replace('_', ' ', $matches[2]);
$subject = preg_replace_callback('#\=([0-9a-f]{2})#i', '_wp_iso_convert', $subject); return preg_replace_callback( '#\=([0-9a-f]{2})#i', '_wp_iso_convert', $subject );
return $subject;
} }
} }
@ -2359,7 +2375,7 @@ function get_date_from_gmt( $string, $format = 'Y-m-d H:i:s' ) {
* @param string $timezone Either 'Z' for 0 offset or '±hhmm'. * @param string $timezone Either 'Z' for 0 offset or '±hhmm'.
* @return int|float The offset in seconds. * @return int|float The offset in seconds.
*/ */
function iso8601_timezone_to_offset($timezone) { function iso8601_timezone_to_offset( $timezone ) {
// $timezone is either 'Z' or '[+|-]hhmm' // $timezone is either 'Z' or '[+|-]hhmm'
if ($timezone == 'Z') { if ($timezone == 'Z') {
$offset = 0; $offset = 0;
@ -2378,10 +2394,10 @@ function iso8601_timezone_to_offset($timezone) {
* @since 1.5.0 * @since 1.5.0
* *
* @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}. * @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}.
* @param string $timezone Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'. * @param string $timezone Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'.
* @return string The date and time in MySQL DateTime format - Y-m-d H:i:s. * @return string The date and time in MySQL DateTime format - Y-m-d H:i:s.
*/ */
function iso8601_to_datetime($date_string, $timezone = 'user') { function iso8601_to_datetime( $date_string, $timezone = 'user' ) {
$timezone = strtolower($timezone); $timezone = strtolower($timezone);
if ($timezone == 'gmt') { if ($timezone == 'gmt') {
@ -2416,7 +2432,7 @@ function iso8601_to_datetime($date_string, $timezone = 'user') {
* @param string $text Content to replace links to open in a new window. * @param string $text Content to replace links to open in a new window.
* @return string Content that has filtered links. * @return string Content that has filtered links.
*/ */
function popuplinks($text) { function popuplinks( $text ) {
$text = preg_replace('/<a (.+?)>/i', "<a $1 target='_blank' rel='external'>", $text); $text = preg_replace('/<a (.+?)>/i', "<a $1 target='_blank' rel='external'>", $text);
return $text; return $text;
} }
@ -2532,7 +2548,7 @@ function sanitize_email( $email ) {
* @since 1.5.0 * @since 1.5.0
* *
* @param int $from Unix timestamp from which the difference begins. * @param int $from Unix timestamp from which the difference begins.
* @param int $to Optional. Unix timestamp to end the time difference. Default becomes time() if not set. * @param int $to Optional. Unix timestamp to end the time difference. Default becomes time() if not set.
* @return string Human readable time difference. * @return string Human readable time difference.
*/ */
function human_time_diff( $from, $to = '' ) { function human_time_diff( $from, $to = '' ) {
@ -2603,7 +2619,7 @@ function human_time_diff( $from, $to = '' ) {
* @param string $text Optional. The excerpt. If set to empty, an excerpt is generated. * @param string $text Optional. The excerpt. If set to empty, an excerpt is generated.
* @return string The excerpt. * @return string The excerpt.
*/ */
function wp_trim_excerpt($text = '') { function wp_trim_excerpt( $text = '' ) {
$raw_excerpt = $text; $raw_excerpt = $text;
if ( '' == $text ) { if ( '' == $text ) {
$text = get_the_content(''); $text = get_the_content('');
@ -2652,9 +2668,9 @@ function wp_trim_excerpt($text = '') {
* *
* @since 3.3.0 * @since 3.3.0
* *
* @param string $text Text to trim. * @param string $text Text to trim.
* @param int $num_words Number of words. Default 55. * @param int $num_words Number of words. Default 55.
* @param string $more Optional. What to append if $text needs to be trimmed. Default '&hellip;'. * @param string $more Optional. What to append if $text needs to be trimmed. Default '&hellip;'.
* @return string Trimmed text. * @return string Trimmed text.
*/ */
function wp_trim_words( $text, $num_words = 55, $more = null ) { function wp_trim_words( $text, $num_words = 55, $more = null ) {
@ -2701,7 +2717,7 @@ function wp_trim_words( $text, $num_words = 55, $more = null ) {
* @param string $text The text within which entities will be converted. * @param string $text The text within which entities will be converted.
* @return string Text with converted entities. * @return string Text with converted entities.
*/ */
function ent2ncr($text) { function ent2ncr( $text ) {
/** /**
* Filter text before named entities are converted into numbered entities. * Filter text before named entities are converted into numbered entities.
@ -2990,7 +3006,7 @@ function ent2ncr($text) {
* @param string $text The text to be formatted. * @param string $text The text to be formatted.
* @return string The formatted text after filter is applied. * @return string The formatted text after filter is applied.
*/ */
function wp_richedit_pre($text) { function wp_richedit_pre( $text ) {
if ( empty( $text ) ) { if ( empty( $text ) ) {
/** /**
* Filter text returned for the rich text editor. * Filter text returned for the rich text editor.
@ -3028,7 +3044,7 @@ function wp_richedit_pre($text) {
* @param string $output The text to be formatted. * @param string $output The text to be formatted.
* @return string Formatted text after filter applied. * @return string Formatted text after filter applied.
*/ */
function wp_htmledit_pre($output) { function wp_htmledit_pre( $output ) {
if ( !empty($output) ) if ( !empty($output) )
$output = htmlspecialchars($output, ENT_NOQUOTES, get_option( 'blog_charset' ) ); // convert only < > & $output = htmlspecialchars($output, ENT_NOQUOTES, get_option( 'blog_charset' ) ); // convert only < > &
@ -3052,8 +3068,9 @@ function wp_htmledit_pre($output) {
* @since 2.8.1 * @since 2.8.1
* @access private * @access private
* *
* @param string|array $search The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles. * @param string|array $search The value being searched for, otherwise known as the needle.
* @param string $subject The string being searched and replaced on, otherwise known as the haystack. * An array may be used to designate multiple needles.
* @param string $subject The string being searched and replaced on, otherwise known as the haystack.
* @return string The string with the replaced svalues. * @return string The string with the replaced svalues.
*/ */
function _deep_replace( $search, $subject ) { function _deep_replace( $search, $subject ) {
@ -3075,6 +3092,9 @@ function _deep_replace( $search, $subject ) {
* is preparing an array for use in an IN clause. * is preparing an array for use in an IN clause.
* *
* @since 2.8.0 * @since 2.8.0
*
* @global wpdb $wpdb
*
* @param string|array $data Unescaped data * @param string|array $data Unescaped data
* @return string|array Escaped data * @return string|array Escaped data
*/ */
@ -3092,10 +3112,12 @@ function esc_sql( $data ) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $url The URL to be cleaned. * @param string $url The URL to be cleaned.
* @param array $protocols Optional. An array of acceptable protocols. * @param array $protocols Optional. An array of acceptable protocols.
* Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'svn' if not set. * Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto',
* @param string $_context Private. Use esc_url_raw() for database usage. * 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms',
* 'rtsp', 'svn' if not set.
* @param string $_context Private. Use esc_url_raw() for database usage.
* @return string The cleaned $url after the 'clean_url' filter is applied. * @return string The cleaned $url after the 'clean_url' filter is applied.
*/ */
function esc_url( $url, $protocols = null, $_context = 'display' ) { function esc_url( $url, $protocols = null, $_context = 'display' ) {
@ -3149,8 +3171,8 @@ function esc_url( $url, $protocols = null, $_context = 'display' ) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @param string $url The URL to be cleaned. * @param string $url The URL to be cleaned.
* @param array $protocols An array of acceptable protocols. * @param array $protocols An array of acceptable protocols.
* @return string The cleaned URL. * @return string The cleaned URL.
*/ */
function esc_url_raw( $url, $protocols = null ) { function esc_url_raw( $url, $protocols = null ) {
@ -3167,7 +3189,7 @@ function esc_url_raw( $url, $protocols = null ) {
* @param string $myHTML The text to be converted. * @param string $myHTML The text to be converted.
* @return string Converted text. * @return string Converted text.
*/ */
function htmlentities2($myHTML) { function htmlentities2( $myHTML ) {
$translation_table = get_html_translation_table( HTML_ENTITIES, ENT_QUOTES ); $translation_table = get_html_translation_table( HTML_ENTITIES, ENT_QUOTES );
$translation_table[chr(38)] = '&'; $translation_table[chr(38)] = '&';
return preg_replace( "/&(?![A-Za-z]{0,4}\w{2,3};|#[0-9]{2,3};)/", "&amp;", strtr($myHTML, $translation_table) ); return preg_replace( "/&(?![A-Za-z]{0,4}\w{2,3};|#[0-9]{2,3};)/", "&amp;", strtr($myHTML, $translation_table) );
@ -3284,7 +3306,7 @@ function esc_textarea( $text ) {
* @param string $tag_name * @param string $tag_name
* @return string * @return string
*/ */
function tag_escape($tag_name) { function tag_escape( $tag_name ) {
$safe_tag = strtolower( preg_replace('/[^a-zA-Z0-9_:]/', '', $tag_name) ); $safe_tag = strtolower( preg_replace('/[^a-zA-Z0-9_:]/', '', $tag_name) );
/** /**
* Filter a string cleaned and escaped for output as an HTML tag. * Filter a string cleaned and escaped for output as an HTML tag.
@ -3321,11 +3343,13 @@ function wp_make_link_relative( $link ) {
* *
* @since 2.0.5 * @since 2.0.5
* *
* @global wpdb $wpdb
*
* @param string $option The name of the option. * @param string $option The name of the option.
* @param string $value The unsanitised value. * @param string $value The unsanitised value.
* @return string Sanitized value. * @return string Sanitized value.
*/ */
function sanitize_option($option, $value) { function sanitize_option( $option, $value ) {
global $wpdb; global $wpdb;
$original_value = $value; $original_value = $value;
@ -3523,9 +3547,7 @@ function sanitize_option($option, $value) {
* @param string $option The option name. * @param string $option The option name.
* @param string $original_value The original value passed to the function. * @param string $original_value The original value passed to the function.
*/ */
$value = apply_filters( "sanitize_option_{$option}", $value, $option, $original_value ); return apply_filters( "sanitize_option_{$option}", $value, $option, $original_value );
return $value;
} }
/** /**
@ -3537,7 +3559,7 @@ function sanitize_option($option, $value) {
* @since 2.2.1 * @since 2.2.1
* *
* @param string $string The string to be parsed. * @param string $string The string to be parsed.
* @param array $array Variables will be stored in this array. * @param array $array Variables will be stored in this array.
*/ */
function wp_parse_str( $string, &$array ) { function wp_parse_str( $string, &$array ) {
parse_str( $string, $array ); parse_str( $string, $array );
@ -3587,7 +3609,7 @@ function wp_pre_kses_less_than_callback( $matches ) {
* @since 2.5.0 * @since 2.5.0
* @link http://www.php.net/sprintf * @link http://www.php.net/sprintf
* *
* @param string $pattern The string which formatted args are inserted. * @param string $pattern The string which formatted args are inserted.
* @param mixed $args ,... Arguments to be formatted into the $pattern string. * @param mixed $args ,... Arguments to be formatted into the $pattern string.
* @return string The formatted string. * @return string The formatted string.
*/ */
@ -3662,10 +3684,10 @@ function wp_sprintf( $pattern ) {
* @since 2.5.0 * @since 2.5.0
* *
* @param string $pattern Content containing '%l' at the beginning. * @param string $pattern Content containing '%l' at the beginning.
* @param array $args List items to prepend to the content and replace '%l'. * @param array $args List items to prepend to the content and replace '%l'.
* @return string Localized list items and rest of the content. * @return string Localized list items and rest of the content.
*/ */
function wp_sprintf_l($pattern, $args) { function wp_sprintf_l( $pattern, $args ) {
// Not a match // Not a match
if ( substr($pattern, 0, 2) != '%l' ) if ( substr($pattern, 0, 2) != '%l' )
return $pattern; return $pattern;
@ -3720,9 +3742,9 @@ function wp_sprintf_l($pattern, $args) {
* *
* @since 2.5.0 * @since 2.5.0
* *
* @param string $str String to get the excerpt from. * @param string $str String to get the excerpt from.
* @param integer $count Maximum number of characters to take. * @param int $count Maximum number of characters to take.
* @param string $more Optional. What to append if $str needs to be trimmed. Defaults to empty string. * @param string $more Optional. What to append if $str needs to be trimmed. Defaults to empty string.
* @return string The excerpt. * @return string The excerpt.
*/ */
function wp_html_excerpt( $str, $count, $more = null ) { function wp_html_excerpt( $str, $count, $more = null ) {
@ -3745,9 +3767,11 @@ function wp_html_excerpt( $str, $count, $more = null ) {
* *
* @since 2.7.0 * @since 2.7.0
* *
* @global string $_links_add_base
*
* @param string $content String to search for links in. * @param string $content String to search for links in.
* @param string $base The base URL to prefix to links. * @param string $base The base URL to prefix to links.
* @param array $attrs The attributes which should be processed. * @param array $attrs The attributes which should be processed.
* @return string The processed content. * @return string The processed content.
*/ */
function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) { function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) {
@ -3763,10 +3787,12 @@ function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) {
* @since 2.7.0 * @since 2.7.0
* @access private * @access private
* *
* @global string $_links_add_base
*
* @param string $m The matched link. * @param string $m The matched link.
* @return string The processed link. * @return string The processed link.
*/ */
function _links_add_base($m) { function _links_add_base( $m ) {
global $_links_add_base; global $_links_add_base;
//1 = attribute name 2 = quotation mark 3 = URL //1 = attribute name 2 = quotation mark 3 = URL
return $m[1] . '=' . $m[2] . return $m[1] . '=' . $m[2] .
@ -3787,9 +3813,11 @@ function _links_add_base($m) {
* *
* @since 2.7.0 * @since 2.7.0
* *
* @global string $_links_add_target
*
* @param string $content String to search for links in. * @param string $content String to search for links in.
* @param string $target The Target to add to the links. * @param string $target The Target to add to the links.
* @param array $tags An array of tags to apply to. * @param array $tags An array of tags to apply to.
* @return string The processed content. * @return string The processed content.
*/ */
function links_add_target( $content, $target = '_blank', $tags = array('a') ) { function links_add_target( $content, $target = '_blank', $tags = array('a') ) {
@ -3805,6 +3833,8 @@ function links_add_target( $content, $target = '_blank', $tags = array('a') ) {
* @since 2.7.0 * @since 2.7.0
* @access private * @access private
* *
* @global string $_links_add_target
*
* @param string $m The matched link. * @param string $m The matched link.
* @return string The processed link. * @return string The processed link.
*/ */
@ -3839,8 +3869,8 @@ function normalize_whitespace( $str ) {
* *
* @since 2.9.0 * @since 2.9.0
* *
* @param string $string String containing HTML tags * @param string $string String containing HTML tags
* @param bool $remove_breaks optional Whether to remove left over line breaks and white space chars * @param bool $remove_breaks Optional. Whether to remove left over line breaks and white space chars
* @return string The processed string. * @return string The processed string.
*/ */
function wp_strip_all_tags($string, $remove_breaks = false) { function wp_strip_all_tags($string, $remove_breaks = false) {
@ -3867,7 +3897,7 @@ function wp_strip_all_tags($string, $remove_breaks = false) {
* @param string $str * @param string $str
* @return string * @return string
*/ */
function sanitize_text_field($str) { function sanitize_text_field( $str ) {
$filtered = wp_check_invalid_utf8( $str ); $filtered = wp_check_invalid_utf8( $str );
if ( strpos($filtered, '<') !== false ) { if ( strpos($filtered, '<') !== false ) {
@ -3905,7 +3935,7 @@ function sanitize_text_field($str) {
* *
* @since 3.1.0 * @since 3.1.0
* *
* @param string $path A path. * @param string $path A path.
* @param string $suffix If the filename ends in suffix this will also be cut off. * @param string $suffix If the filename ends in suffix this will also be cut off.
* @return string * @return string
*/ */
@ -3919,6 +3949,8 @@ function wp_basename( $path, $suffix = '' ) {
* Violating our coding standards for a good function name. * Violating our coding standards for a good function name.
* *
* @since 3.0.0 * @since 3.0.0
*
* @staticvar string|false $dblq
*/ */
function capital_P_dangit( $text ) { function capital_P_dangit( $text ) {
// Simple replacement for titles // Simple replacement for titles
@ -4035,7 +4067,7 @@ function wp_unslash( $value ) {
* @since 3.6.0 * @since 3.6.0
* *
* @param string $content A string which might contain a URL. * @param string $content A string which might contain a URL.
* @return string The found URL. * @return string|false The found URL.
*/ */
function get_url_in_content( $content ) { function get_url_in_content( $content ) {
if ( empty( $content ) ) { if ( empty( $content ) ) {
@ -4058,6 +4090,8 @@ function get_url_in_content( $content ) {
* *
* @since 4.0.0 * @since 4.0.0
* *
* @staticvar string $spaces
*
* @return string The spaces regexp. * @return string The spaces regexp.
*/ */
function wp_spaces_regexp() { function wp_spaces_regexp() {
@ -4086,6 +4120,8 @@ function wp_spaces_regexp() {
* Print the important emoji-related styles. * Print the important emoji-related styles.
* *
* @since 4.2.0 * @since 4.2.0
*
* @staticvar bool $printed
*/ */
function print_emoji_styles() { function print_emoji_styles() {
static $printed = false; static $printed = false;
@ -4113,6 +4149,11 @@ img.emoji {
<?php <?php
} }
/**
*
* @global string $wp_version
* @staticvar bool $printed
*/
function print_emoji_detection_script() { function print_emoji_detection_script() {
global $wp_version; global $wp_version;
static $printed = false; static $printed = false;