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 }
|