W3cubDocs

/Drupal 8

public function UnroutedUrlAssemblerInterface::assemble

public UnroutedUrlAssemblerInterface::assemble($uri, array $options = array(), $collect_bubbleable_metadata = FALSE)

Builds a domain-local or external URL from a URI.

For actual implementations the logic probably has to be split up between domain-local URIs and external URLs.

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.

Throws

\InvalidArgumentException Thrown when the passed in path has no scheme.

File

core/lib/Drupal/Core/Utility/UnroutedUrlAssemblerInterface.php, line 55

Class

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

Namespace

Drupal\Core\Utility

Code

public function assemble($uri, array $options = array(), $collect_bubbleable_metadata = FALSE);

© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Utility!UnroutedUrlAssemblerInterface.php/function/UnroutedUrlAssemblerInterface::assemble/8.1.x