function UnroutedUrlAssembler::assemble

Same name and namespace in other branches
  1. 9 core/lib/Drupal/Core/Utility/UnroutedUrlAssembler.php \Drupal\Core\Utility\UnroutedUrlAssembler::assemble()
  2. 8.9.x core/lib/Drupal/Core/Utility/UnroutedUrlAssembler.php \Drupal\Core\Utility\UnroutedUrlAssembler::assemble()
  3. 11.x core/lib/Drupal/Core/Utility/UnroutedUrlAssembler.php \Drupal\Core\Utility\UnroutedUrlAssembler::assemble()

This is a helper function that calls buildExternalUrl() or buildLocalUrl() based on a check of whether the path is a valid external URL.

Parameters

string $uri: A local URI or an external URL being linked to, such as "base:foo" or "http://example.com/foo".

  • If you provide a full URL, it will be considered an external URL as long as it has an allowed protocol.
  • If you provide only a local URI (e.g. "base:foo"), it will be considered a path local to Drupal, but not handled by the routing system. The base path (the subdirectory where the front controller is found) will be added to the path. Additional query arguments for local paths must be supplied in $options['query'], not part of $uri.
  • If your external URL contains a query (e.g. http://example.com/foo?a=b), then you can either URL encode the query keys and values yourself and include them in $uri, or use $options['query'] to let this method URL encode them.

array $options: (optional) An associative array of additional options, with the following elements:

  • 'query': An array of query key/value-pairs (without any URL-encoding) to append to the URL.
  • 'fragment': A fragment identifier (named anchor) to append to the URL. Do not include the leading '#' character.
  • 'absolute': Defaults to FALSE. Whether to force the output to be an absolute link (beginning with http:). Useful for links that will be displayed outside the site, such as in an RSS feed.
  • 'https': Whether this URL should point to a secure location. If not defined, the current scheme is used, so the user stays on HTTP or HTTPS respectively. TRUE enforces HTTPS and FALSE enforces HTTP.

bool $collect_bubbleable_metadata: (optional) Defaults to FALSE. When TRUE, both the generated URL and its associated bubbleable metadata are returned.

Return value

string|\Drupal\Core\GeneratedUrl A string containing a relative or absolute URL. When $collect_bubbleable_metadata is TRUE, a GeneratedUrl object is returned, containing the generated URL plus bubbleable metadata.

Overrides UnroutedUrlAssemblerInterface::assemble

File

core/lib/Drupal/Core/Utility/UnroutedUrlAssembler.php, line 54

Class

UnroutedUrlAssembler
Provides a way to build external or non Drupal local domain URLs.

Namespace

Drupal\Core\Utility

Code

public function assemble($uri, array $options = [], $collect_bubbleable_metadata = FALSE) {
  // Note that UrlHelper::isExternal will return FALSE if the $uri has a
  // disallowed protocol.  This is later made safe since we always add at
  // least a leading slash.
  if (parse_url($uri, PHP_URL_SCHEME) === 'base') {
    return $this->buildLocalUrl($uri, $options, $collect_bubbleable_metadata);
  }
  elseif (UrlHelper::isExternal($uri)) {
    // UrlHelper::isExternal() only returns true for safe protocols.
    return $this->buildExternalUrl($uri, $options, $collect_bubbleable_metadata);
  }
  throw new \InvalidArgumentException("The URI '{$uri}' is invalid. You must use a valid URI scheme. Use base: for a path, e.g., to a Drupal file that needs the base path. Do not use this for internal paths controlled by Drupal.");
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.