Drupal 8  8.0.2
UrlHelper Class Reference

Static Public Member Functions

static buildQuery (array $query, $parent= '')
 
static filterQueryParameters (array $query, array $exclude=array(), $parent= '')
 
static parse ($url)
 
static encodePath ($path)
 
static isExternal ($path)
 
static externalIsLocal ($url, $base_url)
 
static filterBadProtocol ($string)
 
static getAllowedProtocols ()
 
static setAllowedProtocols (array $protocols=array())
 
static stripDangerousProtocols ($uri)
 
static isValid ($url, $absolute=FALSE)
 

Static Protected Attributes

static $allowedProtocols = array('http', 'https')
 

Detailed Description

Helper class URL based methods.

Member Function Documentation

static encodePath (   $path)
static

Encodes a Drupal path for use in a URL.

For aesthetic reasons slashes are not escaped.

Parameters
string$pathThe Drupal path to encode.
Returns
string The encoded path.

Referenced by PublicStream\getExternalUrl(), ContextualLinks\render(), and UrlHelperTest\testEncodePath().

Here is the caller graph for this function:

static externalIsLocal (   $url,
  $base_url 
)
static

Determines if an external URL points to this installation.

Parameters
string$urlA string containing an external URL, such as "http://example.com/foo".
string$base_urlThe base URL string to check against, such as "http://example.com/"
Returns
bool TRUE if the URL has the same domain and base path.
Exceptions
\InvalidArgumentExceptionException thrown when a either $url or $bath_url are not fully qualified.

Referenced by UrlHelperTest\testExternalIsLocal(), and UrlHelperTest\testExternalIsLocalInvalid().

Here is the caller graph for this function:

static filterBadProtocol (   $string)
static

Processes an HTML attribute value and strips dangerous protocols from URLs.

Parameters
string$stringThe string with the attribute value.
Returns
string Cleaned up and HTML-escaped version of $string.

References Html\decodeEntities(), and Html\escape().

Referenced by Xss\attributes(), XssUnitTest\testBadProtocolStripping(), CommentTokenReplaceTest\testCommentTokenReplacement(), and UrlHelperTest\testFilterBadProtocol().

Here is the call graph for this function:

Here is the caller graph for this function:

static filterQueryParameters ( array  $query,
array  $exclude = array(),
  $parent = '' 
)
static

Filters a URL query parameter array to remove unwanted elements.

Parameters
array$queryAn array to be processed.
array$exclude(optional) A list of $query array keys to remove. Use "parent[child]" to exclude nested items.
string$parentInternal use only. Used to build the $query array key for nested items.
Returns
An array containing query parameters.

Referenced by ViewsForm\buildForm(), RedirectDestination\get(), UrlTest\testDrupalGetQueryParameters(), and UrlHelperTest\testFilterQueryParameters().

Here is the caller graph for this function:

static getAllowedProtocols ( )
static

Gets the allowed protocols.

Returns
array An array of protocols, for example http, https and irc.
static isExternal (   $path)
static

Determines whether a path is external to Drupal.

An example of an external path is http://example.com. If a path cannot be assessed by Drupal's menu handler, then we must treat it as potentially insecure.

Parameters
string$pathThe internal path or external URL being linked to, such as "node/34" or "http://example.com/foo".
Returns
bool TRUE or FALSE, where TRUE indicates an external path.

Referenced by UnroutedUrlAssembler\assemble(), WebTestBase\assertUrl(), WebTestBase\buildUrl(), FormBuilder\doBuildForm(), BrowserTestBase\drupalGet(), GotoAction\execute(), Url\fromInternalUri(), RedirectDestination\get(), RedirectResponseSubscriber\getDestinationAsAbsoluteUrl(), PathValidator\getUrl(), RedirectResponseSubscriber\sanitizeDestination(), UrlTest\testDrupalParseUrl(), and UrlHelperTest\testIsExternal().

Here is the caller graph for this function:

static isValid (   $url,
  $absolute = FALSE 
)
static

Verifies the syntax of the given URL.

This function should only be used on actual URLs. It should not be used for Drupal menu paths, which can contain arbitrary characters. Valid values per RFC 3986.

Parameters
string$urlThe URL to verify.
bool$absoluteWhether the URL is absolute (beginning with a scheme such as "http:").
Returns
bool TRUE if the URL is in a valid format, FALSE otherwise.

Referenced by PathValidator\getUrl(), OpmlFeedAdd\submitForm(), UrlTest\testDrupalParseUrl(), UrlHelperTest\testInvalidAbsolute(), UrlHelperTest\testInvalidRelative(), UrlHelperTest\testValidAbsolute(), UrlHelperTest\testValidRelative(), and Url\validateUrl().

Here is the caller graph for this function:

static setAllowedProtocols ( array  $protocols = array())
static

Sets the allowed protocols.

Parameters
array$protocolsAn array of protocols, for example http, https and irc.

Referenced by UnroutedUrlAssembler\__construct(), UrlGenerator\__construct(), DrupalKernel\preHandle(), XssTest\setUp(), SafeMarkupTest\tearDown(), UrlHelperTest\testFilterBadProtocol(), SafeMarkupTest\testFormat(), UrlHelperTest\testStripDangerousProtocols(), and LinkExternalProtocolsConstraintValidatorTest\testValidate().

Here is the caller graph for this function:

static stripDangerousProtocols (   $uri)
static

Strips dangerous protocols (for example, 'javascript:') from a URI.

This function must be called for all URIs within user-entered input prior to being output to an HTML attribute value. It is often called as part of ::filterBadProtocol() or ::filter(), but those functions return an HTML-encoded string, so this function can be called independently when the output needs to be a plain-text string for passing to functions that will call Html::escape() separately. The exact behavior depends on the value:

  • If the value is a well-formed (per RFC 3986) relative URL or absolute URL that does not use a dangerous protocol (like "javascript:"), then the URL remains unchanged. This includes all URLs generated via Url::toString() and UrlGeneratorTrait::url().
  • If the value is a well-formed absolute URL with a dangerous protocol, the protocol is stripped. This process is repeated on the remaining URL until it is stripped down to a safe protocol.
  • If the value is not a well-formed URL, the same sanitization behavior as for well-formed URLs will be invoked, which strips most substrings that precede a ":". The result can be used in URL attributes such as "href" or "src" (only after calling Html::escape() separately), but this may not produce valid HTML (for example, malformed URLs within "href" attributes fail HTML validation). This can be avoided by using Url::fromUri($possibly_not_a_url)->toString(), which either throws an exception or returns a well-formed URL.
Parameters
string$uriA plain-text URI that might contain dangerous protocols.
Returns
string A plain-text URI stripped of dangerous protocols. As with all plain-text strings, this return value must not be output to an HTML page without being sanitized first. However, it can be passed to functions expecting plain-text strings.
See Also
::escape()
::toString()
::url()
::fromUri()

Referenced by FormattableMarkup\placeholderFormat(), HandlerBase\sanitizeValue(), XssUnitTest\testBadProtocolStripping(), and UrlHelperTest\testStripDangerousProtocols().

Here is the caller graph for this function:


The documentation for this class was generated from the following file: