<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[26485] trunk/src/wp-includes/formatting.php: Inline documentation for hooks in wp-includes/formatting.php.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/26485">26485</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2013-11-30 18:35:37 +0000 (Sat, 30 Nov 2013)</dd>
</dl>
<h3>Log Message</h3>
<pre>Inline documentation for hooks in wp-includes/formatting.php.
Props simonwheatley for the initial patch. Props DrewAPicture, kpdesign.
Fixes <a href="http://core.trac.wordpress.org/ticket/25518">#25518</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesformattingphp">trunk/src/wp-includes/formatting.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesformattingphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/formatting.php (26484 => 26485)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/formatting.php 2013-11-30 17:31:02 UTC (rev 26484)
+++ trunk/src/wp-includes/formatting.php 2013-11-30 18:35:37 UTC (rev 26485)
</span><span class="lines">@@ -101,8 +101,22 @@
</span><span class="cx">
</span><span class="cx"> // Transform into regexp sub-expression used in _wptexturize_pushpop_element
</span><span class="cx"> // Must do this every time in case plugins use these filters in a context sensitive manner
</span><del>- $no_texturize_tags = '(' . implode('|', apply_filters('no_texturize_tags', $default_no_texturize_tags) ) . ')';
- $no_texturize_shortcodes = '(' . implode('|', apply_filters('no_texturize_shortcodes', $default_no_texturize_shortcodes) ) . ')';
</del><ins>+ /**
+ * Filter the list of HTML elements not to texturize.
+ *
+ * @since 2.8.0
+ *
+ * @param array $default_no_texturize_tags An array of HTML element names.
+ */
+ $no_texturize_tags = '(' . implode( '|', apply_filters( 'no_texturize_tags', $default_no_texturize_tags ) ) . ')';
+ /**
+ * Filter the list of shortcodes not to texturize.
+ *
+ * @since 2.8.0
+ *
+ * @param array $default_no_texturize_shortcodes An array of shortcode names.
+ */
+ $no_texturize_shortcodes = '(' . implode( '|', apply_filters( 'no_texturize_shortcodes', $default_no_texturize_shortcodes ) ) . ')';
</ins><span class="cx">
</span><span class="cx"> $no_texturize_tags_stack = array();
</span><span class="cx"> $no_texturize_shortcodes_stack = array();
</span><span class="lines">@@ -842,7 +856,15 @@
</span><span class="cx"> function sanitize_file_name( $filename ) {
</span><span class="cx"> $filename_raw = $filename;
</span><span class="cx"> $special_chars = array("?", "[", "]", "/", "\\", "=", "<", ">", ":", ";", ",", "'", "\"", "&", "$", "#", "*", "(", ")", "|", "~", "`", "!", "{", "}", chr(0));
</span><del>- $special_chars = apply_filters('sanitize_file_name_chars', $special_chars, $filename_raw);
</del><ins>+ /**
+ * Filter the list of characters to remove from a filename.
+ *
+ * @since 2.8.0
+ *
+ * @param array $special_chars Characters to remove.
+ * @param string $filename_raw Filename as it was passed into sanitize_file_name().
+ */
+ $special_chars = apply_filters( 'sanitize_file_name_chars', $special_chars, $filename_raw );
</ins><span class="cx"> $filename = str_replace($special_chars, '', $filename);
</span><span class="cx"> $filename = preg_replace('/[\s-]+/', '-', $filename);
</span><span class="cx"> $filename = trim($filename, '.-_');
</span><span class="lines">@@ -851,16 +873,27 @@
</span><span class="cx"> $parts = explode('.', $filename);
</span><span class="cx">
</span><span class="cx"> // Return if only one extension
</span><del>- if ( count($parts) <= 2 )
- return apply_filters('sanitize_file_name', $filename, $filename_raw);
</del><ins>+ if ( count( $parts ) <= 2 ) {
+ /**
+ * Filter a sanitized filename string.
+ *
+ * @since 2.8.0
+ *
+ * @param string $filename Sanitized filename.
+ * @param string $filename_raw The filename prior to sanitization.
+ */
+ return apply_filters( 'sanitize_file_name', $filename, $filename_raw );
+ }
</ins><span class="cx">
</span><span class="cx"> // Process multiple extensions
</span><span class="cx"> $filename = array_shift($parts);
</span><span class="cx"> $extension = array_pop($parts);
</span><span class="cx"> $mimes = get_allowed_mime_types();
</span><span class="cx">
</span><del>- // Loop over any intermediate extensions. Munge them with a trailing underscore if they are a 2 - 5 character
- // long alpha string not in the extension whitelist.
</del><ins>+ /*
+ * Loop over any intermediate extensions. Postfix them with a trailing underscore
+ * if they are a 2 - 5 character long alpha string not in the extension whitelist.
+ */
</ins><span class="cx"> foreach ( (array) $parts as $part) {
</span><span class="cx"> $filename .= '.' . $part;
</span><span class="cx">
</span><span class="lines">@@ -878,7 +911,7 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx"> $filename .= '.' . $extension;
</span><del>-
</del><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters('sanitize_file_name', $filename, $filename_raw);
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -891,8 +924,6 @@
</span><span class="cx"> * parameters for the 'sanitize_user' filter.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.0.0
</span><del>- * @uses apply_filters() Calls 'sanitize_user' hook on username, raw username,
- * and $strict parameter.
</del><span class="cx"> *
</span><span class="cx"> * @param string $username The username to be sanitized.
</span><span class="cx"> * @param bool $strict If set limits $username to specific characters. Default false.
</span><span class="lines">@@ -914,6 +945,15 @@
</span><span class="cx"> // Consolidate contiguous whitespace
</span><span class="cx"> $username = preg_replace( '|\s+|', ' ', $username );
</span><span class="cx">
</span><ins>+ /**
+ * Filter a sanitized username string.
+ *
+ * @since 2.0.11
+ *
+ * @param string $username Sanitized username.
+ * @param string $raw_username The username prior to sanitization.
+ * @param bool $strict Whether to limit the sanitization to specific characters. Default false.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_user', $username, $raw_username, $strict );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -931,6 +971,15 @@
</span><span class="cx"> $raw_key = $key;
</span><span class="cx"> $key = strtolower( $key );
</span><span class="cx"> $key = preg_replace( '/[^a-z0-9_\-]/', '', $key );
</span><ins>+
+ /**
+ * Filter a sanitized key string.
+ *
+ * @since 3.0.0
+ *
+ * @param string $key Sanitized key.
+ * @param string $raw_key The key prior to sanitization.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_key', $key, $raw_key );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -954,7 +1003,16 @@
</span><span class="cx"> if ( 'save' == $context )
</span><span class="cx"> $title = remove_accents($title);
</span><span class="cx">
</span><del>- $title = apply_filters('sanitize_title', $title, $raw_title, $context);
</del><ins>+ /**
+ * Filter a sanitized title string.
+ *
+ * @since 1.2.1
+ *
+ * @param string $title Sanitized title.
+ * @param string $raw_title The title prior to sanitization.
+ * @param string $context The context for which the title is being sanitized.
+ */
+ $title = apply_filters( 'sanitize_title', $title, $raw_title, $context );
</ins><span class="cx">
</span><span class="cx"> if ( '' === $title || false === $title )
</span><span class="cx"> $title = $fallback_title;
</span><span class="lines">@@ -1086,6 +1144,15 @@
</span><span class="cx"> if ( '' == $sanitized )
</span><span class="cx"> $sanitized = $fallback;
</span><span class="cx">
</span><ins>+ /**
+ * Filter a sanitized HTML class string.
+ *
+ * @since 2.8.0
+ *
+ * @param string $sanitized The sanitized HTML class.
+ * @param string $class HTML class before sanitization.
+ * @param string $fallback The fallback string.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_html_class', $sanitized, $class, $fallback );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1170,6 +1237,13 @@
</span><span class="cx"> */
</span><span class="cx"> function balanceTags( $text, $force = false ) {
</span><span class="cx"> if ( $force || get_option('use_balanceTags') == 1 ) {
</span><ins>+ /**
+ * Filter the list of delimiters to be used before tags are balanced.
+ *
+ * @since 3.8.0
+ *
+ * @param array $delimiters An array of delimiters, e.g '<!--more.*?-->', '<!--nextpage-->'.
+ */
</ins><span class="cx"> $balance_tags_delimiters = apply_filters( 'balance_tags_delimiters', array( '<!--more.*?-->', '<!--nextpage-->' ) );
</span><span class="cx"> // Capture lets PREG_SPLIT_DELIM_CAPTURE return the delimiters
</span><span class="cx"> $delimiters_regex = '/(' . implode( '|', $balance_tags_delimiters ) . ')/';
</span><span class="lines">@@ -1325,6 +1399,13 @@
</span><span class="cx"> * @return string The text after the filter (and possibly htmlspecialchars()) has been run.
</span><span class="cx"> */
</span><span class="cx"> function format_to_edit( $content, $richedit = false ) {
</span><ins>+ /**
+ * Filter the text to be formatted for editing.
+ *
+ * @since 1.2.1
+ *
+ * @param string $content The text, prior to formatting for editing.
+ */
</ins><span class="cx"> $content = apply_filters( 'format_to_edit', $content );
</span><span class="cx"> if ( ! $richedit )
</span><span class="cx"> $content = esc_textarea( $content );
</span><span class="lines">@@ -1340,7 +1421,14 @@
</span><span class="cx"> * @return string Text returned from the 'format_to_post' filter.
</span><span class="cx"> */
</span><span class="cx"> function format_to_post($content) {
</span><del>- $content = apply_filters('format_to_post', $content);
</del><ins>+ /**
+ * Filter the string returned by format_to_post().
+ *
+ * @since 1.2.1
+ *
+ * @param string $content The string to format.
+ */
+ $content = apply_filters( 'format_to_post', $content );
</ins><span class="cx"> return $content;
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1776,6 +1864,15 @@
</span><span class="cx"> $img = $wpsmiliestrans[ $smiley ];
</span><span class="cx"> $smiley_masked = esc_attr( $smiley );
</span><span class="cx">
</span><ins>+ /**
+ * Filter the Smiley image URL before it's used in the image element.
+ *
+ * @since 2.9.0
+ *
+ * @param string $smiley_url URL for the smiley image.
+ * @param string $img Filename for the smiley image.
+ * @param string $site_url Site URL, as returned by site_url().
+ */
</ins><span class="cx"> $src_url = apply_filters( 'smilies_src', includes_url( "images/smilies/$img" ), $img, site_url() );
</span><span class="cx">
</span><span class="cx"> return " <img src='$src_url' alt='$smiley_masked' class='wp-smiley' /> ";
</span><span class="lines">@@ -1849,11 +1946,26 @@
</span><span class="cx">
</span><span class="cx"> // Test for the minimum length the email can be
</span><span class="cx"> if ( strlen( $email ) < 3 ) {
</span><ins>+ /**
+ * Filter whether an email address is valid.
+ *
+ * This filter is evaluated under several different contexts, such as 'email_too_short',
+ * 'email_no_at', 'local_invalid_chars', 'domain_period_sequence', 'domain_period_limits',
+ * 'domain_no_periods', 'sub_hyphen_limits', 'sub_invalid_chars', or no specific context.
+ *
+ * @since 2.8.0
+ *
+ * @param bool $is_email Whether the email address has passed the is_email() checks. Default false.
+ * @param string $email The email address being checked.
+ * @param string $message An explanatory message to the user.
+ * @param string $context Context under which the email was tested.
+ */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'email_too_short' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Test for an @ character after the first position
</span><span class="cx"> if ( strpos( $email, '@', 1 ) === false ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'email_no_at' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1863,17 +1975,20 @@
</span><span class="cx"> // LOCAL PART
</span><span class="cx"> // Test for invalid characters
</span><span class="cx"> if ( !preg_match( '/^[a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]+$/', $local ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'local_invalid_chars' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // DOMAIN PART
</span><span class="cx"> // Test for sequences of periods
</span><span class="cx"> if ( preg_match( '/\.{2,}/', $domain ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'domain_period_sequence' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Test for leading and trailing periods and whitespace
</span><span class="cx"> if ( trim( $domain, " \t\n\r\0\x0B." ) !== $domain ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'domain_period_limits' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1882,6 +1997,7 @@
</span><span class="cx">
</span><span class="cx"> // Assume the domain will have at least two subs
</span><span class="cx"> if ( 2 > count( $subs ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'domain_no_periods' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1889,16 +2005,19 @@
</span><span class="cx"> foreach ( $subs as $sub ) {
</span><span class="cx"> // Test for leading and trailing hyphens and whitespace
</span><span class="cx"> if ( trim( $sub, " \t\n\r\0\x0B-" ) !== $sub ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'sub_hyphen_limits' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Test for invalid characters
</span><span class="cx"> if ( !preg_match('/^[a-z0-9-]+$/i', $sub ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', false, $email, 'sub_invalid_chars' );
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Congratulations your email made it!
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'is_email', $email, $email, null );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2078,11 +2197,25 @@
</span><span class="cx"> function sanitize_email( $email ) {
</span><span class="cx"> // Test for the minimum length the email can be
</span><span class="cx"> if ( strlen( $email ) < 3 ) {
</span><ins>+ /**
+ * Filter a sanitized email address.
+ *
+ * This filter is evaluated under several contexts, including 'email_too_short',
+ * 'email_no_at', 'local_invalid_chars', 'domain_period_sequence', 'domain_period_limits',
+ * 'domain_no_periods', 'domain_no_valid_subs', or no context.
+ *
+ * @since 2.8.0
+ *
+ * @param string $email The sanitized email address.
+ * @param string $email The email address, as provided to sanitize_email().
+ * @param string $message A message to pass to the user.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'email_too_short' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Test for an @ character after the first position
</span><span class="cx"> if ( strpos( $email, '@', 1 ) === false ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'email_no_at' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2093,6 +2226,7 @@
</span><span class="cx"> // Test for invalid characters
</span><span class="cx"> $local = preg_replace( '/[^a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]/', '', $local );
</span><span class="cx"> if ( '' === $local ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'local_invalid_chars' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2100,12 +2234,14 @@
</span><span class="cx"> // Test for sequences of periods
</span><span class="cx"> $domain = preg_replace( '/\.{2,}/', '', $domain );
</span><span class="cx"> if ( '' === $domain ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'domain_period_sequence' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> // Test for leading and trailing periods and whitespace
</span><span class="cx"> $domain = trim( $domain, " \t\n\r\0\x0B." );
</span><span class="cx"> if ( '' === $domain ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'domain_period_limits' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2114,6 +2250,7 @@
</span><span class="cx">
</span><span class="cx"> // Assume the domain will have at least two subs
</span><span class="cx"> if ( 2 > count( $subs ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'domain_no_periods' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2136,6 +2273,7 @@
</span><span class="cx">
</span><span class="cx"> // If there aren't 2 or more valid subs
</span><span class="cx"> if ( 2 > count( $new_subs ) ) {
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', '', $email, 'domain_no_valid_subs' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2146,6 +2284,7 @@
</span><span class="cx"> $email = $local . '@' . $domain;
</span><span class="cx">
</span><span class="cx"> // Congratulations your email made it!
</span><ins>+ /** This filter is documented in wp-includes/formatting.php */
</ins><span class="cx"> return apply_filters( 'sanitize_email', $email, $email, null );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2225,13 +2364,37 @@
</span><span class="cx">
</span><span class="cx"> $text = strip_shortcodes( $text );
</span><span class="cx">
</span><del>- $text = apply_filters('the_content', $text);
</del><ins>+ /** This filter is documented in wp-includes/post-template.php */
+ $text = apply_filters( 'the_content', $text );
</ins><span class="cx"> $text = str_replace(']]>', ']]>', $text);
</span><del>- $excerpt_length = apply_filters('excerpt_length', 55);
- $excerpt_more = apply_filters('excerpt_more', ' ' . '[…]');
</del><ins>+
+ /**
+ * Filter the number of words in an excerpt.
+ *
+ * @since 2.7.0
+ *
+ * @param int $number The number of words. Default 55.
+ */
+ $excerpt_length = apply_filters( 'excerpt_length', 55 );
+ /**
+ * Filter the string in the "more" link displayed after a trimmed excerpt.
+ *
+ * @since 2.9.0
+ *
+ * @param string $more_string The string shown within the more link.
+ */
+ $excerpt_more = apply_filters( 'excerpt_more', ' ' . '[…]' );
</ins><span class="cx"> $text = wp_trim_words( $text, $excerpt_length, $excerpt_more );
</span><span class="cx"> }
</span><del>- return apply_filters('wp_trim_excerpt', $text, $raw_excerpt);
</del><ins>+ /**
+ * Filter the trimmed excerpt string.
+ *
+ * @since 2.8.0
+ *
+ * @param string $text The trimmed text.
+ * @param string $raw_excerpt The text prior to trimming.
+ */
+ return apply_filters( 'wp_trim_excerpt', $text, $raw_excerpt );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -2271,6 +2434,16 @@
</span><span class="cx"> } else {
</span><span class="cx"> $text = implode( $sep, $words_array );
</span><span class="cx"> }
</span><ins>+ /**
+ * Filter the text content after words have been trimmed.
+ *
+ * @since 3.3.0
+ *
+ * @param string $text The trimmed text.
+ * @param int $num_words The number of words to trim the text to. Default 5.
+ * @param string $more An optional string to append to the end of the trimmed text, e.g. ….
+ * @param string $original_text The text before it was trimmed.
+ */
</ins><span class="cx"> return apply_filters( 'wp_trim_words', $text, $num_words, $more, $original_text );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2284,7 +2457,16 @@
</span><span class="cx"> */
</span><span class="cx"> function ent2ncr($text) {
</span><span class="cx">
</span><del>- // Allow a plugin to short-circuit and override the mappings.
</del><ins>+ /**
+ * Filter text before named entities are converted into numbered entities.
+ *
+ * A non-null string must be returned for the filter to be evaluated.
+ *
+ * @since 3.3.0
+ *
+ * @param null $converted_text The text to be converted. Default null.
+ * @param string $text The text prior to entity conversion.
+ */
</ins><span class="cx"> $filtered = apply_filters( 'pre_ent2ncr', null, $text );
</span><span class="cx"> if( null !== $filtered )
</span><span class="cx"> return $filtered;
</span><span class="lines">@@ -2563,14 +2745,30 @@
</span><span class="cx"> * @return string The formatted text after filter is applied.
</span><span class="cx"> */
</span><span class="cx"> function wp_richedit_pre($text) {
</span><del>- // Filtering a blank results in an annoying <br />\n
- if ( empty($text) ) return apply_filters('richedit_pre', '');
</del><ins>+ if ( empty( $text ) ) {
+ /**
+ * Filter text returned for the rich text editor.
+ *
+ * This filter is first evaluated, and the value returned, if an empty string
+ * is passed to wp_richedit_pre(). If an empty string is passed, it results
+ * in a break tag and line feed.
+ *
+ * If a non-empty string is passed, the filter is evaluated on the wp_richedit_pre()
+ * return after being formatted.
+ *
+ * @since 2.0.0
+ *
+ * @param string $output Text for the rich text editor.
+ */
+ return apply_filters( 'richedit_pre', '' );
+ }
</ins><span class="cx">
</span><span class="cx"> $output = convert_chars($text);
</span><span class="cx"> $output = wpautop($output);
</span><span class="cx"> $output = htmlspecialchars($output, ENT_NOQUOTES, get_option( 'blog_charset' ) );
</span><span class="cx">
</span><del>- return apply_filters('richedit_pre', $output);
</del><ins>+ /** This filter is documented in wp-includes/formatting.php */
+ return apply_filters( 'richedit_pre', $output );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -2588,7 +2786,14 @@
</span><span class="cx"> if ( !empty($output) )
</span><span class="cx"> $output = htmlspecialchars($output, ENT_NOQUOTES, get_option( 'blog_charset' ) ); // convert only < > &
</span><span class="cx">
</span><del>- return apply_filters('htmledit_pre', $output);
</del><ins>+ /**
+ * Filter the text before it is formatted for the HTML editor.
+ *
+ * @since 2.5.0
+ *
+ * @param string $output The HTML-formatted text.
+ */
+ return apply_filters( 'htmledit_pre', $output );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -2683,7 +2888,16 @@
</span><span class="cx"> return '';
</span><span class="cx"> }
</span><span class="cx">
</span><del>- return apply_filters('clean_url', $good_protocol_url, $original_url, $_context);
</del><ins>+ /**
+ * Filter a string cleaned and escaped for output as a URL.
+ *
+ * @since 2.3.0
+ *
+ * @param string $good_protocol_url The cleaned URL to be returned.
+ * @param string $original_url The URL prior to cleaning.
+ * @param string $_context If 'display', replace ampersands and single quotes only.
+ */
+ return apply_filters( 'clean_url', $good_protocol_url, $original_url, $_context );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -2734,6 +2948,17 @@
</span><span class="cx"> $safe_text = preg_replace( '/&#(x)?0*(?(1)27|39);?/i', "'", stripslashes( $safe_text ) );
</span><span class="cx"> $safe_text = str_replace( "\r", '', $safe_text );
</span><span class="cx"> $safe_text = str_replace( "\n", '\\n', addslashes( $safe_text ) );
</span><ins>+ /**
+ * Filter a string cleaned and escaped for output in JavaScript.
+ *
+ * Text passed to esc_js() is stripped of invalid or special characters,
+ * and properly slashed for output.
+ *
+ * @since 2.0.11
+ *
+ * @param string $safe_text The text after it has been escaped.
+ * @param string $text The text prior to being escaped.
+ */
</ins><span class="cx"> return apply_filters( 'js_escape', $safe_text, $text );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2748,6 +2973,17 @@
</span><span class="cx"> function esc_html( $text ) {
</span><span class="cx"> $safe_text = wp_check_invalid_utf8( $text );
</span><span class="cx"> $safe_text = _wp_specialchars( $safe_text, ENT_QUOTES );
</span><ins>+ /**
+ * Filter a string cleaned and escaped for output in HTML.
+ *
+ * Text passed to esc_html() is stripped of invalid or special characters
+ * before output.
+ *
+ * @since 2.8.0
+ *
+ * @param string $safe_text The text after it has been escaped.
+ * @param string $text The text prior to being escaped.
+ */
</ins><span class="cx"> return apply_filters( 'esc_html', $safe_text, $text );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2762,6 +2998,17 @@
</span><span class="cx"> function esc_attr( $text ) {
</span><span class="cx"> $safe_text = wp_check_invalid_utf8( $text );
</span><span class="cx"> $safe_text = _wp_specialchars( $safe_text, ENT_QUOTES );
</span><ins>+ /**
+ * Filter a string cleaned and escaped for output in an HTML attribute.
+ *
+ * Text passed to esc_attr() is stripped of invalid or special characters
+ * before output.
+ *
+ * @since 2.0.11
+ *
+ * @param string $safe_text The text after it has been escaped.
+ * @param string $text The text prior to being escaped.
+ */
</ins><span class="cx"> return apply_filters( 'attribute_escape', $safe_text, $text );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2775,6 +3022,14 @@
</span><span class="cx"> */
</span><span class="cx"> function esc_textarea( $text ) {
</span><span class="cx"> $safe_text = htmlspecialchars( $text, ENT_QUOTES, get_option( 'blog_charset' ) );
</span><ins>+ /**
+ * Filter a string cleaned and escaped for output in a textarea element.
+ *
+ * @since 3.1.0
+ *
+ * @param string $safe_text The text after it has been escaped.
+ * @param string $text The text prior to being escaped.
+ */
</ins><span class="cx"> return apply_filters( 'esc_textarea', $safe_text, $text );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -2788,7 +3043,15 @@
</span><span class="cx"> */
</span><span class="cx"> function tag_escape($tag_name) {
</span><span class="cx"> $safe_tag = strtolower( preg_replace('/[^a-zA-Z0-9_:]/', '', $tag_name) );
</span><del>- return apply_filters('tag_escape', $safe_tag, $tag_name);
</del><ins>+ /**
+ * Filter a string cleaned and escaped for output as an HTML tag.
+ *
+ * @since 2.8.0
+ *
+ * @param string $safe_tag The tag name after it has been escaped.
+ * @param string $tag_name The text before it was escaped.
+ */
+ return apply_filters( 'tag_escape', $safe_tag, $tag_name );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -2994,7 +3257,15 @@
</span><span class="cx"> break;
</span><span class="cx"> }
</span><span class="cx">
</span><del>- $value = apply_filters("sanitize_option_{$option}", $value, $option);
</del><ins>+ /**
+ * Filter an option value following sanitization.
+ *
+ * @since 2.3.0
+ *
+ * @param string $value The sanitized option value.
+ * @param string $option The option name.
+ */
+ $value = apply_filters( "sanitize_option_{$option}", $value, $option );
</ins><span class="cx">
</span><span class="cx"> return $value;
</span><span class="cx"> }
</span><span class="lines">@@ -3006,7 +3277,6 @@
</span><span class="cx"> * {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.2.1
</span><del>- * @uses apply_filters() for the 'wp_parse_str' filter.
</del><span class="cx"> *
</span><span class="cx"> * @param string $string The string to be parsed.
</span><span class="cx"> * @param array $array Variables will be stored in this array.
</span><span class="lines">@@ -3015,6 +3285,13 @@
</span><span class="cx"> parse_str( $string, $array );
</span><span class="cx"> if ( get_magic_quotes_gpc() )
</span><span class="cx"> $array = stripslashes_deep( $array );
</span><ins>+ /**
+ * Filter the array of variables derived from a parsed string.
+ *
+ * @since 2.3.0
+ *
+ * @param array $array The array populated with variables.
+ */
</ins><span class="cx"> $array = apply_filters( 'wp_parse_str', $array );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -3095,7 +3372,16 @@
</span><span class="cx"> $arg = isset($args[$arg_index]) ? $args[$arg_index] : '';
</span><span class="cx"> }
</span><span class="cx">
</span><del>- // Apply filters OR sprintf
</del><ins>+ /**
+ * Filter a fragment from the pattern passed to wp_sprintf().
+ *
+ * If the fragment is unchanged, then sprintf() will be run on the fragment.
+ *
+ * @since 2.5.0
+ *
+ * @param string $fragment A fragment from the pattern.
+ * @param string $arg The argument.
+ */
</ins><span class="cx"> $_fragment = apply_filters( 'wp_sprintf', $fragment, $arg );
</span><span class="cx"> if ( $_fragment != $fragment )
</span><span class="cx"> $fragment = $_fragment;
</span><span class="lines">@@ -3132,15 +3418,23 @@
</span><span class="cx"> if ( empty($args) )
</span><span class="cx"> return '';
</span><span class="cx">
</span><del>- // Translate and filter the delimiter set (avoid ampersands and entities here)
- $l = apply_filters('wp_sprintf_l', array(
</del><ins>+ /**
+ * Filter the translated delimiters used by wp_sprintf_l().
+ *
+ * Please note: Ampersands and entities should be avoided here.
+ *
+ * @since 2.5.0
+ *
+ * @param array $delimiters An array of translated delimiters.
+ */
+ $l = apply_filters( 'wp_sprintf_l', array(
</ins><span class="cx"> /* translators: used between list items, there is a space after the comma */
</span><span class="cx"> 'between' => __(', '),
</span><span class="cx"> /* translators: used between list items, there is a space after the and */
</span><span class="cx"> 'between_last_two' => __(', and '),
</span><span class="cx"> /* translators: used between only two list items, there is a space after the and */
</span><span class="cx"> 'between_only_two' => __(' and '),
</span><del>- ));
</del><ins>+ ) );
</ins><span class="cx">
</span><span class="cx"> $args = (array) $args;
</span><span class="cx"> $result = array_shift($args);
</span><span class="lines">@@ -3332,7 +3626,15 @@
</span><span class="cx"> $filtered = trim( preg_replace('/ +/', ' ', $filtered) );
</span><span class="cx"> }
</span><span class="cx">
</span><del>- return apply_filters('sanitize_text_field', $filtered, $str);
</del><ins>+ /**
+ * Filter a sanitized text field string.
+ *
+ * @since 2.9.0
+ *
+ * @param string $filtered The sanitized string.
+ * @param string $str The string prior to being sanitized.
+ */
+ return apply_filters( 'sanitize_text_field', $filtered, $str );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="lines">@@ -3381,6 +3683,14 @@
</span><span class="cx"> */
</span><span class="cx"> function sanitize_mime_type( $mime_type ) {
</span><span class="cx"> $sani_mime_type = preg_replace( '/[^-+*.a-zA-Z0-9\/]/', '', $mime_type );
</span><ins>+ /**
+ * Filter a mime type following sanitization.
+ *
+ * @since 3.1.3
+ *
+ * @param string $sani_mime_type The sanitized mime type.
+ * @param string $mime_type The mime type prior to sanitization.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_mime_type', $sani_mime_type, $mime_type );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -3400,6 +3710,17 @@
</span><span class="cx"> }
</span><span class="cx"> $urls_to_ping = array_map( 'esc_url_raw', $urls_to_ping );
</span><span class="cx"> $urls_to_ping = implode( "\n", $urls_to_ping );
</span><ins>+ /**
+ * Filter a list of trackback URLs following sanitization.
+ *
+ * The string returned here consists of a space or carriage return-delimited list
+ * of trackback URLs.
+ *
+ * @since 3.4.0
+ *
+ * @param string $urls_to_ping Sanitized space or carriage return separated URLs.
+ * @param string $to_ping Space or carriage return separated URLs before sanitization.
+ */
</ins><span class="cx"> return apply_filters( 'sanitize_trackback_urls', $urls_to_ping, $to_ping );
</span><span class="cx"> }
</span><span class="cx">
</span></span></pre>
</div>
</div>
</body>
</html>