Documentation

EscapeOutputSniff extends AbstractFunctionRestrictionsSniff
in package

WPCS

WordPressCodingStandards

uses EscapingFunctionsTrait, PrintingFunctionsTrait

Verifies that all outputted strings are escaped.

Properties

$customAutoEscapedFunctions : array<string|int, string>: Custom list of functions whose return values are pre-escaped for display.
$customEscapingFunctions : array<string|int, string>: Custom list of functions which escape values for display.
$customPrintingFunctions : array<string|int, string>: Custom list of functions which print output incorporating the passed values.
$exclude : array<string|int, mixed>: Exclude groups.
$unittest_groups : array<string|int, mixed>: Groups of function data to check against.
$excluded_groups : array<string|int, mixed>: Cache for the excluded groups information.
$groups : array<string|int, mixed>: Cache for the group information.
$phpcsFile : File: The current file being sniffed.
$regex_pattern : string: Regex pattern with placeholder for the function names.
$tokens : array<string|int, mixed>: The list of tokens in the current file being sniffed.
$unsafePrintingFunctions : array<string, array<string|int, mixed>>: Printing functions that incorporate unsafe values.
$addedCustomEscapingFunctions : array<string, array<string|int, string>>: Cache of previously added custom functions.
$addedCustomPrintingFunctions : array<string|int, string>: Cache of previously added custom functions.
$allAutoEscapedFunctions : array<string, bool>: Combined list of WP native and custom auto-escaping functions.
$allEscapingFunctions : array<string, bool>: Combined list of WP native and custom escaping functions.
$allPrintingFunctions : array<string, bool>: Combined list of WP/PHP native and custom printing functions.
$autoEscapedFunctions : array<string, bool>: Functions whose output is automatically escaped for display.
$escapingFunctions : array<string, bool>: Functions that escape values for display.
$printingFunctions : array<string, bool>: Functions which print output incorporating the values passed to them.
$safe_components : array<string|int, string|int>: List of tokens which can be considered as safe when directly part of the output.
$safe_php_constants : array<string, bool>: List of names of the native PHP constants which can be considered safe.
$target_keywords : array<string|int, string|int>: List of keyword tokens this sniff listens for, which can also be used as an inline expression.

Methods

check_for_matches() : int|void: Verify if the current token is one of the targetted functions.
get_printing_functions() : array<string, bool>: Retrieve a list of all known printing functions.
getGroups() : array<string|int, mixed>: Groups of functions this sniff is looking for.
is_auto_escaped_function() : bool: Check if a particular function is regarded as an auto-escaped function.
is_escaping_function() : bool: Check if a particular function is regarded as an escaping function.
is_printing_function() : bool: Check if a particular function is regarded as a printing function.
is_targetted_token() : bool: Verify is the current token is a function call.
process() : int|void: Set sniff properties and hand off to child class for processing of the token.
process_matched_token() : int|void: Process a matched function call token.
process_token() : int|void: Processes this test, when one of its tokens is encountered.
register() : string|array<string|int, int>: Returns an array of tokens this test wants to listen for.
check_code_is_escaped() : int: Check whether each relevant part of an arbitrary group of token is output escaped.
prepare_name_for_regex() : string: Prepare the function name for use in a regular expression.
setup_groups() : bool: Set up the regular expressions for each group.
find_long_ternary() : int|false: Check whether there is a ternary token at the right nesting level in an arbitrary set of tokens.
walk_match_expression() : int|false: Examine a match expression and only check for escaping in the "returned" parts of the match expression.

$customAutoEscapedFunctions

Custom list of functions whose return values are pre-escaped for display.


        public
            array<string|int, string>
    $customAutoEscapedFunctions
     = array()

$customEscapingFunctions

Custom list of functions which escape values for display.


        public
            array<string|int, string>
    $customEscapingFunctions
     = array()

$customPrintingFunctions

Custom list of functions which print output incorporating the passed values.


        public
            array<string|int, string>
    $customPrintingFunctions
     = array()

$exclude

Exclude groups.


        public
            array<string|int, mixed>
    $exclude
     = array()

Example: 'switch_to_blog,user_meta'

$unittest_groups

Groups of function data to check against.


        public
        static    array<string|int, mixed>
    $unittest_groups
     = array()

Don't use this in extended classes, override getGroups() instead. This is only used for Unit tests.

$excluded_groups

