esc_url
Checks and cleans a URL.
Description
A number of characters are removed from the URL. If the URL is for displaying (the default behaviour) ampersands are also replaced. The filter is applied to the returned cleaned URL.
Returns (string)
The cleaned $url after the {@see 'clean_url'} filter is applied.
Parameters (3)
- 0. $url (string)
- The URL to be cleaned.
- 1. $protocols — Optional. (constant) =>
null
- An array of acceptable protocols. Defaults to return value of
wp_allowed_protocols(…)
- 2. $context (string)
- Private. Use
esc_url_raw(…)
for database usage.
Usage
if ( !function_exists( 'esc_url' ) ) { require_once ABSPATH . WPINC . '/formatting.php'; } // The URL to be cleaned. $url = ''; // Optional. An array of acceptable protocols. // Defaults to return value of wp_allowed_protocols() $protocols = null; // Private. Use esc_url_raw() for database usage. $context = ''; // NOTICE! Understand what this does before running. $result = esc_url($url, $protocols, $context);
Defined (1)
The function is defined in the following location(s).
- /wp-includes/formatting.php
- function esc_url( $url, $protocols = null, $_context = 'display' ) {
- $original_url = $url;
- if ( '' == $url )
- return $url;
- $url = str_replace( ' ', '%20', $url );
- $url = preg_replace('|[^a-z0-9-~+_.?#=!&;, /:%@$\|*\'()\[\]\\x80-\\xff]|i', '', $url);
- if ( '' === $url ) {
- return $url;
- }
- if ( 0 !== stripos( $url, 'mailto:' ) ) {
- $strip = array('%0d', '%0a', '%0D', '%0A');
- $url = _deep_replace($strip, $url);
- }
- $url = str_replace(';//', '://', $url);
- /** If the URL doesn't appear to contain a scheme, we
- * presume it needs http:// prepended (unless a relative
- * link starting with /, # or ? or a php file).
- */
- if ( strpos($url, ':') === false && ! in_array( $url[0], array( '/', '#', '?' ) ) &&
- ! preg_match('/^[a-z0-9-]+?\.php/i', $url) )
- $url = 'http://' . $url;
- // Replace ampersands and single quotes only when displaying.
- if ( 'display' == $_context ) {
- $url = wp_kses_normalize_entities( $url );
- $url = str_replace( '&', '&', $url );
- $url = str_replace( "'", ''', $url );
- }
- if ( ( false !== strpos( $url, '[' ) ) || ( false !== strpos( $url, ']' ) ) ) {
- $parsed = wp_parse_url( $url );
- $front = '';
- if ( isset( $parsed['scheme'] ) ) {
- $front .= $parsed['scheme'] . '://';
- } elseif ( '/' === $url[0] ) {
- $front .= '//';
- }
- if ( isset( $parsed['user'] ) ) {
- $front .= $parsed['user'];
- }
- if ( isset( $parsed['pass'] ) ) {
- $front .= ':' . $parsed['pass'];
- }
- if ( isset( $parsed['user'] ) || isset( $parsed['pass'] ) ) {
- $front .= '@';
- }
- if ( isset( $parsed['host'] ) ) {
- $front .= $parsed['host'];
- }
- if ( isset( $parsed['port'] ) ) {
- $front .= ':' . $parsed['port'];
- }
- $end_dirty = str_replace( $front, '', $url );
- $end_clean = str_replace( array( '[', ']' ), array( '%5B', '%5D' ), $end_dirty );
- $url = str_replace( $end_dirty, $end_clean, $url );
- }
- if ( '/' === $url[0] ) {
- $good_protocol_url = $url;
- } else {
- if ( ! is_array( $protocols ) )
- $protocols = wp_allowed_protocols();
- $good_protocol_url = wp_kses_bad_protocol( $url, $protocols );
- if ( strtolower( $good_protocol_url ) != strtolower( $url ) )
- return '';
- }
- /**
- * Filters a string cleaned and escaped for output as a URL.
- *
- * @since 2.3.0
- *
- * @param string $good_protocol_url The cleaned URL to be returned.
- * @param string $original_url The URL prior to cleaning.
- * @param string $_context If 'display', replace ampersands and single quotes only.
- */
- return apply_filters( 'clean_url', $good_protocol_url, $original_url, $_context );
- }