Url
class Url implements TrustedCallbackInterface (View source)
Defines an object that holds information about a URL.
In most cases, these should be created with the following methods:
- \Drupal\Core\Url::fromRoute()
- \Drupal\Core\Url::fromRouteMatch()
- \Drupal\Core\Url::fromUri()
- \Drupal\Core\Url::fromUserInput()
Traits
Provides dependency injection friendly methods for serialization.
Properties
| protected array | $_serviceIds | An array of service IDs keyed by property name used for serialization. |
from DependencySerializationTrait |
| protected array | $_entityStorages | An array of entity type IDs keyed by the property name of their storages. |
from DependencySerializationTrait |
| protected UrlGeneratorInterface | $urlGenerator | The URL generator. |
|
| protected UnroutedUrlAssemblerInterface | $urlAssembler | The unrouted URL assembler. |
|
| protected AccessManagerInterface | $accessManager | The access manager. |
|
| protected string | $routeName | The route name. |
|
| protected array | $routeParameters | The route parameters. |
|
| protected array | $options | The URL options. |
|
| protected bool | $external | Indicates whether this object contains an external URL. |
|
| protected bool | $unrouted | Indicates whether this URL is for a URI without a Drupal route. |
|
| protected string | $uri | The non-route URI. |
|
| protected string | $internalPath | Stores the internal path, if already requested by getInternalPath(). |
Methods
Constructs a new Url object.
Creates a new Url object for a URL that has a Drupal route.
Creates a Url object for a relative URI reference submitted by user input.
Create a new Url object for entity URIs.
Creates a new Url object for 'internal:' URIs.
Creates a new Url object for 'route:' URIs.
Returns the Url object matching a request.
Sets this Url to encapsulate an unrouted URI.
Generates a URI string that represents the data in the Url object.
Indicates if this Url is external.
Indicates if this Url has a Drupal route.
Returns the route name.
Returns the route parameters.
Sets the route parameters.
Sets a specific route parameter.
Returns the URL options.
Gets a specific option.
Sets the URL options.
Sets a specific option.
Merges the URL options with any currently set.
Returns the URI value for this Url object.
Sets the value of the absolute option for this Url.
Generates the string URL representation for this Url object.
Returns the route information for a render array.
Returns the internal path (system path) for this route.
Checks this Url object against applicable access check services.
Checks a Url render element against applicable access check services.
No description
Gets the URL generator.
Gets the unrouted URL assembler for non-Drupal URLs.
Sets the unrouted URL assembler.
Lists the trusted callbacks provided by the implementing class.
Details
__sleep()
{@inheritdoc}
__wakeup()
{@inheritdoc}
__construct(string $route_name, array $route_parameters = [], array $options = [])
Constructs a new Url object.
In most cases, use Url::fromRoute() or Url::fromUri() rather than constructing Url objects directly in order to avoid ambiguity and make your code more self-documenting.
static Url
fromRoute(string $route_name, array $route_parameters = [], array $options = [])
Creates a new Url object for a URL that has a Drupal route.
This method is for URLs that have Drupal routes (that is, most pages generated by Drupal). For non-routed local URIs relative to the base path (like robots.txt) use Url::fromUri() with the base: scheme.
static Url
fromRouteMatch(RouteMatchInterface $route_match)
Creates a new URL object from a route match.
static Url
fromUserInput(string $user_input, array $options = [])
Creates a Url object for a relative URI reference submitted by user input.
Use this method to create a URL for user-entered paths that may or may not correspond to a valid Drupal route.
static Url
fromUri(string $uri, array $options = [])
Creates a new Url object from a URI.
This method is for generating URLs for URIs that:
- do not have Drupal routes: both external URLs and unrouted local URIs like base:robots.txt
- do have a Drupal route but have a custom scheme to simplify linking. Currently, there is only the entity: scheme (This allows URIs of the form entity:{entity_type}/{entity_id}. For example: entity:node/1 resolves to the entity.node.canonical route with a node parameter of 1.)
For URLs that have Drupal routes (that is, most pages generated by Drupal), use Url::fromRoute().
static protected Url
fromEntityUri(array $uri_parts, array $options, string $uri)
Create a new Url object for entity URIs.
static protected Url
fromInternalUri(array $uri_parts, array $options)
Creates a new Url object for 'internal:' URIs.
Important note: the URI minus the scheme can NOT simply be validated by a \Drupal\Core\Path\PathValidatorInterface implementation. The semantics of the 'internal:' URI scheme are different:
- PathValidatorInterface accepts paths without a leading slash (e.g.
'node/add') as well as 2 special paths: '
' and ' ', which are mapped to the correspondingly named routes. - 'internal:' URIs store paths with a leading slash that represents the root — i.e. the front page — (e.g. 'internal:/node/add'), and doesn't have any exceptions.
To clarify, a few examples of path plus corresponding 'internal:' URI:
- 'node/add' -> 'internal:/node/add'
- 'node/add?foo=bar' -> 'internal:/node/add?foo=bar'
- 'node/add#kitten' -> 'internal:/node/add#kitten'
- '
' -> 'internal:/' - '
foo=bar' -> 'internal:/?foo=bar' - '
#kitten' -> 'internal:/#kitten' - '
' -> 'internal:' - '
foo=bar' -> 'internal:?foo=bar' - '
#kitten' -> 'internal:#kitten'
Therefore, when using a PathValidatorInterface to validate 'internal:' URIs, we must map:
- 'internal:' (path component is '') to the special '
' path - 'internal:/' (path component is '/') to the special '
' path - 'internal:/some-path' (path component is '/some-path') to 'some-path'
static protected Url
fromRouteUri(array $uri_parts, array $options, string $uri)
Creates a new Url object for 'route:' URIs.
static Url
createFromRequest(Request $request)
Returns the Url object matching a request.
SECURITY NOTE: The request path is not checked to be valid and accessible by the current user to allow storing and reusing Url objects by different users. The 'path.validator' service getUrlIfValid() method should be used instead of this one if validation and access check is desired. Otherwise, 'access_manager' service checkNamedRoute() method should be used on the router name and parameters stored in the Url object returned by this method.
protected $this
setUnrouted()
Sets this Url to encapsulate an unrouted URI.
string
toUriString()
Generates a URI string that represents the data in the Url object.
The URI will typically have the scheme of route: even if the object was constructed using an entity: or internal: scheme. An internal: URI that does not match a Drupal route with be returned here with the base: scheme, and external URLs will be returned in their original form.
bool
isExternal()
Indicates if this Url is external.
bool
isRouted()
Indicates if this Url has a Drupal route.
string
getRouteName()
Returns the route name.
array
getRouteParameters()
Returns the route parameters.
$this
setRouteParameters(array $parameters)
Sets the route parameters.
$this
setRouteParameter(string $key, mixed $value)
Sets a specific route parameter.
array
getOptions()
Returns the URL options.
mixed
getOption(string $name)
Gets a specific option.
See \Drupal\Core\Url::fromUri() for details on the options.
$this
setOptions(array $options)
Sets the URL options.
$this
setOption(string $name, mixed $value)
Sets a specific option.
See \Drupal\Core\Url::fromUri() for details on the options.
$this
mergeOptions(array $options)
Merges the URL options with any currently set.
In the case of conflict with existing options, the new options will replace the existing options.
string
getUri()
Returns the URI value for this Url object.
Only to be used if self::$unrouted is TRUE.
$this
setAbsolute(bool $absolute = TRUE)
Sets the value of the absolute option for this Url.
string|GeneratedUrl
toString(bool $collect_bubbleable_metadata = FALSE)
Generates the string URL representation for this Url object.
For an external URL, the string will contain the input plus any query string or fragment specified by the options array.
If this Url object was constructed from a Drupal route or from an internal URI (URIs using the internal:, base:, or entity: schemes), the returned string will either be a relative URL like /node/1 or an absolute URL like http://example.com/node/1 depending on the options array, plus any specified query string or fragment.
array
toRenderArray()
Returns the route information for a render array.
string
getInternalPath()
Returns the internal path (system path) for this route.
This path will not include any prefixes, fragments, or query strings.
bool|AccessResultInterface
access(AccountInterface $account = NULL, bool $return_as_object = FALSE)
Checks this Url object against applicable access check services.
Determines whether the route is accessible or not.
static bool
renderAccess(array $element)
Checks a Url render element against applicable access check services.
protected AccessManagerInterface
accessManager()
No description
protected UrlGeneratorInterface
urlGenerator()
Gets the URL generator.
protected UnroutedUrlAssemblerInterface
unroutedUrlAssembler()
Gets the unrouted URL assembler for non-Drupal URLs.
$this
setUrlGenerator(UrlGeneratorInterface $url_generator = NULL)
Sets the URL generator.
$this
setUnroutedUrlAssembler(UnroutedUrlAssemblerInterface $url_assembler)
Sets the unrouted URL assembler.
static string[]
trustedCallbacks()
Lists the trusted callbacks provided by the implementing class.
Trusted callbacks are public methods on the implementing class and can be invoked via \Drupal\Core\Security\DoTrustedCallbackTrait::doTrustedCallback().