www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Utility/UnroutedUrlAssemblerInterface.php

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