annotate core/lib/Drupal/Core/Utility/UnroutedUrlAssemblerInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Utility;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Provides a way to build external or non Drupal local domain URLs.
Chris@0 7 */
Chris@0 8 interface UnroutedUrlAssemblerInterface {
Chris@0 9
Chris@0 10 /**
Chris@0 11 * Builds a domain-local or external URL from a URI.
Chris@0 12 *
Chris@0 13 * For actual implementations the logic probably has to be split up between
Chris@0 14 * domain-local URIs and external URLs.
Chris@0 15 *
Chris@0 16 * @param string $uri
Chris@0 17 * A local URI or an external URL being linked to, such as "base:foo"
Chris@0 18 * or "http://example.com/foo".
Chris@0 19 * - If you provide a full URL, it will be considered an external URL as
Chris@0 20 * long as it has an allowed protocol.
Chris@0 21 * - If you provide only a local URI (e.g. "base:foo"), it will be
Chris@0 22 * considered a path local to Drupal, but not handled by the routing
Chris@0 23 * system. The base path (the subdirectory where the front controller
Chris@0 24 * is found) will be added to the path. Additional query arguments for
Chris@0 25 * local paths must be supplied in $options['query'], not part of $uri.
Chris@0 26 * - If your external URL contains a query (e.g. http://example.com/foo?a=b),
Chris@0 27 * then you can either URL encode the query keys and values yourself and
Chris@0 28 * include them in $uri, or use $options['query'] to let this method
Chris@0 29 * URL encode them.
Chris@0 30 * @param array $options
Chris@0 31 * (optional) An associative array of additional options, with the following
Chris@0 32 * elements:
Chris@0 33 * - 'query': An array of query key/value-pairs (without any URL-encoding) to
Chris@0 34 * append to the URL.
Chris@0 35 * - 'fragment': A fragment identifier (named anchor) to append to the URL.
Chris@0 36 * Do not include the leading '#' character.
Chris@0 37 * - 'absolute': Defaults to FALSE. Whether to force the output to be an
Chris@0 38 * absolute link (beginning with http:). Useful for links that will be
Chris@0 39 * displayed outside the site, such as in an RSS feed.
Chris@0 40 * - 'https': Whether this URL should point to a secure location. If not
Chris@0 41 * defined, the current scheme is used, so the user stays on HTTP or HTTPS
Chris@0 42 * respectively. TRUE enforces HTTPS and FALSE enforces HTTP.
Chris@0 43 * @param bool $collect_bubbleable_metadata
Chris@0 44 * (optional) Defaults to FALSE. When TRUE, both the generated URL and its
Chris@0 45 * associated bubbleable metadata are returned.
Chris@0 46 *
Chris@0 47 * @return string|\Drupal\Core\GeneratedUrl
Chris@0 48 * A string containing a relative or absolute URL.
Chris@0 49 * When $collect_bubbleable_metadata is TRUE, a GeneratedUrl object is
Chris@0 50 * returned, containing the generated URL plus bubbleable metadata.
Chris@0 51 *
Chris@0 52 * @throws \InvalidArgumentException
Chris@0 53 * Thrown when the passed in path has no scheme.
Chris@0 54 */
Chris@0 55 public function assemble($uri, array $options = [], $collect_bubbleable_metadata = FALSE);
Chris@0 56
Chris@0 57 }