Router.php

<?php
/** @namespace RESTAPI
 *
 * Im Namensraum RESTAPI sind alle Klassen und Funktionen versammelt,
 * die für die RESTful Web Services von Stud.IP benötigt werden.
 */
namespace RESTAPI;
use RESTAPI\Renderer\DefaultRenderer;

/**
 * Die Aufgabe des Routers ist das Anlegen und Auswerten eines
 * Mappings von sogenannten Routen (Tupel aus HTTP-Methode und Pfad)
 * auf Code.
 *
 * Dazu werden zunächst Routen mittels der Funktion
 * Router::registerRoutes registriert.
 *
 * Wenn dann ein HTTP-Request eingeht, kann mithilfe von
 * Router::dispatch und HTTP-Methode bzw. Pfad der zugehörige Code
 * gefunden und ausgeführt werden. Der Router bildet aus dem
 * Rückgabewert des Codes ein Response-Objekt, das er als Ergebnis
 * zurück meldet.
 *
 * @code
 * $router = Router::getInstance();
 *
 * // register a sample Route
 * $router->registerRoutes(new ExampleRoute);
 *
 * // dispatch to therein defined Routes
 * $response = $router->dispatch('/example', 'GET');
 *
 * // render response
 * $response->output();
 *
 * @endcode
 *
 * @author     Jan-Hendrik Willms <tleilax+studip@gmail.com>
 * @author     <mlunzena@uos.de>
 * @license    GPL 2 or later
 * @see        Inspired by http://blog.sosedoff.com/2009/07/04/simpe-php-url-routing-controller/
 * @since      Stud.IP 3.0
 * @deprecated Since Stud.IP 5.0. Will be removed in Stud.IP 5.2.
 */
class Router
{
    // instances are cached here
    protected static $instances = [];

    /**
     * Holds the user object of the user that is accessing the API.
     * This is null for nobody users.
     */
    protected $user = null;

    /**
     * Returns (and if neccessary, initializes) a (cached) router object for an
     * optional consumer id.
     *
     * @param mixed $consumer_id ID of the consumer (defaults to 'global')
     *
     * @return Router returns the Router instance associated to the
     *                consumer ID (or to the 'global' ID)
     */
    public static function getInstance($consumer_id = null)
    {
        $consumer_id = $consumer_id ?: 'global';

        if (!isset(self::$instances[$consumer_id])) {
            self::$instances[$consumer_id] = new self($consumer_id);
        }
        return self::$instances[$consumer_id];
    }

    // All supported method need to be defined here
    protected static $supported_methods = [
        'get', 'post', 'put', 'delete', 'patch', 'options', 'head'
    ];

    /**
     * Returns a list of all supported methods.
     *
     * @return array of methods as strings
     */
    public static function getSupportedMethods()
    {
        return self::$supported_methods;
    }

    // registered routes by method and uri template
    protected $routes = [];

    // registered content renderers
    protected $renderers = [];

    // identified or forced content renderer
    protected $content_renderer = false;

    // default renderer
    protected $default_renderer = false;

    // registered conditions
    protected $conditions = [];

    // registered descriptions
    protected $descriptions = [];

    // registered consumers
    protected $consumers = [];

    // associated permissions
    protected $permissions = false;

    /**
     * Constructs the router.
     *
     * @param mixed $consumer_id  the ID of the consumer this router
     *                             should associate to
     */
    protected function __construct($consumer_id)
    {
        $this->permissions = ConsumerPermissions::get($consumer_id);
        $this->registerRenderer(new Renderer\DefaultRenderer);
    }

    /**
     * Registers a handler for a specific combination of request method
     * and uri template.
     *
     * @param String  $request_method   expected HTTP request method
     * @param String  $uri_template     expected URI template, for
     *                                  example: \code "/user/:user_id/events" \endcode
     * @param Array   $handler          request handler array:
     *                                  \code array($object, "methodName") \endcode
     * @param Array   $conditions       (optional) an associative
     *                                  array using the name of
     *                                  parameters as keys and regexps
     *                                  as value
     * @param string  $source           (optional) this denotes the
     *                                  origin of a route. Usually
     *                                  either 'core' or 'plugin', but
     *                                  defaults to 'unknown'.
     * @param bool    $allow_nobody     Whether the route can be accessed
     *                                  as nobody user (true) or not (false).
     *                                  Defaults to false.
     *
     * @return Router  returns itself to allow chaining
     * @throws \Exception  if passed HTTP request method is not supported
     */
    public function register($request_method, $uri_template, $handler, $conditions = [], $source = 'unknown', $allow_nobody = false)
    {
        // Normalize method and test whether it's supported
        $request_method = mb_strtolower($request_method);
        if (!in_array($request_method, self::$supported_methods)) {
            throw new \Exception('Method "' . $request_method . '" is not supported.');
        }

        // Initialize routes storage for this method if neccessary
        if (!isset($this->routes[$request_method])) {
            $this->routes[$request_method] = [];
        }

        // Normalize uri template (always starts with a slash)
        if ($uri_template[0] !== '/') {
            $uri_template = '/' . $uri_template;
        }

        // Sanitize conditions
        foreach ($conditions as $var => $pattern) {
            if ($pattern[0] !== $pattern[mb_strlen($pattern) - 1] || ctype_alnum($pattern[0])) {
                $conditions[$var] = '/' . $pattern . '/';
            }
        }

        $this->routes[$request_method][$uri_template] = compact(
            'handler', 'conditions', 'source', 'allow_nobody'
        );

        // Return instance to allow chaining
        return $this;
    }

