WordPress.org

Languages: English • Reference/esc url 日本語 (Add your language)

Description

Always use esc_url when sanitizing URLs (in text nodes, attribute nodes or anywhere else). Rejects URLs that do not have one of the provided whitelisted protocols (defaulting to http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, and telnet), eliminates invalid characters, and removes dangerous characters. This function encodes characters as HTML entities: use it when generating an (X)HTML or XML document. Encodes ampersands (&) and single quotes (') as numeric entity references (&#038, &#039).

If the URL appears to be an absolute link that does not contain a scheme, prepends http://. Please note that relative urls (/my-url/parameter2/), as well as anchors (#myanchor) and parameter items (?myparam=yes) are also allowed and filtered as a special case, without prepending the default protocol to the filtered url.

Replaces the deprecated clean_url().

Usage

<?php esc_url( $url, $protocols, $_context ); ?>

Parameters

$url

(string) (required) The URL to be cleaned.

Default: None

$protocols

(array) (optional) An array of acceptable protocols. Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'svn', 'tel', 'fax', 'xmpp' if not set.

Default: null

$_context

(string) (optional) How the URL will be used. Default is 'display' which makes the value safe for display purposes. No other contexts have special processing in the core code.

Default: 'display'

Return Values

(string) 

The cleaned $url after the 'esc_url' filter is applied. An empty string is returned if $url specifies a protocol other than those in $protocols, or if $url contains an empty string.

Examples

Adding a link to home

As featured in the Twenty Thirteen theme, although simplified for the sake of the example

<a href="<?php echo esc_url( home_url( '/' ) ); ?>">Home</a>

Notes

Changelog

• Since: 2.8

Source File

esc_url() is located in wp-includes/formatting.php.

Related

See: Data Validation article for an in-depth discussion of input and output sanitization.

• esc_html()
  • esc_html__()
  • esc_html_e()
• esc_attr()
  • esc_attr__()
  • esc_attr_e()
• esc_js()
• esc_sql()
• esc_textarea()
• esc_url()
  • esc_url_raw()
  • urlencode()
  • urlencode_deep()