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

Возвращает

String. The cleaned URL after the 'clean_url' filter is applied.

Basis of: esc_url_raw()
1 time = 0.000052s = very fast | 50000 times = 0.31s = very fast | PHP 7.1.2, WP 4.7.3
Hooks from the function

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

Список изменений

С версии 2.8.0 Введена.

Code of esc_url() WP 5.5.1

wp-includes/formatting.php
<?php
function esc_url( $url, $protocols = null, $_context = 'display' ) {
	$original_url = $url;

	if ( '' === $url ) {
		return $url;
	}

	$url = str_replace( ' ', '%20', ltrim( $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 it's a relative link
	 * starting with /, # or ?, or a PHP file).
	 */
	if ( strpos( $url, ':' ) === false && ! in_array( $url[0], array( '/', '#', '?' ), true ) &&
		! 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 100vlad.lu
Editors: kama 100
No comments
    Log In . Register