Helper Functions

Function clean_html

function clean_html( string $text, array $allowedtags = [], string $context = '' ) : string

When translating strings in WordPress, the most common functions to use are __() (translate and return) or _e() (translate and output). Where possible, these need to be escaped too, to ensure that translations don't accidentally break your output. For this reason, esc_html_e(), esc_attr_e(), etc. are offered by WordPress as convenience functions.

However, this falls down when you need to have HTML in the translation.

This function provides a nice, easy, quick way to perform sanitization on translated strings. Rather than requiring you to work with the internals of kses, it's much closer to functions like esc_html().

Parameters

  • $text (string)(required) Content to escape
  • $allowedtags (array) Allowed tags, see examples.
  • $context (string) kses context to use ( see wp_kses_allowed_html)

Return

  • (string) Escaped string for output into HTML context.

Example usage

For the most part, clean_html() can be used in exactly the same way developers are used to using other escaping functions.

To allow a tags only in a translated string:

$text = clean_html(
    sprintf(
        __( 'This is some text <a href="%1$s">with a link</a>'),
        'http://example.com/'
    ),
    'a'
);

It works with multiple elements as well, using a comma-separated string or list of elements:

$text = clean_html(
    sprintf(
        __( 'This is <code>some</code> text <a href="%1$s">with a link</a>'),
        'http://example.com/'
    ),
    'a, code' // or [ 'a', 'code' ]
);

If you need custom attributes, you can use kses-style attribute specifiers. These can be mixed too:

$text = clean_html(
    sprintf(
        __( 'This is <span class="x">some</span> text <a href="%1$s">with a link</a>'),
        'http://example.com/'
    ),
    [
        'a',
        'span' => [
            'class' => true,
        ],
    ]
);

Function print_clean_html

print_clean_html( string $text, array $allowedtags = [], string $context = '' ) : void

Equivalent of clean_html() which echoes output directly rather than returning.

Parameters

  • $text (string)(required) Content to escape
  • $allowedtags (array) Allowed tags, see examples under clean_html.
  • $context (string) kses context to use ( see wp_kses_allowed_html)

Return

  • (void) Escaped string is echoed to the browser directly.

Function wp_hash_password

wp_hash_password( string $password ) : bool|string

Hash password using bcrypt. This function calls password_hash instead of WordPress' default password hashing function.

The wp_hash_password_options filter is available to set the options that password_hash can accept.

Parameters

  • $password (string)(required) Plaintext password

Return

  • (bool|string)

Function wp_check_password

wp_check_password( string $password, string $hash, int|string $userId ) : mixed|void

Check if user has entered correct password, supports bcrypt and pHash.

At its core, this function just calls password_verify instead of the default. However, it also checks if a user's password was previously hashed with the old MD5-based hash function and re-hashes it with bcrypt. This means you can still install this plugin on an existing site and everything will work seamlessly.

The check_password filter is available just like the default WP function.

Parameters

  • $password (string)(required) Plaintext password
  • $hash (string)(required) Hash of password
  • $userId (int|string) ID of user to whom the password belongs

Return

  • (mixed|void)

Function wp_set_password

wp_set_password( string $password, int $userId ) : bool|string

Set password using bcrypt.

This function is included here verbatim but with the addition of returning the hash. The default WP function does not return anything which means you end up hashing it twice for no reason.

Parameters

  • $password (string)(required) Plaintext password
  • $userId (int)(required) ID of user to whom password belongs

Return

  • (bool|string)