Make WordPress Core


Ignore:
Timestamp:
04/28/2018 01:57:32 PM (6 years ago)
Author:
johnbillion
Message:

Formatting: Begin the process of improving the docs for KSES related functions.

See #33801

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/kses.php

    r42880 r43016  
    3232
    3333/**
    34  * You can override this in a plugin.
    35  *
    36  * The {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context.
    37  *
    38  * `CUSTOM_TAGS` is not recommended and should be considered deprecated.
     34 * Specifies the default allowable HTML tags.
     35 *
     36 * Using `CUSTOM_TAGS` is not recommended and should be considered deprecated. The
     37 * {@see 'wp_kses_allowed_html'} filter is more powerful and supplies context.
    3938 *
    4039 * @see wp_kses_allowed_html()
    41  *
    4240 * @since 1.2.0
     41 *
     42 * @var array[]|bool Array of default allowable HTML tags, or false to use the defaults.
    4343 */
    4444if ( ! defined( 'CUSTOM_TAGS' ) ) {
     
    5252if ( ! CUSTOM_TAGS ) {
    5353    /**
    54      * Kses global for default allowable HTML tags.
     54     * KSES global for default allowable HTML tags.
    5555     *
    56      * Can be override by using CUSTOM_TAGS constant.
     56     * Can be overridden with the `CUSTOM_TAGS` constant.
    5757     *
    58      * @global array $allowedposttags
     58     * @var array[] $allowedposttags Array of default allowable HTML tags.
    5959     * @since 2.0.0
    6060     */
     
    417417
    418418    /**
    419      * Kses allowed HTML elements.
    420      *
    421      * @global array $allowedtags
     419     * @var array[] $allowedtags Array of KSES allowed HTML elements.
    422420     * @since 1.0.0
    423421     */
     
    452450    );
    453451
     452    /**
     453     * @var string[] $allowedentitynames Array of KSES allowed HTML entitity names.
     454     * @since 1.0.0
     455     */
    454456    $allowedentitynames = array(
    455457        'nbsp',
     
    715717
    716718/**
    717  * Filters content and keeps only allowable HTML elements.
     719 * Filters text content and strips out disallowed HTML.
    718720 *
    719721 * This function makes sure that only the allowed HTML element names, attribute
    720  * names and attribute values plus only sane HTML entities will occur in
    721  * $string. You have to remove any slashes from PHP's magic quotes before you
    722  * call this function.
    723  *
    724  * The default allowed protocols are 'http', 'https', 'ftp', 'mailto', 'news',
    725  * 'irc', 'gopher', 'nntp', 'feed', 'telnet, 'mms', 'rtsp' and 'svn'. This
    726  * covers all common link protocols, except for 'javascript' which should not
    727  * be allowed for untrusted users.
     722 * names, attribute values, and HTML entities will occur in the given text string.
     723 *
     724 * This function expects unslashed data.
     725 *
     726 * @see wp_kses_post() for specifically filtering post content and fields.
     727 * @see wp_allowed_protocols() for the default allowed protocols in link URLs.
    728728 *
    729729 * @since 1.0.0
    730730 *
    731  * @param string $string            Content to filter through kses
    732  * @param array  $allowed_html      List of allowed HTML elements
    733  * @param array  $allowed_protocols Optional. Allowed protocol in links.
    734  * @return string Filtered content with only allowed HTML elements
     731 * @param string         $string            Text content to filter.
     732 * @param array[]|string $allowed_html      An array of allowed HTML elements and attributes, or a
     733 *                                          context name such as 'post'.
     734 * @param string[]       $allowed_protocols Array of allowed URL protocols.
     735 * @return string Filtered content containing only the allowed HTML.
    735736 */
    736737function wp_kses( $string, $allowed_html, $allowed_protocols = array() ) {
     
    740741    $string = wp_kses_no_null( $string, array( 'slash_zero' => 'keep' ) );
    741742    $string = wp_kses_normalize_entities( $string );
    742     $string = wp_kses_hook( $string, $allowed_html, $allowed_protocols ); // WP changed the order of these funcs and added args to wp_kses_hook
     743    $string = wp_kses_hook( $string, $allowed_html, $allowed_protocols );
    743744    return wp_kses_split( $string, $allowed_html, $allowed_protocols );
    744745}
    745746
    746747/**
    747  * Filters one attribute only and ensures its value is allowed.
    748  *
    749  * This function has the advantage of being more secure than esc_attr() and can
    750  * escape data in some situations where wp_kses() must strip the whole attribute.
     748 * Filters one HTML attribute and ensures its value is allowed.
     749 *
     750 * This function can escape data in some situations where `wp_kses()` must strip the whole attribute.
    751751 *
    752752 * @since 4.2.3
    753753 *
    754  * @param string $string The 'whole' attribute, including name and value.
    755  * @param string $element The element name to which the attribute belongs.
     754 * @param string $string  The 'whole' attribute, including name and value.
     755 * @param string $element The HTML element name to which the attribute belongs.
    756756 * @return string Filtered attribute.
    757757 */
     
    819819
    820820/**
    821  * Return a list of allowed tags and attributes for a given context.
     821 * Returns an array of allowed HTML tags and attributes for a given context.
    822822 *
    823823 * @since 3.5.0
     
    827827 * @global array $allowedentitynames
    828828 *
    829  * @param string|array $context The context for which to retrieve tags.
    830  *                              Allowed values are post, strip, data, entities, or
    831  *                              the name of a field filter such as pre_user_description.
    832  * @return array List of allowed tags and their allowed attributes.
     829 * @param string|array $context The context for which to retrieve tags. Allowed values are 'post',
     830 *                              'strip', 'data', 'entities', or the name of a field filter such as
     831 *                              'pre_user_description'.
     832 * @return array Array of allowed HTML tags and their allowed attributes.
    833833 */
    834834function wp_kses_allowed_html( $context = '' ) {
     
    837837    if ( is_array( $context ) ) {
    838838        /**
    839          * Filters HTML elements allowed for a given context.
     839         * Filters the HTML that is allowed for a given context.
    840840         *
    841841         * @since 3.5.0
    842842         *
    843          * @param array  $context      Context to judge allowed tags by.
    844          * @param string $context_type Context type (explicit).
     843         * @param array[]|string $context      Context to judge allowed tags by.
     844         * @param string         $context_type Context name.
    845845         */
    846846        return apply_filters( 'wp_kses_allowed_html', $context, 'explicit' );
     
    875875
    876876/**
    877  * You add any kses hooks here.
    878  *
    879  * There is currently only one kses WordPress hook, {@see 'pre_kses'}, and it is called here.
     877 * You add any KSES hooks here.
     878 *
     879 * There is currently only one KSES WordPress hook, {@see 'pre_kses'}, and it is called here.
    880880 * All parameters are passed to the hooks and expected to receive a string.
    881881 *
    882882 * @since 1.0.0
    883883 *
    884  * @param string $string            Content to filter through kses
    885  * @param array  $allowed_html      List of allowed HTML elements
    886  * @param array  $allowed_protocols Allowed protocol in links
     884 * @param string          $string            Content to filter through KSES.
     885 * @param array[]|string  $allowed_html      List of allowed HTML elements.
     886 * @param string[]        $allowed_protocols Array of allowed URL protocols.
    887887 * @return string Filtered content through {@see 'pre_kses'} hook.
    888888 */
     
    893893     * @since 2.3.0
    894894     *
    895      * @param string $string            Content to run through kses.
    896      * @param array  $allowed_html      Allowed HTML elements.
    897      * @param array  $allowed_protocols Allowed protocol in links.
     895     * @param string          $string            Content to run through KSES.
     896     * @param array[]|string  $allowed_html      Allowed HTML elements.
     897     * @param string[]        $allowed_protocols Array of allowed URL protocols.
    898898     */
    899899    return apply_filters( 'pre_kses', $string, $allowed_html, $allowed_protocols );
     
    901901
    902902/**
    903  * This function returns kses' version number.
     903 * Returns the version number of KSES.
    904904 *
    905905 * @since 1.0.0
    906906 *
    907  * @return string KSES Version Number
     907 * @return string KSES version number.
    908908 */
    909909function wp_kses_version() {
     
    914914 * Searches for HTML tags, no matter how malformed.
    915915 *
    916  * It also matches stray ">" characters.
     916 * It also matches stray `>` characters.
    917917 *
    918918 * @since 1.0.0
     
    921921 * @global array $pass_allowed_protocols
    922922 *
    923  * @param string $string            Content to filter
    924  * @param array  $allowed_html      Allowed HTML elements
    925  * @param array  $allowed_protocols Allowed protocols to keep
     923 * @param string   $string            Content to filter.
     924 * @param array    $allowed_html      Allowed HTML elements.
     925 * @param string[] $allowed_protocols Array of allowed URL protocols.
    926926 * @return string Content with fixed HTML tags
    927927 */
     
    934934
    935935/**
    936  * Callback for wp_kses_split.
     936 * Callback for `wp_kses_split()`.
    937937 *
    938938 * @since 3.1.0
    939939 * @access private
     940 * @ignore
    940941 *
    941942 * @global array $pass_allowed_html
     
    950951
    951952/**
    952  * Callback for wp_kses_split for fixing malformed HTML tags.
     953 * Callback for `wp_kses_split()` for fixing malformed HTML tags.
    953954 *
    954955 * This function does a lot of work. It rejects some very malformed things like
    955  * <:::>. It returns an empty string, if the element isn't allowed (look ma, no
    956  * strip_tags()!). Otherwise it splits the tag into an element and an attribute
     956 * `<:::>`. It returns an empty string, if the element isn't allowed (look ma, no
     957 * `strip_tags()`!). Otherwise it splits the tag into an element and an attribute
    957958 * list.
    958959 *
     
    962963 *
    963964 * @access private
     965 * @ignore
    964966 * @since 1.0.0
    965967 *
    966  * @param string $string            Content to filter
    967  * @param array  $allowed_html      Allowed HTML elements
    968  * @param array  $allowed_protocols Allowed protocols to keep
     968 * @param string   $string            Content to filter.
     969 * @param array    $allowed_html      Allowed HTML elements.
     970 * @param string[] $allowed_protocols Array of allowed URL protocols.
    969971 * @return string Fixed HTML element
    970972 */
     
    10221024 * Removes all attributes, if none are allowed for this element.
    10231025 *
    1024  * If some are allowed it calls wp_kses_hair() to split them further, and then
    1025  * it builds up new HTML code from the data that kses_hair() returns. It also
    1026  * removes "<" and ">" characters, if there are any left. One more thing it does
     1026 * If some are allowed it calls `wp_kses_hair()` to split them further, and then
     1027 * it builds up new HTML code from the data that `kses_hair()` returns. It also
     1028 * removes `<` and `>` characters, if there are any left. One more thing it does
    10271029 * is to check if the tag has a closing XHTML slash, and if it does, it puts one
    10281030 * in the returned code as well.
     
    10301032 * @since 1.0.0
    10311033 *
    1032  * @param string $element           HTML element/tag
    1033  * @param string $attr              HTML attributes from HTML element to closing HTML element tag
    1034  * @param array  $allowed_html      Allowed HTML elements
    1035  * @param array  $allowed_protocols Allowed protocols to keep
    1036  * @return string Sanitized HTML element
     1034 * @param string   $element           HTML element/tag.
     1035 * @param string   $attr              HTML attributes from HTML element to closing HTML element tag.
     1036 * @param array    $allowed_html      Allowed HTML elements.
     1037 * @param string[] $allowed_protocols Array of allowed URL protocols.
     1038 * @return string Sanitized HTML element.
    10371039 */
    10381040function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) {
     
    10721074
    10731075/**
    1074  * Determine whether an attribute is allowed.
     1076 * Determines whether an attribute is allowed.
    10751077 *
    10761078 * @since 4.2.3
    10771079 *
    1078  * @param string $name The attribute name. Returns empty string when not allowed.
    1079  * @param string $value The attribute value. Returns a filtered value.
    1080  * @param string $whole The name=value input. Returns filtered input.
    1081  * @param string $vless 'y' when attribute like "enabled", otherwise 'n'.
    1082  * @param string $element The name of the element to which this attribute belongs.
    1083  * @param array $allowed_html The full list of allowed elements and attributes.
    1084  * @return bool Is the attribute allowed?
     1080 * @param string $name         The attribute name. Passed by reference. Returns empty string when not allowed.
     1081 * @param string $value        The attribute value. Passed by reference. Returns a filtered value.
     1082 * @param string $whole        The `name=value` input. Passed by reference. Returns filtered input.
     1083 * @param string $vless        Whether the attribute is valueless. Use 'y' or 'n'.
     1084 * @param string $element      The name of the element to which this attribute belongs.
     1085 * @param array  $allowed_html The full list of allowed elements and attributes.
     1086 * @return bool Whether or not the attribute is allowed.
    10851087 */
    10861088function wp_kses_attr_check( &$name, &$value, &$whole, $vless, $element, $allowed_html ) {
     
    11271129 * conform to W3C's HTML specification. It will also remove bad URL protocols
    11281130 * from attribute values. It also reduces duplicate attributes by using the
    1129  * attribute defined first (foo='bar' foo='baz' will result in foo='bar').
     1131 * attribute defined first (`foo='bar' foo='baz'` will result in `foo='bar'`).
    11301132 *
    11311133 * @since 1.0.0
    11321134 *
    1133  * @param string $attr              Attribute list from HTML element to closing HTML element tag
    1134  * @param array  $allowed_protocols Allowed protocols to keep
    1135  * @return array List of attributes after parsing
     1135 * @param string   $attr              Attribute list from HTML element to closing HTML element tag.
     1136 * @param string[] $allowed_protocols Array of allowed URL protocols.
     1137 * @return array[] Array of attribute information after parsing.
    11361138 */
    11371139function wp_kses_hair( $attr, $allowed_protocols ) {
     
    12721274 * Does not modify input.  May return "evil" output.
    12731275 *
    1274  * Based on wp_kses_split2() and wp_kses_attr()
     1276 * Based on `wp_kses_split2()` and `wp_kses_attr()`.
    12751277 *
    12761278 * @since 4.2.3
    12771279 *
    1278  * @param string $element HTML element/tag
    1279  * @return array|bool List of attributes found in $element. Returns false on failure.
     1280 * @param string $element HTML element.
     1281 * @return array|bool List of attributes found in the element. Returns false on failure.
    12801282 */
    12811283function wp_kses_attr_parse( $element ) {
     
    13231325 * In case of unexpected input, returns false instead of stripping things.
    13241326 *
    1325  * Based on wp_kses_hair() but does not return a multi-dimensional array.
     1327 * Based on `wp_kses_hair()` but does not return a multi-dimensional array.
    13261328 *
    13271329 * @since 4.2.3
    13281330 *
    1329  * @param string $attr Attribute list from HTML element to closing HTML element tag
     1331 * @param string $attr Attribute list from HTML element to closing HTML element tag.
    13301332 * @return array|bool List of attributes found in $attr. Returns false on failure.
    13311333 */
     
    13751377 * Performs different checks for attribute values.
    13761378 *
    1377  * The currently implemented checks are "maxlen", "minlen", "maxval", "minval"
     1379 * The currently implemented checks are "maxlen", "minlen", "maxval", "minval",
    13781380 * and "valueless".
    13791381 *
    13801382 * @since 1.0.0
    13811383 *
    1382  * @param string $value      Attribute value
    1383  * @param string $vless      Whether the value is valueless. Use 'y' or 'n'
     1384 * @param string $value      Attribute value.
     1385 * @param string $vless      Whether the attribute is valueless. Use 'y' or 'n'.
    13841386 * @param string $checkname  What $checkvalue is checking for.
    1385  * @param mixed  $checkvalue What constraint the value should pass
    1386  * @return bool Whether check passes
     1387 * @param mixed  $checkvalue What constraint the value should pass.
     1388 * @return bool Whether check passes.
    13871389 */
    13881390function wp_kses_check_attr_val( $value, $vless, $checkname, $checkvalue ) {
     
    14381440        case 'valueless':
    14391441            // The valueless check makes sure if the attribute has a value
    1440             // (like <a href="blah">) or not (<option selected>). If the given value
     1442            // (like `<a href="blah">`) or not (`<option selected>`). If the given value
    14411443            // is a "y" or a "Y", the attribute must not have a value.
    1442             // If the given value is an "n" or an "N", the attribute must have one.
     1444            // If the given value is an "n" or an "N", the attribute must have a value.
    14431445
    14441446            if ( strtolower( $checkvalue ) != $vless ) {
     
    14521454
    14531455/**
    1454  * Sanitize string from bad protocols.
    1455  *
    1456  * This function removes all non-allowed protocols from the beginning of
    1457  * $string. It ignores whitespace and the case of the letters, and it does
    1458  * understand HTML entities. It does its work in a while loop, so it won't be
    1459  * fooled by a string like "javascript:javascript:alert(57)".
     1456 * Sanitizes a string and removed disallowed URL protocols.
     1457 *
     1458 * This function removes all non-allowed protocols from the beginning of the
     1459 * string. It ignores whitespace and the case of the letters, and it does
     1460 * understand HTML entities. It does its work recursively, so it won't be
     1461 * fooled by a string like `javascript:javascript:alert(57)`.
    14601462 *
    14611463 * @since 1.0.0
    14621464 *
    1463  * @param string $string            Content to filter bad protocols from
    1464  * @param array  $allowed_protocols Allowed protocols to keep
    1465  * @return string Filtered content
     1465 * @param string   $string            Content to filter bad protocols from.
     1466 * @param string[] $allowed_protocols Array of allowed URL protocols.
     1467 * @return string Filtered content.
    14661468 */
    14671469function wp_kses_bad_protocol( $string, $allowed_protocols ) {
     
    14821484
    14831485/**
    1484  * Removes any invalid control characters in $string.
    1485  *
    1486  * Also removes any instance of the '\0' string.
     1486 * Removes any invalid control characters in a text string.
     1487 *
     1488 * Also removes any instance of the `\0` string.
    14871489 *
    14881490 * @since 1.0.0
    14891491 *
    1490  * @param string $string
    1491  * @param array $options Set 'slash_zero' => 'keep' when '\0' is allowed. Default is 'remove'.
    1492  * @return string
     1492 * @param string $string  Content to filter null characters from.
     1493 * @param array  $options Set 'slash_zero' => 'keep' when '\0' is allowed. Default is 'remove'.
     1494 * @return string Filtered content.
    14931495 */
    14941496function wp_kses_no_null( $string, $options = null ) {
     
    15081510 * Strips slashes from in front of quotes.
    15091511 *
    1510  * This function changes the character sequence \" to just ". It leaves all
    1511  * other slashes alone. It's really weird, but the quoting from
    1512  * preg_replace(//e) seems to require this.
     1512 * This function changes the character sequence `\"` to just `"`. It leaves all other
     1513 * slashes alone. The quoting from `preg_replace(//e)` requires this.
    15131514 *
    15141515 * @since 1.0.0
    15151516 *
    1516  * @param string $string String to strip slashes
    1517  * @return string Fixed string with quoted slashes
     1517 * @param string $string String to strip slashes from.
     1518 * @return string Fixed string with quoted slashes.
    15181519 */
    15191520function wp_kses_stripslashes( $string ) {
     
    15221523
    15231524/**
    1524  * Goes through an array and changes the keys to all lower case.
     1525 * Converts the keys of an array to lowercase.
    15251526 *
    15261527 * @since 1.0.0
    15271528 *
    1528  * @param array $inarray Unfiltered array
    1529  * @return array Fixed array with all lowercase keys
     1529 * @param array $inarray Unfiltered array.
     1530 * @return array Fixed array with all lowercase keys.
    15301531 */
    15311532function wp_kses_array_lc( $inarray ) {
     
    15391540            $outkey2                         = strtolower( $inkey2 );
    15401541            $outarray[ $outkey ][ $outkey2 ] = $inval2;
    1541         } // foreach $inval
    1542     } // foreach $inarray
     1542        }
     1543    }
    15431544
    15441545    return $outarray;
     
    15461547
    15471548/**
    1548  * Handles parsing errors in wp_kses_hair().
     1549 * Handles parsing errors in `wp_kses_hair()`.
    15491550 *
    15501551 * The general plan is to remove everything to and including some whitespace,
     
    15631564 * Sanitizes content from bad protocols and other characters.
    15641565 *
    1565  * This function searches for URL protocols at the beginning of $string, while
     1566 * This function searches for URL protocols at the beginning of the string, while
    15661567 * handling whitespace and HTML entities.
    15671568 *
    15681569 * @since 1.0.0
    15691570 *
    1570  * @param string $string            Content to check for bad protocols
    1571  * @param string $allowed_protocols Allowed protocols
    1572  * @return string Sanitized content
     1571 * @param string   $string            Content to check for bad protocols.
     1572 * @param string[] $allowed_protocols Array of allowed URL protocols.
     1573 * @return string Sanitized content.
    15731574 */
    15741575function wp_kses_bad_protocol_once( $string, $allowed_protocols, $count = 1 ) {
     
    15931594
    15941595/**
    1595  * Callback for wp_kses_bad_protocol_once() regular expression.
     1596 * Callback for `wp_kses_bad_protocol_once()` regular expression.
    15961597 *
    15971598 * This function processes URL protocols, checks to see if they're in the
     
    15991600 *
    16001601 * @access private
     1602 * @ignore
    16011603 * @since 1.0.0
    16021604 *
    1603  * @param string $string            URI scheme to check against the whitelist
    1604  * @param string $allowed_protocols Allowed protocols
    1605  * @return string Sanitized content
     1605 * @param string   $string            URI scheme to check against the whitelist.
     1606 * @param string[] $allowed_protocols Array of allowed URL protocols.
     1607 * @return string Sanitized content.
    16061608 */
    16071609function wp_kses_bad_protocol_once2( $string, $allowed_protocols ) {
     
    16341636 * @since 1.0.0
    16351637 *
    1636  * @param string $string Content to normalize entities
    1637  * @return string Content with normalized entities
     1638 * @param string $string Content to normalize entities.
     1639 * @return string Content with normalized entities.
    16381640 */
    16391641function wp_kses_normalize_entities( $string ) {
     
    16501652
    16511653/**
    1652  * Callback for wp_kses_normalize_entities() regular expression.
     1654 * Callback for `wp_kses_normalize_entities()` regular expression.
    16531655 *
    16541656 * This function only accepts valid named entity references, which are finite,
     
    16591661 * @global array $allowedentitynames
    16601662 *
    1661  * @param array $matches preg_replace_callback() matches array
    1662  * @return string Correctly encoded entity
     1663 * @param array $matches preg_replace_callback() matches array.
     1664 * @return string Correctly encoded entity.
    16631665 */
    16641666function wp_kses_named_entities( $matches ) {
     
    16741676
    16751677/**
    1676  * Callback for wp_kses_normalize_entities() regular expression.
    1677  *
    1678  * This function helps wp_kses_normalize_entities() to only accept 16-bit
     1678 * Callback for `wp_kses_normalize_entities()` regular expression.
     1679 *
     1680 * This function helps `wp_kses_normalize_entities()` to only accept 16-bit
    16791681 * values and nothing more for `&#number;` entities.
    16801682 *
    16811683 * @access private
     1684 * @ignore
    16821685 * @since 1.0.0
    16831686 *
    1684  * @param array $matches preg_replace_callback() matches array
    1685  * @return string Correctly encoded entity
     1687 * @param array $matches `preg_replace_callback()` matches array.
     1688 * @return string Correctly encoded entity.
    16861689 */
    16871690function wp_kses_normalize_entities2( $matches ) {
     
    17021705
    17031706/**
    1704  * Callback for wp_kses_normalize_entities() for regular expression.
    1705  *
    1706  * This function helps wp_kses_normalize_entities() to only accept valid Unicode
     1707 * Callback for `wp_kses_normalize_entities()` for regular expression.
     1708 *
     1709 * This function helps `wp_kses_normalize_entities()` to only accept valid Unicode
    17071710 * numeric entities in hex form.
    17081711 *
    17091712 * @since 2.7.0
    17101713 * @access private
    1711  *
    1712  * @param array $matches preg_replace_callback() matches array
    1713  * @return string Correctly encoded entity
     1714 * @ignore
     1715 *
     1716 * @param array $matches `preg_replace_callback()` matches array.
     1717 * @return string Correctly encoded entity.
    17141718 */
    17151719function wp_kses_normalize_entities3( $matches ) {
     
    17231727
    17241728/**
    1725  * Helper function to determine if a Unicode value is valid.
     1729 * Determines if a Unicode codepoint is valid.
    17261730 *
    17271731 * @since 2.7.0
    17281732 *
    1729  * @param int $i Unicode value
    1730  * @return bool True if the value was a valid Unicode number
     1733 * @param int $i Unicode codepoint.
     1734 * @return bool Whether or not the codepoint is a valid Unicode codepoint.
    17311735 */
    17321736function valid_unicode( $i ) {
     
    17381742
    17391743/**
    1740  * Convert all entities to their character counterparts.
     1744 * Converts all numeric HTML entities to their named counterparts.
    17411745 *
    17421746 * This function decodes numeric HTML entities (`&#65;` and `&#x41;`).
    1743  * It doesn't do anything with other entities like &auml;, but we don't
     1747 * It doesn't do anything with named entities like `&auml;`, but we don't
    17441748 * need them in the URL protocol whitelisting system anyway.
    17451749 *
    17461750 * @since 1.0.0
    17471751 *
    1748  * @param string $string Content to change entities
    1749  * @return string Content after decoded entities
     1752 * @param string $string Content to change entities.
     1753 * @return string Content after decoded entities.
    17501754 */
    17511755function wp_kses_decode_entities( $string ) {
     
    17571761
    17581762/**
    1759  * Regex callback for wp_kses_decode_entities()
     1763 * Regex callback for `wp_kses_decode_entities()`.
    17601764 *
    17611765 * @since 2.9.0
     1766 * @access private
     1767 * @ignore
    17621768 *
    17631769 * @param array $match preg match
     
    17691775
    17701776/**
    1771  * Regex callback for wp_kses_decode_entities()
     1777 * Regex callback for `wp_kses_decode_entities()`.
    17721778 *
    17731779 * @since 2.9.0
     1780 * @access private
     1781 * @ignore
    17741782 *
    17751783 * @param array $match preg match
     
    17811789
    17821790/**
    1783  * Sanitize content with allowed HTML Kses rules.
     1791 * Sanitize content with allowed HTML KSES rules.
     1792 *
     1793 * This function expects slashed data.
    17841794 *
    17851795 * @since 1.0.0
    17861796 *
    1787  * @param string $data Content to filter, expected to be escaped with slashes
    1788  * @return string Filtered content
     1797 * @param string $data Content to filter, expected to be escaped with slashes.
     1798 * @return string Filtered content.
    17891799 */
    17901800function wp_filter_kses( $data ) {
     
    17931803
    17941804/**
    1795  * Sanitize content with allowed HTML Kses rules.
     1805 * Sanitize content with allowed HTML KSES rules.
     1806 *
     1807 * This function expects unslashed data.
    17961808 *
    17971809 * @since 2.9.0
    17981810 *
    1799  * @param string $data Content to filter, expected to not be escaped
    1800  * @return string Filtered content
     1811 * @param string $data Content to filter, expected to not be escaped.
     1812 * @return string Filtered content.
    18011813 */
    18021814function wp_kses_data( $data ) {
     
    18051817
    18061818/**
    1807  * Sanitize content for allowed HTML tags for post content.
    1808  *
    1809  * Post content refers to the page contents of the 'post' type and not $_POST
     1819 * Sanitizes content for allowed HTML tags for post content.
     1820 *
     1821 * Post content refers to the page contents of the 'post' type and not `$_POST`
    18101822 * data from forms.
    18111823 *
     1824 * This function expects slashed data.
     1825 *
    18121826 * @since 2.0.0
    18131827 *
    1814  * @param string $data Post content to filter, expected to be escaped with slashes
     1828 * @param string $data Post content to filter, expected to be escaped with slashes.
    18151829 * @return string Filtered post content with allowed HTML tags and attributes intact.
    18161830 */
     
    18201834
    18211835/**
    1822  * Sanitize content for allowed HTML tags for post content.
    1823  *
    1824  * Post content refers to the page contents of the 'post' type and not $_POST
     1836 * Sanitizes content for allowed HTML tags for post content.
     1837 *
     1838 * Post content refers to the page contents of the 'post' type and not `$_POST`
    18251839 * data from forms.
    18261840 *
     1841 * This function expects unslashed data.
     1842 *
    18271843 * @since 2.9.0
    18281844 *
    1829  * @param string $data Post content to filter
     1845 * @param string $data Post content to filter.
    18301846 * @return string Filtered post content with allowed HTML tags and attributes intact.
    18311847 */
     
    18501866
    18511867/**
    1852  * Strips all of the HTML in the content.
     1868 * Strips all HTML from a text string.
     1869 *
     1870 * This function expects slashed data.
    18531871 *
    18541872 * @since 2.1.0
    18551873 *
    1856  * @param string $data Content to strip all HTML from
    1857  * @return string Filtered content without any HTML
     1874 * @param string $data Content to strip all HTML from.
     1875 * @return string Filtered content without any HTML.
    18581876 */
    18591877function wp_filter_nohtml_kses( $data ) {
     
    18621880
    18631881/**
    1864  * Adds all Kses input form content filters.
    1865  *
    1866  * All hooks have default priority. The wp_filter_kses() function is added to
     1882 * Adds all KSES input form content filters.
     1883 *
     1884 * All hooks have default priority. The `wp_filter_kses()` function is added to
    18671885 * the 'pre_comment_content' and 'title_save_pre' hooks.
    18681886 *
    1869  * The wp_filter_post_kses() function is added to the 'content_save_pre',
     1887 * The `wp_filter_post_kses()` function is added to the 'content_save_pre',
    18701888 * 'excerpt_save_pre', and 'content_filtered_save_pre' hooks.
    18711889 *
     
    18901908
    18911909/**
    1892  * Removes all Kses input form content filters.
    1893  *
    1894  * A quick procedural method to removing all of the filters that kses uses for
     1910 * Removes all KSES input form content filters.
     1911 *
     1912 * A quick procedural method to removing all of the filters that KSES uses for
    18951913 * content in WordPress Loop.
    18961914 *
    1897  * Does not remove the kses_init() function from {@see 'init'} hook (priority is
    1898  * default). Also does not remove kses_init() function from {@see 'set_current_user'}
     1915 * Does not remove the `kses_init()` function from {@see 'init'} hook (priority is
     1916 * default). Also does not remove `kses_init()` function from {@see 'set_current_user'}
    18991917 * hook (priority is also default).
    19001918 *
     
    19161934
    19171935/**
    1918  * Sets up most of the Kses filters for input form content.
    1919  *
    1920  * If you remove the kses_init() function from {@see 'init'} hook and
    1921  * {@see 'set_current_user'} (priority is default), then none of the Kses filter hooks
    1922  * will be added.
    1923  *
    1924  * First removes all of the Kses filters in case the current user does not need
    1925  * to have Kses filter the content. If the user does not have unfiltered_html
    1926  * capability, then Kses filters are added.
     1936 * Sets up most of the KSES filters for input form content.
     1937 *
     1938 * First removes all of the KSES filters in case the current user does not need
     1939 * to have KSES filter the content. If the user does not have `unfiltered_html`
     1940 * capability, then KSES filters are added.
    19271941 *
    19281942 * @since 2.0.0
     
    19371951
    19381952/**
    1939  * Inline CSS filter
     1953 * Filters an inline style attribute and removes disallowed rules.
    19401954 *
    19411955 * @since 2.8.1
     
    19431957 * @param string $css        A string of CSS rules.
    19441958 * @param string $deprecated Not used.
    1945  * @return string            Filtered string of CSS rules.
     1959 * @return string Filtered string of CSS rules.
    19461960 */
    19471961function safecss_filter_attr( $css, $deprecated = '' ) {
     
    19671981     * @since 5.0.0 Added support for `text-transform`.
    19681982     *
    1969      * @param array $attr List of allowed CSS attributes.
     1983     * @param string[] $attr Array of allowed CSS attributes.
    19701984     */
    19711985    $allowed_attr = apply_filters(
     
    20782092 * @since 3.5.0
    20792093 * @access private
     2094 * @ignore
    20802095 *
    20812096 * @param array $value An array of attributes.
Note: See TracChangeset for help on using the changeset viewer.