Cache for the excluded groups information.


        protected
            array<string|int, mixed>
    $excluded_groups
     = array()

$groups

Cache for the group information.


        protected
            array<string|int, mixed>
    $groups
     = array()

$phpcsFile

The current file being sniffed.


        protected
            File
    $phpcsFile

$regex_pattern

Regex pattern with placeholder for the function names.


        protected
            string
    $regex_pattern
     = '`^(?:%s)$`i'

$tokens

The list of tokens in the current file being sniffed.


        protected
            array<string|int, mixed>
    $tokens

$unsafePrintingFunctions

Printing functions that incorporate unsafe values.


        protected
            array<string, array<string|int, mixed>>
    $unsafePrintingFunctions
     = array('_e' => array('alternative' => 'esc_html_e() or esc_attr_e()', 'params' => array(1 => 'text')), '_ex' => array('alternative' => 'echo esc_html_x() or echo esc_attr_x()', 'params' => array(1 => 'text')))

$addedCustomEscapingFunctions

Cache of previously added custom functions.


        private
            array<string, array<string|int, string>>
    $addedCustomEscapingFunctions
     = array('escape' => array(), 'autoescape' => array())

Prevents having to do the same merges over and over again.

$addedCustomPrintingFunctions

Cache of previously added custom functions.


        private
            array<string|int, string>
    $addedCustomPrintingFunctions
     = array()

Prevents having to do the same merges over and over again.

$allAutoEscapedFunctions

Combined list of WP native and custom auto-escaping functions.


        private
            array<string, bool>
    $allAutoEscapedFunctions
     = array()

$allEscapingFunctions

Combined list of WP native and custom escaping functions.


        private
            array<string, bool>
    $allEscapingFunctions
     = array()

$allPrintingFunctions

Combined list of WP/PHP native and custom printing functions.


        private
            array<string, bool>
    $allPrintingFunctions
     = array()

$autoEscapedFunctions

Functions whose output is automatically escaped for display.


        private
            array<string, bool>
    $autoEscapedFunctions
     = array('allowed_tags' => true, 'bloginfo' => true, 'body_class' => true, 'calendar_week_mod' => true, 'category_description' => true, 'checked' => true, 'comment_class' => true, 'count' => true, 'disabled' => true, 'do_shortcode' => true, 'do_shortcode_tag' => true, 'get_archives_link' => true, 'get_attachment_link' => true, 'get_avatar' => true, 'get_bookmark_field' => true, 'get_calendar' => true, 'get_comment_author_link' => true, 'get_current_blog_id' => true, 'get_delete_post_link' => true, 'get_search_form' => true, 'get_search_query' => true, 'get_the_author_link' => true, 'get_the_author' => true, 'get_the_date' => true, 'get_the_ID' => true, 'get_the_post_thumbnail' => true, 'get_the_term_list' => true, 'post_type_archive_title' => true, 'readonly' => true, 'selected' => true, 'single_cat_title' => true, 'single_month_title' => true, 'single_post_title' => true, 'single_tag_title' => true, 'single_term_title' => true, 'tag_description' => true, 'term_description' => true, 'the_author' => true, 'the_date' => true, 'the_title_attribute' => true, 'walk_nav_menu_tree' => true, 'wp_dropdown_categories' => true, 'wp_dropdown_users' => true, 'wp_generate_tag_cloud' => true, 'wp_get_archives' => true, 'wp_get_attachment_image' => true, 'wp_get_attachment_link' => true, 'wp_link_pages' => true, 'wp_list_authors' => true, 'wp_list_bookmarks' => true, 'wp_list_categories' => true, 'wp_list_comments' => true, 'wp_login_form' => true, 'wp_loginout' => true, 'wp_nav_menu' => true, 'wp_readonly' => true, 'wp_register' => true, 'wp_tag_cloud' => true, 'wp_timezone_choice' => true, 'wp_title' => true)

$escapingFunctions

