WordPress at a glance

esc_url() WP 2.8.0

Cleans the URL for use in text, changes the wrong and removes the dangerous characters.

esc_url() unlike esc_url_raw() prepares a string for displaying.

Always use esc_url() when you need to clean URLs, for example, for text or HTML attributes.

The function creates characters in the form of HTML entities, use it when creating (X)HTML or XML documents. For example, it changes the ampersand &` and quotation mark'` for their HTML entities&#038,&#039`.

Avoid URLs without protocol. Every URL must begin with http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed or telnet

Is the basis for: esc_url_raw()
✈ 1 time = 0.000052s = very fast | 50000 times = 0.31s = very fast | PHP 7.1.2, WP 4.7.3
Hooks in function
Return

String. The cleaned $url after the 'clean_url' filter is applied.

Usage

esc_url( $url, $protocols, $_context );
$url(string) (required)
The URL to be cleaned.
$protocols(array)
An array of acceptable protocols. By default: http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, telnet.
Default: null
$_context(string)
How the URL will be used. May be display or '' (empty sting). If display then ampersand ( & ) and quotes (') will be replaced with HTML entities.
Default: 'display'

Examples

#1 Basic Example

$url = "http;//example.com/link?var='some&";

echo esc_url( $url );
// output: http://example.com/link?var=&#039some&#038

#2 Relative URL

echo esc_url( '/foo' ); //> /foo

Code of esc url: wp-includes/formatting.php WP 5.2.1

<?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( '&amp;', '&#038;', $url );
		$url = str_replace( "'", '&#039;', $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 );
}

Related Functions

From tag: esc_ (clean validate sanitize)

More from category: Sanitizing, Escaping

vladlu 100
Editors: kama 100
No comments
    Hello, !     Log In . Register