Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 /*
|
Chris@0
|
4 * This file is part of the Symfony CMF package.
|
Chris@0
|
5 *
|
Chris@0
|
6 * (c) 2011-2015 Symfony CMF
|
Chris@0
|
7 *
|
Chris@0
|
8 * For the full copyright and license information, please view the LICENSE
|
Chris@0
|
9 * file that was distributed with this source code.
|
Chris@0
|
10 */
|
Chris@0
|
11
|
Chris@0
|
12 namespace Symfony\Cmf\Component\Routing;
|
Chris@0
|
13
|
Chris@0
|
14 use Symfony\Component\HttpFoundation\Request;
|
Chris@0
|
15 use Symfony\Component\Routing\Exception\RouteNotFoundException;
|
Chris@0
|
16 use Symfony\Component\Routing\Route;
|
Chris@0
|
17 use Symfony\Component\Routing\RouteCollection;
|
Chris@0
|
18
|
Chris@0
|
19 /**
|
Chris@0
|
20 * Interface for the route provider the DynamicRouter is using.
|
Chris@0
|
21 *
|
Chris@0
|
22 * Typically this could be a doctrine orm or odm repository, but you can
|
Chris@0
|
23 * implement something else if you need to.
|
Chris@0
|
24 */
|
Chris@0
|
25 interface RouteProviderInterface
|
Chris@0
|
26 {
|
Chris@0
|
27 /**
|
Chris@0
|
28 * Finds routes that may potentially match the request.
|
Chris@0
|
29 *
|
Chris@0
|
30 * This may return a mixed list of class instances, but all routes returned
|
Chris@0
|
31 * must extend the core symfony route. The classes may also implement
|
Chris@0
|
32 * RouteObjectInterface to link to a content document.
|
Chris@0
|
33 *
|
Chris@0
|
34 * This method may not throw an exception based on implementation specific
|
Chris@0
|
35 * restrictions on the url. That case is considered a not found - returning
|
Chris@0
|
36 * an empty array. Exceptions are only used to abort the whole request in
|
Chris@0
|
37 * case something is seriously broken, like the storage backend being down.
|
Chris@0
|
38 *
|
Chris@0
|
39 * Note that implementations may not implement an optimal matching
|
Chris@0
|
40 * algorithm, simply a reasonable first pass. That allows for potentially
|
Chris@0
|
41 * very large route sets to be filtered down to likely candidates, which
|
Chris@0
|
42 * may then be filtered in memory more completely.
|
Chris@0
|
43 *
|
Chris@0
|
44 * @param Request $request A request against which to match.
|
Chris@0
|
45 *
|
Chris@0
|
46 * @return RouteCollection with all Routes that could potentially match
|
Chris@0
|
47 * $request. Empty collection if nothing can match.
|
Chris@0
|
48 */
|
Chris@0
|
49 public function getRouteCollectionForRequest(Request $request);
|
Chris@0
|
50
|
Chris@0
|
51 /**
|
Chris@0
|
52 * Find the route using the provided route name.
|
Chris@0
|
53 *
|
Chris@0
|
54 * @param string $name The route name to fetch.
|
Chris@0
|
55 *
|
Chris@0
|
56 * @return Route
|
Chris@0
|
57 *
|
Chris@0
|
58 * @throws RouteNotFoundException If there is no route with that name in
|
Chris@0
|
59 * this repository
|
Chris@0
|
60 */
|
Chris@0
|
61 public function getRouteByName($name);
|
Chris@0
|
62
|
Chris@0
|
63 /**
|
Chris@0
|
64 * Find many routes by their names using the provided list of names.
|
Chris@0
|
65 *
|
Chris@0
|
66 * Note that this method may not throw an exception if some of the routes
|
Chris@0
|
67 * are not found or are not actually Route instances. It will just return the
|
Chris@0
|
68 * list of those Route instances it found.
|
Chris@0
|
69 *
|
Chris@0
|
70 * This method exists in order to allow performance optimizations. The
|
Chris@0
|
71 * simple implementation could be to just repeatedly call
|
Chris@0
|
72 * $this->getRouteByName() while catching and ignoring eventual exceptions.
|
Chris@0
|
73 *
|
Chris@0
|
74 * If $names is null, this method SHOULD return a collection of all routes
|
Chris@0
|
75 * known to this provider. If there are many routes to be expected, usage of
|
Chris@0
|
76 * a lazy loading collection is recommended. A provider MAY only return a
|
Chris@0
|
77 * subset of routes to e.g. support paging or other concepts, but be aware
|
Chris@0
|
78 * that the DynamicRouter will only call this method once per
|
Chris@0
|
79 * DynamicRouter::getRouteCollection() call.
|
Chris@0
|
80 *
|
Chris@0
|
81 * @param array|null $names The list of names to retrieve, In case of null,
|
Chris@0
|
82 * the provider will determine what routes to return.
|
Chris@0
|
83 *
|
Chris@0
|
84 * @return Route[] Iterable list with the keys being the names from the
|
Chris@0
|
85 * $names array.
|
Chris@0
|
86 */
|
Chris@0
|
87 public function getRoutesByNames($names);
|
Chris@0
|
88 }
|