Functions that escape values for display.


        private
            array<string, bool>
    $escapingFunctions
     = array('absint' => true, 'esc_attr__' => true, 'esc_attr_e' => true, 'esc_attr_x' => true, 'esc_attr' => true, 'esc_html__' => true, 'esc_html_e' => true, 'esc_html_x' => true, 'esc_html' => true, 'esc_js' => true, 'esc_sql' => true, 'esc_textarea' => true, 'esc_url_raw' => true, 'esc_url' => true, 'esc_xml' => true, 'filter_input' => true, 'filter_var' => true, 'floatval' => true, 'highlight_string' => true, 'intval' => true, 'json_encode' => true, 'like_escape' => true, 'number_format' => true, 'rawurlencode' => true, 'sanitize_hex_color' => true, 'sanitize_hex_color_no_hash' => true, 'sanitize_html_class' => true, 'sanitize_key' => true, 'sanitize_locale_name' => true, 'sanitize_user_field' => true, 'tag_escape' => true, 'urlencode_deep' => true, 'urlencode' => true, 'wp_json_encode' => true, 'wp_kses_allowed_html' => true, 'wp_kses_data' => true, 'wp_kses_one_attr' => true, 'wp_kses_post' => true, 'wp_kses' => true)

$printingFunctions

Functions which print output incorporating the values passed to them.


        private
            array<string, bool>
    $printingFunctions
     = array('_deprecated_argument' => true, '_deprecated_constructor' => true, '_deprecated_file' => true, '_deprecated_function' => true, '_deprecated_hook' => true, '_doing_it_wrong' => true, '_e' => true, '_ex' => true, 'printf' => true, 'trigger_error' => true, 'user_error' => true, 'vprintf' => true, 'wp_die' => true, 'wp_dropdown_pages' => true)

$safe_components

List of tokens which can be considered as safe when directly part of the output.


        private
            array<string|int, string|int>
    $safe_components
     = array(\T_LNUMBER => \T_LNUMBER, \T_DNUMBER => \T_DNUMBER, \T_TRUE => \T_TRUE, \T_FALSE => \T_FALSE, \T_NULL => \T_NULL, \T_CONSTANT_ENCAPSED_STRING => \T_CONSTANT_ENCAPSED_STRING, \T_START_NOWDOC => \T_START_NOWDOC, \T_NOWDOC => \T_NOWDOC, \T_END_NOWDOC => \T_END_NOWDOC, \T_BOOLEAN_NOT => \T_BOOLEAN_NOT)

This list is enhanced with additional tokens in the register() method.

$safe_php_constants

List of names of the native PHP constants which can be considered safe.


        private
            array<string, bool>
    $safe_php_constants
     = array(
    'PHP_EOL' => true,
    // String.
    'PHP_VERSION' => true,
    // Integer.
    'PHP_MAJOR_VERSION' => true,
    // Integer.
    'PHP_MINOR_VERSION' => true,
    // Integer.
    'PHP_RELEASE_VERSION' => true,
    // Integer.
    'PHP_VERSION_ID' => true,
    // Integer.
    'PHP_EXTRA_VERSION' => true,
    // String.
    'PHP_DEBUG' => true,
)

$target_keywords

List of keyword tokens this sniff listens for, which can also be used as an inline expression.


        private
            array<string|int, string|int>
    $target_keywords
     = array(\T_EXIT => \T_EXIT, \T_PRINT => \T_PRINT, \T_THROW => \T_THROW)

check_for_matches()

Verify if the current token is one of the targetted functions.


    public
                    check_for_matches(int $stackPtr) : int|void

Parameters

$stackPtr : int: The position of the current token in the stack.

Return values

int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

get_printing_functions()

Retrieve a list of all known printing functions.


    public
        final            get_printing_functions() : array<string, bool>

Return values

array<string, bool>

getGroups()

Groups of functions this sniff is looking for.


    public
                    getGroups() : array<string|int, mixed>

Return values

array<string|int, mixed>

is_auto_escaped_function()

Check if a particular function is regarded as an auto-escaped function.


    public
        final            is_auto_escaped_function(string $functionName) : bool

Parameters

$functionName : string: The name of the function to check.

Return values

bool

is_escaping_function()

Check if a particular function is regarded as an escaping function.


    public
        final            is_escaping_function(string $functionName) : bool

Parameters

$functionName : string: The name of the function to check.

Return values

bool

is_printing_function()

Check if a particular function is regarded as a printing function.


    public
        final            is_printing_function(string $functionName) : bool

Parameters

$functionName : string: The name of the function to check.

Return values

bool

is_targetted_token()

Verify is the current token is a function call.


    public
                    is_targetted_token(int $stackPtr) : bool

Parameters

$stackPtr : int: The position of the current token in the stack.

Return values

bool

process()

