Newer
Older
Alex Pott
committed
<?php
namespace Drupal\Core\Routing;
use Symfony\Component\HttpFoundation\Request;
Alex Pott
committed
/**
* Defines the route provider interface.
Alex Pott
committed
*/
interface RouteProviderInterface {
Alex Pott
committed
/**
* Finds routes that may potentially match the request.
*
* This may return a mixed list of class instances, but all routes returned
* must extend the core Symfony route. The classes may also implement
* RouteObjectInterface to link to a content document.
*
* This method may not throw an exception based on implementation specific
* restrictions on the URL. That case is considered a not found - returning
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
* an empty array. Exceptions are only used to abort the whole request in
* case something is seriously broken, like the storage backend being down.
*
* Note that implementations may not implement an optimal matching
* algorithm, simply a reasonable first pass. That allows for potentially
* very large route sets to be filtered down to likely candidates, which
* may then be filtered in memory more completely.
*
* @param \Symfony\Component\HttpFoundation\Request $request
* A request against which to match
*
* @return \Symfony\Component\Routing\RouteCollection
* All Routes that could potentially match $request.
* Empty collection if nothing can match
*/
public function getRouteCollectionForRequest(Request $request);
/**
* Find the route using the provided route name.
*
* @param string $name
* The route name to fetch
*
* @return \Symfony\Component\Routing\Route
* The Symfony route object.
*
* @throws \Symfony\Component\Routing\Exception\RouteNotFoundException
* If a matching route cannot be found.
*/
public function getRouteByName($name);
/**
* Find many routes by their names using the provided list of names.
*
* Note that this method may not throw an exception if some of the routes
* are not found or are not actually Route instances. It will just return the
* list of those Route instances it found.
*
* This method exists in order to allow performance optimizations. The
* simple implementation could be to just repeatedly call
* $this->getRouteByName() while catching and ignoring eventual exceptions.
*
* If $names is null, this method SHOULD return a collection of all routes
* known to this provider. If there are many routes to be expected, usage of
* a lazy loading collection is recommended. A provider MAY only return a
* subset of routes to e.g. support paging or other concepts.
*
* @param array|null $names
* The list of names to retrieve, In case of null, the provider will
* determine what routes to return
*
* @return \Symfony\Component\Routing\Route[]
* Iterable list with the keys being the names from the $names array
*/
public function getRoutesByNames($names);
Alex Pott
committed
/**
* Get all routes which match a certain pattern.
*
* @param string $pattern
* The route pattern to search for (contains {} as placeholders).
*
* @return \Symfony\Component\Routing\RouteCollection
* Returns a route collection of matching routes. The collection may be
* empty and will be sorted from highest to lowest fit (match of path parts)
* and then in ascending order by route name for routes with the same fit.
Alex Pott
committed
*/
public function getRoutesByPattern($pattern);
/**
* Returns all the routes on the system.
*
* Usage of this method is discouraged for performance reasons. If possible,
* use RouteProviderInterface::getRoutesByNames() or
* RouteProviderInterface::getRoutesByPattern() instead.
*
* @return \Symfony\Component\Routing\Route[]
* An iterator of routes keyed by route name.
*/
public function getAllRoutes();
/**
* Resets the route provider object.
*/
public function reset();