Kama и campusboy, vladlu, Jackky3 месяца назад8 EN

esc_url() │ WP 2.8.0

Очищает УРЛ для использования его в тексте, изменяет неправильные и удаляет опасные символы.

Эта функция в отличии от esc_url_raw() готовит строку к выводу на экран.

Всегда используйте эту функцию, когда нужно очистить УРЛы:

  • в тексте.
  • в атрибутах HTML тегов.

Что делает функция:

  • Создает символы в виде HTML сущностей.
  • Исправляет опечатки: ;// >>> ://
  • Меняет амперсанд & и кавычку ', на их сущности &, '.
  • Удаляет следующие символы:
    • a-z (case-insensitive)
    • 0-9
    • - ~ + _ . ? # = ! & ; , / : % @ $ \ | * ' ( ) [ ]
    • байты в рендже \x80-\xff (extended ASCII)

Избегайте УРЛов, в которых не используется нужный протокол, т.е. УРЛ должен начинаться с одного из: http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, telnet.

Основа для: sanitize_url(), esc_url_raw()
1 раз — 0.000052 сек (очень быстро) | 50000 раз — 0.31 сек (очень быстро) | PHP 7.1.2, WP 4.7.3
Хуки из функции

Возвращает

Строку. Очищенный УРЛ.

Использование

$url = esc_url( $url, $protocols, $_context );
$url(строка) (обязательный)
УРЛ, который нужно очистить.
$protocols(массив)
Массив принимаемых протоколов. По умолчанию это: http, https, ftp, ftps, mailto, news, irc, gopher, nntp, feed, telnet.
По умолчанию: null
$_context(строка)

Как будет использоваться УРЛ. Может быть:

  • display - амперсанд ( & ) и кавычки ('), будут заменены на их сущности.
  • '' (пустая строка) - стандартная очистка.
  • db - стандартная очистка.

По умолчанию: 'display'

Примеры

1

#1 Сравнение с urlencode()

  • urlencode() - кодирует преданную строку, чтобы её можно было использовать как часть URL (без домена). Если передать целиком URL, то он станет нерабочим.

  • esc_url() - обрабатывает URL целиком (не ломает его), заботится о безопасном выводе URL на экран - удаляет или изменяет в URL некоторые символы (совсем не так как это делает urlencode()).
$url = "http://example.com/моя ссылка?var='some&";

echo esc_url( $url );   // http://example.com/моя%20ссылка?var='some&
echo urlencode( $url ); // http%3A%2F%2Fexample.com%2F%D0%BC%D0%BE%D1%8F+%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B0%3Fvar%3D%27some%26
0

#2 Демонстрация очистки URL 

$url = "http;//example.com/link?var='some_&_\backslach";
echo esc_url( $url ); //> http://example.com/link?var='some_&_backslach

$url = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAD///////neHiwAAAAF3RST/+8RwZ==';
echo esc_url( $url ); //> ''

echo esc_url( '#some' ); //> #some

var_dump( esc_url( '' ) );    // string(0) ""
var_dump( esc_url( false ) ); // string(0) ""
var_dump( esc_url( null ) );  // string(0) ""
0

#3 Относительный URL 

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

echo esc_url( '//github.com/wp_limit_login' ); //> //github.com/wp_limit_login

// НО
echo esc_url( 'foo' );  //> http://foo

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

С версии 2.8.0 Введена.
С версии 6.9.0 Prepends https:// to the URL if it does not already contain a scheme and the first item in $protocols is 'https'.

Код esc_url() WP 6.9

wp-includes/formatting.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 the first item
	 * in $protocols is 'https', then https:// is prepended.
	 */
	if ( ! str_contains( $url, ':' ) && ! in_array( $url[0], array( '/', '#', '?' ), true ) &&
		! preg_match( '/^[a-z0-9-]+?\.php/i', $url )
	) {
		$scheme = ( is_array( $protocols ) && 'https' === array_first( $protocols ) ) ? 'https://' : 'http://';
		$url    = $scheme . $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 ( str_contains( $url, '[' ) || str_contains( $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 );
}

esc_ (очистка валидация)

Очистка данных

8 комментариев