    /**
     * Registers the routes defined in a RouteMap instance using
     * docblock annotations (like @get) of its methods.
     *
     * \code
     * $router = \RESTAPI\Router::getInstance();
     *
     * $router->registerRoutes(new ExampleRouteMap());
     * \endcode
     *
     * @param RouteMap $map  the RouteMap instance to register
     *
     * @return Router returns itself to allow chaining
     */
    public function registerRoutes(RouteMap $map)
    {
        // Investigate object, define whether it's located in the core system
        // or a plugin, respect any defined class conditions and iterate
        // through it's methods to find any defined route
        $ref      = new \ReflectionClass($map);
        $filename = $ref->getFilename();
        $source   = mb_strpos($filename, 'plugins_packages') !== false
                  ? 'plugin'
                  : 'core';

        foreach (self::$supported_methods as $http_method) {
            foreach ($map->getRoutes($http_method) as $uri_template => $data) {
                // Register (and describe) route
                $this->register(
                    $http_method, $uri_template,
                    $data['handler'], $data['conditions'],
                    $source,
                    $data['allow_nobody']
                );
                if ($data['description']) {
                    $this->describe(
                        $uri_template,
                        $data['description'],
                        $http_method
                    );
                }
            }
        }

        return $this;
    }

    /**
     * Describe one or more routes.
     *
     * \code
     * $router = \RESTAPI\Router::getInstance();
     *
     * // describe a single route
     * $router->describe('/foo', 'returns everything about foo', 'get');
     *
     * // describe several routes that use the same path
     * $router->describe('/foo', array(
     *     'get'    => 'returns everything about foo',
     *     'put'    => 'updates all of foo',
     *     'delete' => 'empty up foo'
     * ));
     *
     * // describe several routes
     * $router->describe(array(
     *     '/foo' => array(
     *                   'get'    => 'returns everything about foo',
     *                   'put'    => 'updates all of foo',
     *                   'delete' => 'empty up foo'),
     *     '/bar' => array(...),
     * ));
     * \endcode
     *
     * @param String|Array $uri_template  URI template to describe or pass an
     *                                    array to describe multiple routes.
     * @param String|null  $description   description of the route
     * @param String       $method        method to describe.
     *
     * @return Router  returns instance of itself to allow chaining
     */
    public function describe($uri_template, $description = null, $method = 'get')
    {
        // describe multiple routes at once
        if (func_num_args() === 1 && is_array($uri_template)) {
            foreach ($uri_template as $template => $description) {
                $this->describe($template, $description);
            }
        }

        // describe routes that use the same URI template
        elseif (func_num_args() === 2 && is_array($description)) {
            foreach ($description as $method => $desc) {
                $this->describe($uri_template, $desc, $method);
            }
        }

        // describe a single route
        else {
            if (!isset($this->descriptions[$uri_template])) {
                $this->descriptions[$uri_template] = [];
            }
            if (isset($this->routes[$method][$uri_template])) {
                $this->descriptions[$uri_template][$method] = $description;
            } else {
                // Try to find route with different method
                foreach ($this->routes as $m => $templates) {
                    if (isset($templates[$uri_template])) {
                        $this->descriptions[$uri_template][$m] = $description;
                        break;
                    }
                }
            }
        }
        return $this;
    }