Set sniff properties and hand off to child class for processing of the token.


    public
                    process(File $phpcsFile, int $stackPtr) : int|void

Parameters

$phpcsFile : File: The file being scanned.
$stackPtr : int: The position of the current token in the stack passed in $tokens.

Return values

int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_matched_token()

Process a matched function call token.


    public
                    process_matched_token(int $stackPtr, string $group_name, string $matched_content) : int|void

Parameters

$stackPtr : int: The position of the current token in the stack.
$group_name : string: The name of the group which was matched.
$matched_content : string: The token content (function name) which was matched in lowercase.

Return values

int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

process_token()

Processes this test, when one of its tokens is encountered.


    public
                    process_token(int $stackPtr) : int|void

Parameters

$stackPtr : int: The position of the current token in the stack.

Return values

int|void —

Integer stack pointer to skip forward or void to continue normal file processing.

register()

Returns an array of tokens this test wants to listen for.


    public
                    register() : string|array<string|int, int>

Return values

string|array<string|int, int>

check_code_is_escaped()

Check whether each relevant part of an arbitrary group of token is output escaped.


    protected
                    check_code_is_escaped(int $start, int $end[, string $code = 'OutputNotEscaped' ]) : int

Parameters

$start : int: The position to start checking from.
$end : int: The position to stop the check at.
$code : string = 'OutputNotEscaped': Code to use for the PHPCS error.

Return values

int —

Integer stack pointer to skip forward.

prepare_name_for_regex()

Prepare the function name for use in a regular expression.


    protected
                    prepare_name_for_regex(string $function_name) : string

The getGroups() method allows for providing function names with a wildcard * to target a group of functions. This prepare routine takes that into account while still safely escaping the function name for use in a regular expression.

Parameters

$function_name : string: Function name.

Return values

string —

Regex escaped function name.

setup_groups()

Set up the regular expressions for each group.


    protected
                    setup_groups(string $key) : bool

Parameters

$key : string: The group array index key where the input for the regular expression can be found.

Return values

bool —

True if the groups were setup. False if not.

find_long_ternary()

Check whether there is a ternary token at the right nesting level in an arbitrary set of tokens.


    private
                    find_long_ternary(int $start, int $end) : int|false

Parameters

$start : int: The position to start checking from.
$end : int: The position to stop the check at.

Return values

int|false —

Stack pointer to the ternary or FALSE if no ternary was found or if this is a short ternary.

walk_match_expression()

Examine a match expression and only check for escaping in the "returned" parts of the match expression.


    private
                    walk_match_expression(int $stackPtr, string $code) : int|false

Parameters

$stackPtr : int: Pointer to a T_MATCH token.
$code : string: Code to use for the PHPCS error.

Return values

int|false —

Stack pointer to skip to or FALSE if the match expression contained a parse error.

EscapeOutputSniff extends AbstractFunctionRestrictionsSniff in package WPCS WordPressCodingStandards uses EscapingFunctionsTrait, PrintingFunctionsTrait

Tags

Table of Contents

Properties

Methods

Properties

$customAutoEscapedFunctions

Tags

$customEscapingFunctions

Tags

$customPrintingFunctions

Tags

$exclude

Tags

$unittest_groups

Tags

$excluded_groups

Tags

$groups

Tags

$phpcsFile

Tags

$regex_pattern

Tags

$tokens

Tags

$unsafePrintingFunctions

Tags

$addedCustomEscapingFunctions

Tags

$addedCustomPrintingFunctions

Tags

$allAutoEscapedFunctions

Tags

$allEscapingFunctions

Tags

$allPrintingFunctions

Tags

$autoEscapedFunctions

Tags

$escapingFunctions

Tags

$printingFunctions

Tags

$safe_components

Tags

$safe_php_constants

Tags

$target_keywords

Tags

Methods

check_for_matches()

Parameters

Tags

Return values

get_printing_functions()

Tags

Return values

getGroups()

Tags

Return values

is_auto_escaped_function()

Parameters

Tags

Return values

is_escaping_function()

Parameters

Tags

Return values

is_printing_function()

Parameters

Tags

Return values

is_targetted_token()

Parameters

Tags

Return values

process()

Parameters

Tags

EscapeOutputSniff extends AbstractFunctionRestrictionsSniff
in package

WPCS

WordPressCodingStandards

uses EscapingFunctionsTrait, PrintingFunctionsTrait