www.aleph1.co.uk Git - yaffs-website/blob - vendor/symfony-cmf/routing/RouteProviderInterface.php

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