    /**
     * Get list of registered routes - optionally with their descriptions.
     *
     * @param bool $describe      (optional) include descriptions,
     *                              defaults to `false`
     * @param bool $check_access  (optional) only show methods this router's
     *                              consumer is authorized to,
     *                              defaults to `true`
     *
     * @return array list of registered routes
     */
    public function getRoutes($describe = false, $check_access = true)
    {
        $this->setupRoutes();

        $result = [];
        foreach ($this->routes as $method => $routes) {
            foreach ($routes as $uri => $route) {
                if ($check_access && !$this->permissions->check($uri, $method)) {
                    continue;
                }
                if (!isset($result[$uri])) {
                    $result[$uri] = [];
                }
                if ($describe) {
                    $result[$uri][$method] = [
                        'description' => $this->descriptions[$uri][$method] ?: null,
                        'source'      => $route['source'] ?: 'unknown',
                    ];
                } else {
                    $result[$uri][] = $method;
                }
            }
        }
        ksort($result);
        if ($describe) {
            $result = array_map(function ($item) {
                ksort($item);
                return $item;
            }, $result);
        }
        return $result;
    }

    /**
     * Dispatches an URI across the defined routes and produces a
     * Response object which may then be send back (using #output).
     *
     * @param mixed  $uri     URI to dispatch (defaults to `$_SERVER['PATH_INFO']`)
     * @param String $method  Request method (defaults to the method
     *                        of the actual HTTP request or "GET")
     *
     * @return Response  a Response object containing status, headers
     *                   and body
     * @throws RouterException  may throw such an exception if there
     *                          is no matching route (404) or if there
     *                          is one, but the consumer is not
     *                          authorized to it (403)
     */
    public function dispatch($uri = null, $method = null)
    {
        $this->setupRoutes();

        $uri = $this->normalizeDispatchURI($uri);
        $method = $this->normalizeRequestMethod($method);

        $content_renderer = $this->negotiateContent($uri);

        [$route, $parameters, $allow_nobody] = $this->matchRoute($uri, $method, $content_renderer);
        if (!$route) {
            //No route found for the combination of URI and method.
            //We return the allowed methods for the route in the HTTP header:
            $methods = $this->getMethodsForUri($uri);
            if (count($methods) > 0) {
                header('Allow: ' . implode(', ', $methods));
                throw new RouterException(405);
            } else {
                //Route not found.
                throw new RouterException(404);
            }
        }
        //At this point, a route is found.
        //We need to check if it can be used as nobody user or not.
        if (!$route['allow_nobody'] && !$this->user) {
            //Nobody users aren't allowed for this route.
            throw new RouterException(401, 'Unauthorized (no consumer)');
        }

        try {
            $response = $this->execute($route, $parameters);
        } catch (RouterHalt $halt) {
            $response = $halt->response;
        }

        $response->finish($content_renderer);

        return $response;
    }

    /**
     * Searches and registers available routes.
     */
    private function setupRoutes()
    {
        // A bit ugly, I confess
        static $was_setup = false;
        if ($was_setup) {
            return;
        }
        $was_setup = true;

        // Register default routes
        $routes = [
            'Activity',
            'Blubber',
            'Clipboard',
            'Consultations',
            'Contacts',
            'Course',
            'Discovery',
            'Events',
			'Feedback',
            'FileSystem',
            'Forum',
            'Messages',
            'News',
            'ResourceBooking',
            'Resources',
            'ResourceCategories',
            'ResourcePermissions',
            'ResourceProperties',
            'ResourceRequest',
            'RoomClipboard',
            'Schedule',
            'Semester',
            'Studip',
            'User',
            'UserConfig',
            'Wiki'
        ];

        foreach ($routes as $route) {
            require_once "app/routes/$route.php";
            $class = "\\RESTAPI\\Routes\\$route";
            $this->registerRoutes(new $class);
        }

        // Register plugin routes
        $router = $this;
        $routes = array_flatten(\PluginEngine::sendMessage('RESTAPIPlugin', 'getRouteMaps'));
        array_walk(
            $routes,
            function ($route) use ($router) {
                $router->registerRoutes($route);
            }
        );
    }

    /**
     * Takes a route and the parameters out of the requested path and
     * executes the handler of the route.
     *
     * @param array $route      the matched route out of
     *                          Router::matchRoute; an array with keys
     *                          'handler', 'conditions' and 'source'
     * @param array $parameters the matched parameters out of
     *                          Router::matchRoute; something like:
     *                          `array('user_id' => '23a21d...e78f')`
     * @return Response  the resulting Response object which is then
     *                   polished in Router::dispatch
     */
    protected function execute($route, $parameters)
    {
        $handler = $route['handler'];

        if (!is_object($handler[0])) {
            throw new \RuntimeException("Handler is not a method.");
        }

        $handler[0]->init($this, $route);

        if (method_exists($handler[0], 'before')) {
            $handler[0]->before($this, $handler, $parameters);
        }

        $result = call_user_func_array($handler, $parameters);

        if (method_exists($result, 'toArray')) {
            $result = $result->toArray();
        }

        // $result is stronger than $response->body
        if (isset($result)) {
            $handler[0]->body($result);
        }

        if (method_exists($handler[0], 'after')) {
            $handler[0]->after($this, $parameters);
        }

        return $handler[0]->getResponse();
    }

