WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/esc url

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).

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 appending protocol to the beginning of 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' if not set.
Default: null
$_context
(string) (optional) How the URL will be used. Default is 'display'.
Default: 'display'

Return Values

(string) 
The cleaned $url after the 'clean_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.

See also index of Function Reference and index of Template Tags.