Ticket #5638: phpdoc.formatting.diff
| File phpdoc.formatting.diff, 33.3 KB (added by scohoust, 4 years ago) |
|---|
-
Users/Scott/Sites/wp/trunk/wp-includes/formatting.php
1 1 <?php 2 2 /** 3 * Main Wordpress Formatting API 3 * Main Wordpress Formatting API. 4 4 * 5 * Handles many functions for formatting output 5 * Handles many functions for formatting output. 6 6 * 7 7 * @package WordPress 8 8 **/ … … 18 18 * <code> 19 19 * ’cause today’s effort makes it worth tomorrow’s “holiday”… 20 20 * </code> 21 * Code within certain html blocks are skipped. 21 * Code within certain html blocks are skipped. 22 22 * 23 23 * @since 0.71 24 24 * @uses $wp_cockneyreplace Array of formatted entities for certain common phrases … … 76 76 } 77 77 78 78 /** 79 * Accepts matches array from preg_replace_callback in wpautop() or a string 79 * Accepts matches array from preg_replace_callback in wpautop() or a string. 80 80 * 81 * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not converted into paragraphs or line-breaks. 81 * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not 82 * converted into paragraphs or line-breaks. 82 83 * 83 84 * @since 1.2.0 84 85 * 85 * @param array|string $matches The array or string 86 * @param array|string $matches The array or string 86 87 * @return string The pre block without paragraph/line-break conversion. 87 88 */ 88 89 function clean_pre($matches) { … … 99 100 } 100 101 101 102 /** 102 * Replaces double line-breaks with paragraph elements 103 * Replaces double line-breaks with paragraph elements. 103 104 * 104 * A group of regex replaces used to identify text formatted with newlines and replace105 * double line-breaks with HTML paragraph tags. The remaining line-breaks after conversion106 * become <<br />> tags, unless $br is set to '0' or 'false'.107 * 105 * A group of regex replaces used to identify text formatted with newlines and 106 * replace double line-breaks with HTML paragraph tags. The remaining 107 * line-breaks after conversion become <<br />> tags, unless $br is set to '0' 108 * or 'false'. 108 109 * 109 110 * @since 0.71 110 111 * 111 112 * @param string $pee The text which has to be formatted. 112 * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true. 113 * @return string Text which has been converted into correct paragraph tags. 113 * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true. 114 * @return string Text which has been converted into correct paragraph tags. 114 115 */ 115 116 function wpautop($pee, $br = 1) { 116 117 $pee = $pee . "\n"; // just to make things a little easier, pad the end … … 179 180 } 180 181 181 182 /** 182 * Converts a number of special characters into their HTML entities 183 * Converts a number of special characters into their HTML entities. 183 184 * 184 * Differs from htmlspecialchars as existing HTML entities will not be encoded. Specificically185 * changes: & to &, < to < and > to >.185 * Differs from htmlspecialchars as existing HTML entities will not be encoded. 186 * Specificically changes: & to &, < to < and > to >. 186 187 * 187 * $quotes can be set to 'single' to encode ' to ', 'double' to encode " to ", or '1' to do both.188 * Default is 0 where no quotes are encoded.188 * $quotes can be set to 'single' to encode ' to ', 'double' to encode " to 189 * ", or '1' to do both. Default is 0 where no quotes are encoded. 189 190 * 190 191 * @since 1.2.2 191 192 * 192 * @param string $text The text which is to be encoded 193 * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0. 194 * @return string The encoded text with HTML entities. 193 * @param string $text The text which is to be encoded. 194 * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0. 195 * @return string The encoded text with HTML entities. 195 196 */ 196 197 function wp_specialchars( $text, $quotes = 0 ) { 197 198 // Like htmlspecialchars except don't double-encode HTML entities … … 264 265 } 265 266 266 267 /** 267 * Replaces accents in a string 268 * Replaces accents in a string. 268 269 * 269 270 * {@internal Missing Long Description}} 270 271 * 271 272 * @since 1.2.1 272 273 * 273 274 * @param string $string The text to be filtered. 274 * @return string Filtered string with replaced "nice" characters 275 * @return string Filtered string with replaced "nice" characters. 275 276 */ 276 277 function remove_accents($string) { 277 278 if ( !preg_match('/[\x80-\xff]/', $string) ) … … 404 405 } 405 406 406 407 /** 407 * Filters certain characters from the file name. 408 * Filters certain characters from the file name. 408 409 * 409 410 * {@internal Missing Long Description}} 410 411 * 411 412 * @since 2.1.0 412 413 * 413 * @param string $name The string to be sanitized 414 * @return string Sanitized string 414 * @param string $name The string to be sanitized. 415 * @return string Sanitized string. 415 416 */ 416 417 function sanitize_file_name( $name ) { // Like sanitize_title, but with periods 417 418 $name = strtolower( $name ); … … 426 427 } 427 428 428 429 /** 429 * Removes characters from the username 430 * Removes characters from the username. 430 431 * 431 * If $strict is true, only alphanumeric characters (as well as _, space, ., -, @) are returned. 432 * If $strict is true, only alphanumeric characters (as well as _, space, ., -, 433 * @) are returned. 432 434 * 433 435 * @since 2.0.0 434 436 * 435 * @param string $username The username to be sanitized. 436 * @param bool $strict If set limits $username to specific characters. Default false. 437 * @return string The sanitized username, after passing through filters. 437 * @param string $username The username to be sanitized. 438 * @param bool $strict If set limits $username to specific characters. Default false. 439 * @return string The sanitized username, after passing through filters. 438 440 */ 439 441 function sanitize_user( $username, $strict = false ) { 440 442 $raw_username = $username; … … 451 453 } 452 454 453 455 /** 454 * Returns a string which has been sanitized. 456 * Returns a string which has been sanitized. 455 457 * 456 * Specifically, HTML and PHP tags are stripped. Further actions can be added via the 457 * plugin API. If $title is empty and $fallback_title is set, the latter will be used. 458 * Specifically, HTML and PHP tags are stripped. Further actions can be added 459 * via the plugin API. If $title is empty and $fallback_title is set, the latter 460 * will be used. 458 461 * 459 462 * @since 1.0.0 460 463 * 461 * @param string $title The string to be sanitized. 462 * @param string $fallback_title Optional. A title to use if $title is empty. 463 * @return string The sanitized string. 464 * @param string $title The string to be sanitized. 465 * @param string $fallback_title Optional. A title to use if $title is empty. 466 * @return string The sanitized string. 464 467 */ 465 468 function sanitize_title($title, $fallback_title = '') { 466 469 $title = strip_tags($title); … … 473 476 } 474 477 475 478 /** 476 * Replaces the string with safe characters. Whitespace becomes a dash. 479 * Replaces the string with safe characters. Whitespace becomes a dash. 477 480 * 478 * Limits the output to alphanumeric characters, underscore (_) and dash (-). 481 * Limits the output to alphanumeric characters, underscore (_) and dash (-). 479 482 * 480 483 * @since 1.2.0 481 484 * 482 * @param string $title The title to be sanitized 483 * @return string The sanitized title 485 * @param string $title The title to be sanitized. 486 * @return string The sanitized title. 484 487 */ 485 488 function sanitize_title_with_dashes($title) { 486 489 $title = strip_tags($title); … … 510 513 } 511 514 512 515 /** 513 * Ensures a string is a valid SQL order by clause. 516 * Ensures a string is a valid SQL order by clause. 514 517 * 515 * Accepts one or more columns, with or without ASC/DESC, and also accepts RAND() 518 * Accepts one or more columns, with or without ASC/DESC, and also accepts 519 * RAND(). 516 520 * 517 521 * @since 2.5.1 518 522 * 519 * @param string $orderby Order by string to be checked 523 * @param string $orderby Order by string to be checked. 520 524 * @return string|false Returns the order by clause if it is a match, false otherwise. 521 525 */ 522 526 function sanitize_sql_orderby( $orderby ){ … … 527 531 } 528 532 529 533 /** 530 * Converts a number of characters from a string 534 * Converts a number of characters from a string. 531 535 * 532 * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are converted into correct 533 * XHTML and Unicode characters are converted to the valid range. 536 * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are 537 * converted into correct XHTML and Unicode characters are converted to the 538 * valid range. 534 539 * 535 540 * @since 0.71 536 541 * 537 * @param string $content String of characters to be converted 538 * @param string $deprecated Not used 542 * @param string $content String of characters to be converted. 543 * @param string $deprecated Not used. 539 544 * @return string Converted string. 540 545 */ 541 546 function convert_chars($content, $deprecated = '') { … … 593 598 } 594 599 595 600 /** 596 * Fixes javascript bugs in browsers. 601 * Fixes javascript bugs in browsers. 597 602 * 598 603 * {@internal Missing Long Description}} 599 604 * … … 601 606 * @uses $is_macIE 602 607 * @uses $is_winIE 603 608 * 604 * @param string $text Text to be made safe 605 * @return string Fixed text 609 * @param string $text Text to be made safe. 610 * @return string Fixed text. 606 611 */ 607 612 function funky_javascript_fix($text) { 608 613 // Fixes for browsers' javascript bugs … … 648 653 * Added Cleaning Hooks 649 654 * 1.0 First Version 650 655 * 651 * @param string $text Text to be balanced 652 * @return string Balanced text 656 * @param string $text Text to be balanced. 657 * @return string Balanced text. 653 658 */ 654 659 function force_balance_tags( $text ) { 655 660 $tagstack = array(); $stacksize = 0; $tagqueue = ''; $newtext = ''; … … 751 756 } 752 757 753 758 /** 754 * Acts on text which is about to be edited 759 * Acts on text which is about to be edited. 755 760 * 756 * Unless $richedit is set, it is simply a holder for the 'format_to_edit' filter. If $richedit757 * is set true htmlspecialchars() will be run on the content, converting special characters to758 * HTMl entities.761 * Unless $richedit is set, it is simply a holder for the 'format_to_edit' 762 * filter. If $richedit is set true htmlspecialchars() will be run on the 763 * content, converting special characters to HTMl entities. 759 764 * 760 765 * @since 0.71 761 766 * 762 * @param string $content The text about to be edited. 763 * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false. 764 * @return string The text after the filter (and possibly htmlspecialchars()) has been run. 767 * @param string $content The text about to be edited. 768 * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false. 769 * @return string The text after the filter (and possibly htmlspecialchars()) has been run. 765 770 */ 766 771 function format_to_edit($content, $richedit = false) { 767 772 $content = apply_filters('format_to_edit', $content); … … 778 783 * @since 0.71 779 784 * 780 785 * @param string $content The text to pass through the filter. 781 * @return string Text returned from the 'format_to_post' filter. 786 * @return string Text returned from the 'format_to_post' filter. 782 787 */ 783 788 function format_to_post($content) { 784 789 $content = apply_filters('format_to_post', $content); … … 786 791 } 787 792 788 793 /** 789 * Add leading zeros when necessary 794 * Add leading zeros when necessary. 790 795 * 791 796 * {@internal Missing Long Description}} 792 797 * … … 817 822 } 818 823 819 824 /** 820 * Appends a trailing slash 825 * Appends a trailing slash. 821 826 * 822 * Will remove trailing slash if it exists already before adding 823 * a trailing slash. This prevents double slashing a string or 824 * path. 827 * Will remove trailing slash if it exists already before adding a trailing 828 * slash. This prevents double slashing a string or path. 825 829 * 826 * The primary use of this is for paths and thus should be used 827 * for paths. It is not restricted to paths and offers no specific 828 * path support. 830 * The primary use of this is for paths and thus should be used for paths. It is 831 * not restricted to paths and offers no specific path support. 829 832 * 830 833 * @since 1.2.0 831 * @uses untrailingslashit() Unslashes string if it was slashed already 834 * @uses untrailingslashit() Unslashes string if it was slashed already. 832 835 * 833 * @param string $string What to add the trailing slash to 834 * @return string String with trailing slash added 836 * @param string $string What to add the trailing slash to. 837 * @return string String with trailing slash added. 835 838 */ 836 839 function trailingslashit($string) { 837 840 return untrailingslashit($string) . '/'; 838 841 } 839 842 840 843 /** 841 * Removes trailing slash if it exists 844 * Removes trailing slash if it exists. 842 845 * 843 * The primary use of this is for paths and thus should be used 844 * for paths. It is not restricted to paths and offers no specific 845 * path support. 846 * The primary use of this is for paths and thus should be used for paths. It is 847 * not restricted to paths and offers no specific path support. 846 848 * 847 849 * @since 2.2.0 848 850 * 849 * @param string $string What to remove the trailing slash from 850 * @return string String without the trailing slash 851 * @param string $string What to remove the trailing slash from. 852 * @return string String without the trailing slash. 851 853 */ 852 854 function untrailingslashit($string) { 853 855 return rtrim($string, '/'); 854 856 } 855 857 856 858 /** 857 * addslashes_gpc() - {@internal Missing Short Description}}859 * Adds slashes to escape strings. 858 860 * 859 * {@internal Missing Long Description}} 861 * Slashes will first be removed if magic_quotes_gpc is set, 862 * see {@link http://www.php.net/magic_quotes} for more details. 860 863 * 861 864 * @since 0.71 862 865 * 863 * @param unknown_type $gpc864 * @return unknown866 * @param string $gpc The string returned from HTTP request data. 867 * @return string Returns a string escaped with slashes. 865 868 */ 866 869 function addslashes_gpc($gpc) { 867 870 global $wpdb; … … 874 877 } 875 878 876 879 /** 877 * stripslashes_deep() - {@internal Missing Short Description}}880 * Navigates through an array and removes slashes from the values. 878 881 * 879 * {@internal Missing Long Description}} 882 * If an array is passed, the array_map() function causes a callback to 883 * pass the value back to the function. The slashes from this value will 884 * removed. 880 885 * 881 886 * @since 2.0.0 882 887 * 883 * @param unknown_type $value884 * @return unknown888 * @param array|string $value The array or string to be striped. 889 * @return array|string Stripped array (or string in the callback). 885 890 */ 886 891 function stripslashes_deep($value) { 887 892 $value = is_array($value) ? … … 892 897 } 893 898 894 899 /** 895 * urlencode_deep() - {@internal Missing Short Description}}900 * Navigates through an array and encodes the values to be used in a URL. 896 901 * 897 * {@internal Missing Long Description}} 902 * Uses a callback to pass the value of the array back to the function as a 903 * string. 898 904 * 899 905 * @since 2.2.0 900 906 * 901 * @param unknown_type $value902 * @return unknown907 * @param array|string $value The array or string to be encoded. 908 * @return array|string $value The encoded array (or string from the callback). 903 909 */ 904 910 function urlencode_deep($value) { 905 911 $value = is_array($value) ? … … 942 948 * 943 949 * {@internal Missing Long Description}} 944 950 * 945 * @since 2.5 951 * @since 2.5.0 946 952 * @access private 947 953 * 948 954 * @param unknown_type $matches … … 967 973 * 968 974 * {@internal Missing Long Description}} 969 975 * 970 * @since 2.5 976 * @since 2.5.0 971 977 * @access private 972 978 * 973 979 * @param unknown_type $matches … … 993 999 * 994 1000 * {@internal Missing Long Description}} 995 1001 * 996 * @since 2.5 1002 * @since 2.5.0 997 1003 * @access private 998 1004 * 999 1005 * @param unknown_type $matches … … 1093 1099 } 1094 1100 1095 1101 /** 1096 * is_email() - {@internal Missing Short Description}}1102 * Checks to see if the text is a valid email address. 1097 1103 * 1098 1104 * {@internal Missing Long Description}} 1099 1105 * 1100 1106 * @since 0.71 1101 1107 * 1102 * @param unknown_type $user_email1103 * @return unknown1108 * @param string $user_email The email address to be checked. 1109 * @return bool Returns true if valid, otherwise false. 1104 1110 */ 1105 1111 function is_email($user_email) { 1106 1112 $chars = "/^([a-z0-9+_]|\\-|\\.)+@(([a-z0-9_]|\\-)+\\.)+[a-z]{2,6}\$/i"; … … 1138 1144 } 1139 1145 1140 1146 /** 1141 * get_gmt_from_date() - Give it a date, it will give you the same date as GMT1147 * Returns a date in the GMT equivalent. 1142 1148 * 1143 * {@internal Missing Long Description}} 1149 * Requires and returns a date in the Y-m-d H:i:s format. 1150 * Simply subtracts the value of gmt_offset. 1144 1151 * 1145 1152 * @since 1.2.0 1146 1153 * 1147 * @param unknown_type $string1148 * @return unknown1154 * @param string $string The date to be converted. 1155 * @return string GMT version of the date provided. 1149 1156 */ 1150 1157 function get_gmt_from_date($string) { 1151 // note: this only substracts $time_difference from the given date1152 1158 preg_match('#([0-9]{1,4})-([0-9]{1,2})-([0-9]{1,2}) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})#', $string, $matches); 1153 1159 $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 1154 1160 $string_gmt = gmdate('Y-m-d H:i:s', $string_time - get_option('gmt_offset') * 3600); … … 1156 1162 } 1157 1163 1158 1164 /** 1159 * get_date_from_gmt() - Give it a GMT date, it will give you the same date with $time_difference added1165 * Converts a GMT date into the correct format for the blog. 1160 1166 * 1161 * {@internal Missing Long Description}} 1167 * Requires and returns in the Y-m-d H:i:s format. Simply 1168 * adds the value of gmt_offset. 1162 1169 * 1163 1170 * @since 1.2.0 1164 1171 * 1165 * @param unknown_type $string1166 * @return unknown1172 * @param string $string The date to be converted. 1173 * @return string Formatted date relative to the GMT offset. 1167 1174 */ 1168 1175 function get_date_from_gmt($string) { 1169 // note: this only adds $time_difference to the given date1170 1176 preg_match('#([0-9]{1,4})-([0-9]{1,2})-([0-9]{1,2}) ([0-9]{1,2}):([0-9]{1,2}):([0-9]{1,2})#', $string, $matches); 1171 1177 $string_time = gmmktime($matches[4], $matches[5], $matches[6], $matches[2], $matches[3], $matches[1]); 1172 1178 $string_localtime = gmdate('Y-m-d H:i:s', $string_time + get_option('gmt_offset')*3600); … … 1174 1180 } 1175 1181 1176 1182 /** 1177 * iso8601_timezone_to_offset() - Computes an offset in seconds from an iso8601 timezone1183 * Computes an offset in seconds from an iso8601 timezone. 1178 1184 * 1179 1185 * {@internal Missing Long Description}} 1180 1186 * 1181 1187 * @since 1.5.0 1182 1188 * 1183 * @param unknown_type $timezone1184 * @return unknown1189 * @param string $timezone Either 'Z' for 0 offset or '±hhmm'. 1190 * @return int|float The offset in seconds. 1185 1191 */ 1186 1192 function iso8601_timezone_to_offset($timezone) { 1187 1193 // $timezone is either 'Z' or '[+|-]hhmm' … … 1197 1203 } 1198 1204 1199 1205 /** 1200 * iso8601_to_datetime() - Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt]1206 * Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt]. 1201 1207 * 1202 1208 * {@internal Missing Long Description}} 1203 1209 * 1204 1210 * @since 1.5.0 1205 1211 * 1206 * @param unknown_type $date_string1207 * @param unknown_type $timezone 1208 * @return unknown1212 * @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}. 1213 * @param unknown_type $timezone Optional. If set to GMT returns the time minus gmt_offset. Default USER. 1214 * @return string The date and time in MySQL DateTime format - Y-m-d H:i:s. 1209 1215 */ 1210 1216 function iso8601_to_datetime($date_string, $timezone = USER) { 1211 1217 if ($timezone == GMT) { … … 1229 1235 } 1230 1236 1231 1237 /** 1232 * Adds a element attributes to open links in new windows 1238 * Adds a element attributes to open links in new windows. 1233 1239 * 1234 * Comment text in popup windows should be filtered through this. Right 1235 * now it's a moderately dumb function, ideally it would detect whether 1236 * a target or rel attribute was already there and adjust its actions 1237 * accordingly. 1240 * Comment text in popup windows should be filtered through this. Right now it's 1241 * a moderately dumb function, ideally it would detect whether a target or rel 1242 * attribute was already there and adjust its actions accordingly. 1238 1243 * 1239 1244 * @since 0.71 1240 1245 * 1241 * @param string $text Content to replace links to open in a new window 1242 * @return string Content that has filtered links 1246 * @param string $text Content to replace links to open in a new window. 1247 * @return string Content that has filtered links. 1243 1248 */ 1244 1249 function popuplinks($text) { 1245 1250 $text = preg_replace('/<a (.+?)>/i', "<a $1 target='_blank' rel='external'>", $text); … … 1247 1252 } 1248 1253 1249 1254 /** 1250 * Strips out all characters that are not allowable in an email 1255 * Strips out all characters that are not allowable in an email. 1251 1256 * 1252 1257 * @since 1.5.0 1253 1258 * 1254 * @param string $email Email address to filter 1255 * @return string Filtered email address 1259 * @param string $email Email address to filter. 1260 * @return string Filtered email address. 1256 1261 */ 1257 1262 function sanitize_email($email) { 1258 1263 return preg_replace('/[^a-z0-9+_.@-]/i', '', $email); 1259 1264 } 1260 1265 1261 1266 /** 1262 * human_time_diff() - {@internal Missing Short Description}}1267 * Determines the difference between two timestamps. 1263 1268 * 1264 * {@internal Missing Long Description}} 1269 * The difference is returned in a human readable format such as 1270 * "1 hour", "5 mins", "2 days". 1265 1271 * 1266 1272 * @since 1.5.0 1267 1273 * 1268 * @param unknown_type $from1269 * @param unknown_type $to1270 * @return unknown1274 * @param int $from Unix timestamp from which the difference begins. 1275 * @param int $to Optional. Unix timestamp to end the time difference. Default becomes time() if not set. 1276 * @return string Human readable time difference. 1271 1277 */ 1272 1278 function human_time_diff( $from, $to = '' ) { 1273 1279 if ( empty($to) ) … … 1296 1302 } 1297 1303 1298 1304 /** 1299 * wp_trim_excerpt() - {@internal Missing Short Description}}1305 * Generates an excerpt from the content if needed. 1300 1306 * 1301 1307 * {@internal Missing Long Description}} 1302 1308 * 1303 1309 * @since 1.5.0 1304 1310 * 1305 * @param unknown_type $text1306 * @return unknown1311 * @param string $text The exerpt. If set to empty an excerpt is generated. 1312 * @return string The excerpt. 1307 1313 */ 1308 1314 function wp_trim_excerpt($text) { // Fakes an excerpt if needed 1309 1315 if ( '' == $text ) { … … 1326 1332 } 1327 1333 1328 1334 /** 1329 * ent2ncr() - {@internal Missing Short Description}}1335 * Converts named entities into numbered entities. 1330 1336 * 1331 1337 * {@internal Missing Long Description}} 1332 1338 * 1333 1339 * @since 1.5.1 1334 1340 * 1335 * @param unknown_type $text1336 * @return unknown1341 * @param string $text The text within which entities will be converted. 1342 * @return string Text with converted entities. 1337 1343 */ 1338 1344 function ent2ncr($text) { 1339 1345 $to_ncr = array( … … 1600 1606 } 1601 1607 1602 1608 /** 1603 * wp_richedit_pre() - {@internal Missing Short Description}}1609 * Formats text for the rich text editor and applies filter. 1604 1610 * 1605 * {@internal Missing Long Description}} 1611 * The filter 'richedit_pre' is applied here. If $text is empty 1612 * the filter will be applied to an empty string. 1606 1613 * 1607 1614 * @since 2.0.0 1608 1615 * 1609 * @param unknown_type $text1610 * @return unknown1616 * @param string $text The text to be formatted. 1617 * @return string The formatted text after filter is applied. 1611 1618 */ 1612 1619 function wp_richedit_pre($text) { 1613 1620 // Filtering a blank results in an annoying <br />\n … … 1620 1627 return apply_filters('richedit_pre', $output); 1621 1628 } 1622 1629 1630 /** 1631 * Formats text for the HTML editor and applies a filter. 1632 * 1633 * Unless $output is empty it will pass through htmlspecialchars 1634 * before the 'htmledit_pre' filter is applied. 1635 * 1636 * @since unknown 1637 * 1638 * @param string $output The text to be formatted. 1639 * @return string Formatted text after filter applied. 1640 */ 1623 1641 function wp_htmledit_pre($output) { 1624 1642 if ( !empty($output) ) 1625 1643 $output = htmlspecialchars($output, ENT_NOQUOTES); // convert only < > & … … 1628 1646 } 1629 1647 1630 1648 /** 1631 * clean_url() - {@internal Missing Short Description}}1649 * Checks and cleans a URL. 1632 1650 * 1633 * {@internal Missing Long Description}} 1651 * A number of characters are removed from the URL. If the URL is 1652 * for displaying (the default behaviour) amperstands are also replaced. 1653 * The 'clean_url' filter is applied to the returned cleaned URL. 1634 1654 * 1635 1655 * @since 1.2.0 1656 * @uses wp_kses_bad_protocol() To only permit protocols in the URL set 1657 * via $protocols or the common ones set in the function. 1636 1658 * 1637 * @param unknown_type $url 1638 * @param unknown_type $protocols 1639 * @param unknown_type $context 1640 * @return unknown 1659 * @param string $url The URL to be cleaned. 1660 * @param array $protocols Optional. An array of acceptable protocols. 1661 * Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' if not set. 1662 * @param string $context Optional. How the URL will be used. Default is 'display'. 1663 * @return string The cleaned $url after the 'cleaned_url' filter is applied. 1641 1664 */ 1642 1665 function clean_url( $url, $protocols = null, $context = 'display' ) { 1643 1666 $original_url = $url; … … 1655 1678 substr( $url, 0, 1 ) != '/' && !preg_match('/^[a-z0-9-]+?\.php/i', $url) ) 1656 1679 $url = 'http://' . $url; 1657 1680 1658 // Replace ampersands on y when displaying.1681 // Replace ampersands only when displaying. 1659 1682 if ( 'display' == $context ) 1660 1683 $url = preg_replace('/&([^#])(?![a-z]{2,8};)/', '&$1', $url); 1661 1684 … … 1668 1691 } 1669 1692 1670 1693 /** 1671 * sanitize_url() - {@internal Missing Short Description}}1694 * Performs clean_url() for database usage. 1672 1695 * 1673 * {@internal Missing Long Description}}1696 * @see clean_url() 1674 1697 * 1675 1698 * @since 2.3.1 1676 1699 * 1677 * @param unknown_type $url1678 * @param unknown_type $protocols1679 * @return unknown1700 * @param string $url The URL to be cleaned. 1701 * @param array $protocols An array of acceptable protocols. 1702 * @return string The cleaned URL. 1680 1703 */ 1681 1704 function sanitize_url( $url, $protocols = null ) { 1682 1705 return clean_url( $url, $protocols, 'db' ); 1683 1706 } 1684 1707 1685 1708 /** 1686 * Convert entities, while preserving already-encoded entities 1709 * Convert entities, while preserving already-encoded entities. 1687 1710 * 1688 1711 * {@internal Missing Long Description}} 1689 1712 * … … 1691 1714 * 1692 1715 * @since 1.2.2 1693 1716 * 1694 * @param unknown_type $myHTML1695 * @return unknown1717 * @param string $myHTML The text to be converted. 1718 * @return string Converted text. 1696 1719 */ 1697 1720 function htmlentities2($myHTML) { 1698 1721 $translation_table = get_html_translation_table( HTML_ENTITIES, ENT_QUOTES ); … … 1701 1724 } 1702 1725 1703 1726 /** 1704 * Escape single quotes, specialchar double quotes, and fix line endings 1727 * Escape single quotes, specialchar double quotes, and fix line endings. 1705 1728 * 1706 * {@internal Missing Long Description}}1729 * The filter 'js_escape' is also applied here. 1707 1730 * 1708 1731 * @since 2.0.4 1709 1732 * 1710 * @param string $text 1711 * @return unknown1733 * @param string $text The text to be escaped. 1734 * @return string Escaped text. 1712 1735 */ 1713 1736 function js_escape($text) { 1714 1737 $safe_text = wp_specialchars($text, 'double'); … … 1717 1740 return apply_filters('js_escape', $safe_text, $text); 1718 1741 } 1719 1742 1720 // Escaping for HTML attributes 1743 /** 1744 * Escaping for HTML attributes. 1745 * 1746 * @since unknown 1747 * 1748 * @param string $text 1749 * @return string 1750 */ 1721 1751 function attribute_escape($text) { 1722 1752 $safe_text = wp_specialchars($text, true); 1723 1753 return apply_filters('attribute_escape', $safe_text, $text); 1724 1754 } 1725 1755 1726 // Escape a HTML tag name 1756 /** 1757 * Escape a HTML tag name. 1758 * 1759 * @since unknown 1760 * 1761 * @param string $tag_name 1762 * @return string 1763 */ 1727 1764 function tag_escape($tag_name) { 1728 1765 $safe_tag = strtolower( preg_replace('[^a-zA-Z_:]', '', $tag_name) ); 1729 1766 return apply_filters('tag_escape', $safe_tag, $tag_name); 1730 1767 } 1731 1768 1732 1769 /** 1733 * Escapes text for SQL LIKE special characters % and _ 1770 * Escapes text for SQL LIKE special characters % and _. 1734 1771 * 1735 * @param string text the text to be escaped 1736 * @return string text, safe for inclusion in LIKE query 1772 * @since unknown 1773 * 1774 * @param string $text The text to be escaped. 1775 * @return string text, safe for inclusion in LIKE query. 1737 1776 */ 1738 1777 function like_escape($text) { 1739 1778 return str_replace(array("%", "_"), array("\\%", "\\_"), $text); 1740 1779 } 1741 1780 1781 /** 1782 * {@internal Missing Short Description}} 1783 * 1784 * @since unknown 1785 * 1786 * @param string $link 1787 * @return string 1788 */ 1742 1789 function wp_make_link_relative( $link ) { 1743 1790 return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link ); 1744 1791 } 1745 1792 1793 /** 1794 * Sanitises various option values based on the nature of the option. 1795 * 1796 * This is basically a switch statement which will pass $value through 1797 * a number of functions depending on the $option. 1798 * 1799 * @since 2.0.5 1800 * 1801 * @param string $option The name of the option. 1802 * @param string $value The unsanitised value. 1803 * @return string Sanitized value. 1804 */ 1746 1805 function sanitize_option($option, $value) { // Remember to call stripslashes! 1747 1806 1748 1807 switch ($option) { … … 1818 1877 } 1819 1878 1820 1879 /** 1821 * wp_parse_str() - {@internal Missing Short Description}}1880 * Parses a string into variables to be stored in an array. 1822 1881 * 1823 * {@internal Missing Long Description}} 1882 * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes 1883 * if {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on. 1824 1884 * 1825 1885 * @since 2.2.1 1826 * @uses apply_filters() 1886 * @uses apply_filters() for the 'wp_parse_str' filter. 1827 1887 * 1828 * @param string $string 1829 * @param array $array 1888 * @param string $string The string to be parsed. 1889 * @param array $array Variables will be stored in this array. 1830 1890 */ 1831 1891 function wp_parse_str( $string, &$array ) { 1832 1892 parse_str( $string, $array ); 1833 1893 if ( get_magic_quotes_gpc() ) 1834 $array = stripslashes_deep( $array ); // parse_str() adds slashes if magicquotes is on. See: http://php.net/parse_str1894 $array = stripslashes_deep( $array ); 1835 1895 $array = apply_filters( 'wp_parse_str', $array ); 1836 1896 } 1837 1897 1838 // Convert lone less than signs. KSES already converts lone greater than signs. 1898 /** 1899 * Convert lone less than signs. 1900 * 1901 * KSES already converts lone greater than signs. 1902 * 1903 * @uses wp_pre_kses_less_than_callback in the callback function. 1904 * @since unknown 1905 * 1906 * @param string $text Text to be converted. 1907 * @return string Converted text. 1908 */ 1839 1909 function wp_pre_kses_less_than( $text ) { 1840 1910 return preg_replace_callback('%<[^>]*?((?=<)|>|$)%', 'wp_pre_kses_less_than_callback', $text); 1841 1911 } 1842 1912 1913 /** 1914 * Callback function used by preg_replace. 1915 * 1916 * @since unknown 1917 * @uses wp_specialchars to format the $matches text. 1918 * 1919 * @param array $matches Populated by matches to preg_replace. 1920 * @return string The text returned after wp_specialchars if needed. 1921 */ 1843 1922 function wp_pre_kses_less_than_callback( $matches ) { 1844 1923 if ( false === strpos($matches[0], '>') ) 1845 1924 return wp_specialchars($matches[0]); … … 1847 1926 } 1848 1927 1849 1928 /** 1850 * wp_sprintf() - sprintf() with filters 1929 * WordPress implementation of PHP sprintf() with filters. 1930 * 1931 * @since unknown 1932 * @link http://www.php.net/sprintf 1933 * 1934 * @param string $pattern The string which formatted args are inserted. 1935 * @param mixed $args,... Arguments to be formatted into the $pattern string. 1936 * @return string The formatted string. 1851 1937 */ 1852 1938 function wp_sprintf( $pattern ) { 1853 1939 $args = func_get_args( ); … … 1902 1988 } 1903 1989 1904 1990 /** 1905 * wp_sprintf_l - List specifier %l for wp_sprintf1991 * List specifier %l for wp_sprintf. 1906 1992 * 1993 * @since unknown 1994 * 1907 1995 * @param unknown_type $pattern 1908 1996 * @param unknown_type $args 1909 1997 * @return unknown … … 1940 2028 } 1941 2029 1942 2030 /** 1943 * Safely extracts not more than the first $count characters from html string 2031 * Safely extracts not more than the first $count characters from html string. 1944 2032 * 1945 * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* be 1946 * counted as one character. For example & will be counted as 4, < as 3, etc. 2033 * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* 2034 * be counted as one character. For example & will be counted as 4, < as 2035 * 3, etc. 1947 2036 * 1948 * @param integer $str String to get the excerpt from 1949 * @param integer $count Maximum number of characters to take 1950 * @return string the excerpt2037 * @param integer $str String to get the excerpt from. 2038 * @param integer $count Maximum number of characters to take. 2039 * @return string The excerpt. 1951 2040 */ 1952 2041 function wp_html_excerpt( $str, $count ) { 1953 2042 $str = strip_tags( $str ); … … 1966 2055 * @package WordPress 1967 2056 * @since 2.7 1968 2057 * 1969 * @param string $content String to search for links in 1970 * @param string $base The base URL to prefix to links 2058 * @param string $content String to search for links in. 2059 * @param string $base The base URL to prefix to links. 1971 2060 * @param array $attrs The attributes which should be processed. 1972 * @ eaturn string The processed content.2061 * @return string The processed content. 1973 2062 */ 1974 2063 function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) { 1975 2064 $attrs = implode('|', (array)$attrs); … … 1985 2074 * @package WordPress 1986 2075 * @since 2.7 1987 2076 * 1988 * @internal 1989 * @param string $m The matched link 1990 * @param string $base The base URL to prefix to links 1991 * @eaturn string The processed link 2077 * @param string $m The matched link. 2078 * @param string $base The base URL to prefix to links. 2079 * @return string The processed link. 1992 2080 */ 1993 2081 function _links_add_base($m, $base) { 1994 2082 //1 = attribute name 2 = quotation mark 3 = URL … … 2009 2097 * @package WordPress 2010 2098 * @since 2.7 2011 2099 * 2012 * @param string $content String to search for links in 2013 * @param string $target The Target to add to the links 2100 * @param string $content String to search for links in. 2101 * @param string $target The Target to add to the links. 2014 2102 * @param array $tags An array of tags to apply to. 2015 * @ eaturn string The processed content.2103 * @return string The processed content. 2016 2104 */ 2017 2105 function links_add_target( $content, $target = '_blank', $tags = array('a') ) { 2018 2106 $tags = implode('|', (array)$tags); … … 2021 2109 $content); 2022 2110 } 2023 2111 /** 2024 * Callback to add a target attribute to all links in passed content 2112 * Callback to add a target attribute to all links in passed content. 2025 2113 * 2026 2114 * 2027 2115 * @package WordPress 2028 2116 * @since 2.7 2029 2117 * 2030 * @internal 2031 * @param string $m The matched link 2032 * @param string $target The Target to add to the links 2033 * @eaturn string The processed link. 2118 * @param string $m The matched link. 2119 * @param string $target The Target to add to the links. 2120 * @return string The processed link. 2034 2121 */ 2035 2122 function _links_add_target( $m, $target ) { 2036 2123 $tag = $m[1];