    /**
     * Registers a content renderer.
     *
     * @param DefaultRenderer $renderer    instance of a content renderer
     * @param boolean         $is_default  (optional) set this
     *                                     renderer as default?;
     *                                     defaults to `false`
     *
     * @return Router returns itself to allow chaining
     */
    public function registerRenderer($renderer, $is_default = false)
    {
        $this->renderers[$renderer->extension()] = $renderer;
        if ($is_default) {
            $this->default_renderer = $renderer;
        }

        return $this;
    }

    private function normalizeDispatchURI($uri)
    {
        return $uri === null ? $_SERVER['PATH_INFO'] : $uri;
    }

    private function normalizeRequestMethod($method)
    {
        return mb_strtolower($method ?: \Request::method() ?: 'get');
    }

    /**
     * Negotiate content using the registered content renderers. The
     * first ContentRenderer that returns `true` when calling
     * ContentRenderer::shouldRespondTo gets the job.
     *
     * @param String $uri  the URI to which the content renderers may respond
     *
     * @return ContentRenderer  either a ContentRenderer that responds
     *                          to the URI or the default
     *                          ContentRenderer of this router.
     */
    protected function negotiateContent($uri)
    {
        $content_renderer = null;
        foreach ($this->renderers as $renderer) {
            if ($renderer->shouldRespondTo($uri)) {
                $content_renderer = $renderer;
                break;
            }
        }
        if (!$content_renderer) {
            $content_renderer = $this->default_renderer ?: reset($this->renderers);
        }
        return $content_renderer;
    }

    /**
     * Tries to match a route given a URI and a HTTP request method.
     *
     * @param String $uri     the URI to match
     * @param String $method  the HTTP request method to match
     * @param DefaultRenderer $content_renderer the used
     *                                          ContentRenderer which
     *                                          is needed to remove
     *                                          a file extension
     *
     * @return array  an array containing the matched route and the
     *                found parameters
     */
    protected function matchRoute($uri, $method, $content_renderer)
    {
        $matched    = null;
        $parameters = [];
        if (isset($this->routes[$method])) {
            if ($content_renderer->extension() && mb_strpos($uri, $content_renderer->extension()) !== false) {
                $uri = mb_substr($uri, 0, -mb_strlen($content_renderer->extension()));
            }

            foreach ($this->routes[$method] as $uri_template => $route) {
                if (!isset($route['uri_template'])) {
                    $route['uri_template'] = new UriTemplate($uri_template, $route['conditions']);
                }

                if ($route['uri_template']->match($uri, $prmtrs)) {
                    if (!$this->permissions->check($uri_template, $method)) {
                        throw new RouterException(403, "Route not activated");
                    }
                    $matched = $route;
                    $parameters = $prmtrs;
                    break;
                }
            }
        }
        return [$matched, $parameters];
    }

    /**
     * Returns all methods the given uri responds to.
     *
     * @param String $uri the URI to match
     *
     * @return array of all of responding methods
     */
    protected function getMethodsForUri($uri)
    {
        $methods = [];

        foreach ($this->routes as $method => $templates) {
            foreach ($templates as $uri_template => $route) {
                if (!isset($route['uri_template'])) {
                    $route['uri_template'] = new UriTemplate($uri_template, $route['conditions']);
                }

                if ($route['uri_template']->match($uri)
                    && $this->permissions->check($uri_template, $method))
                {
                    $methods[] = $method;
                }
            }
        }

        return array_map('strtoupper', $methods);
    }


    /**
     * Sets up the authentication for the router.
     */
    public function setupAuth()
    {
        // Detect consumer
        $consumer = Consumer\Base::detectConsumer();
        if (!$consumer) {
            return null;
        }

        $this->user = $consumer->getUser();

        // Set authentication if present
        if ($this->user) {
            // Skip fake authentication if user is already logged in
            if ($GLOBALS['user']->id !== $this->user->id) {

                $GLOBALS['auth'] = new \Seminar_Auth();
                $GLOBALS['auth']->auth = [
                    'uid'   => $this->user->user_id,
                    'uname' => $this->user->username,
                    'perm'  => $this->user->perms,
                ];

                $GLOBALS['user'] = new \Seminar_User($this->user);

                $GLOBALS['perm'] = new \Seminar_Perm();
                $GLOBALS['MAIL_VALIDATE_BOX'] = false;
            }
            setTempLanguage($GLOBALS['user']->id);
        }

        return $this->user;
    }
}