annotate vendor/symfony-cmf/routing/RouteProviderInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
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 }