Flight\Routing\RouteCollection

Complexity

Total Complexity

33

Size/Duplication

Total Lines	303
Duplicated Lines	0 %

Test Coverage

Coverage

100%

Importance

Changes	2
Bugs	0	Features	0

17 Methods

Rating	Name	Duplication	Size	Complexity
A	addRoute()	0	11	2
A	post()	0	3	1
A	head()	0	3	1
A	patch()	0	3	1
A	options()	0	3	1
A	resource()	0	11	4
A	add()	0	13	3
A	get()	0	3	1
A	find()	0	9	3
A	doMerge()	0	21	5
A	group()	0	15	3
A	put()	0	3	1
A	delete()	0	3	1
A	any()	0	3	1
A	__construct()	0	4	1
A	__call()	0	21	3
A	getRoutes()	0	3	1

<?php

declare(strict_types=1);

/*
 * This file is part of Flight Routing.
 *
 * PHP version 7.1 and above required
 *
 * @author    Divine Niiquaye Ibok <divineibok@gmail.com>
 * @copyright 2019 Biurad Group (https://biurad.com/)
 * @license   https://opensource.org/licenses/BSD-3-Clause License
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Flight\Routing;

use Flight\Routing\Exceptions\InvalidControllerException;

/**
 * A RouteCollection represents a set of Route instances.
 *
 * This class provides all(*) methods for creating path+HTTP method-based routes and
 * injecting them into the router:
 *
 * - head
 * - get
 * - post
 * - put
 * - patch
 * - delete
 * - options
 * - any
 * - resource
 *
 * A general `addRoute()` method allows specifying multiple request methods and/or
 * arbitrary request methods when creating a path-based route.
 *
 * __call() forwards method-calls to Route, but returns instance of RouteCollection
 * listing Route's methods below, so that IDEs know they are valid
 *
 * @method RouteCollection withAssert(string $variable, string $regexp)
 * @method RouteCollection withDefault(string $variable, mixed $default)
 * @method RouteCollection withArgument($variable, mixed $value)
 * @method RouteCollection withMethod(string ...$methods)
 * @method RouteCollection withScheme(string ...$schemes)
 * @method RouteCollection withMiddleware(mixed ...$middlewares)
 * @method RouteCollection withDomain(string ...$hosts)
 * @method RouteCollection withPrefix(string $path)
 *
 * @author Fabien Potencier <fabien@symfony.com>
 * @author Tobias Schultze <http://tobion.de>
 * @author Divine Niiquaye Ibok <divineibok@gmail.com>
 */
final class RouteCollection extends \ArrayIterator
{
    /** @var null|string */
    private $namePrefix;

    /** @var Route */
    private $defaultRoute;

    /**
     * @param null|Route $defaultRoute
     * @param mixed      $defaultHandler
     */
    public function __construct(?Route $defaultRoute = null, $defaultHandler = null)
    {
        $this->defaultRoute = $defaultRoute ?? new Route('/', '', $defaultHandler);
        parent::__construct();
    }

    /**
     * @param string   $method
     * @param string[] $arguments
     *
     * @return mixed
     */
    public function __call($method, $arguments)
    {
        $routeMethod = \strtolower((string) \preg_replace('~^with([A-Z]{1}[a-z]+)$~', '\1', $method, 1));

        if (!\method_exists($this->defaultRoute, $routeMethod)) {
            throw new \BadMethodCallException(
                \sprintf(
                    'Method "%s::%s" does not exist. %2$s method should have a \'with\' prefix',
                    Route::class,
                    $method
                )
            );
        }

        \call_user_func_array([$this->defaultRoute, $routeMethod], $arguments);

        foreach ($this as $route) {
            \call_user_func_array([$route, $routeMethod], $arguments);
        }

        return $this;
    }

    /**
     * Gets the current RouteCollection as an array that includes all routes.
     *
     * Use this method to fetch routes instead of getIterator().
     *
     * @return Route[] The filtered merged routes
     */
    public function getRoutes(): array
    {
        return $this->doMerge('', new static());
    }

    /**
     * Add route(s) to the collection
     *
     * @param Route ...$routes
     *
     * @return self
     */
    public function add(Route ...$routes): self
    {
        foreach ($routes as $route) {
            $default = clone $this->defaultRoute;

            if (null === $route->getController()) {
                $route->run($default->getController());
            }

            $this[]  = $default::__set_state($route->getAll());
        }

        return $this;
    }

    /**
     * Maps a pattern to a handler.
     *
     * You can must specify HTTP methods that should be matched.
     *
     * @param string   $pattern Matched route pattern
     * @param string[] $methods Matched HTTP methods
     * @param mixed    $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function addRoute(string $pattern, array $methods, $handler = null): Route
    {
        $route      = clone $this->defaultRoute;
        $controller = null === $handler ? $route->getController() : $handler;

        $route->path($pattern)->method(...$methods);

        $this[] = $route;
        $route->run($controller);

        return $route;
    }

    /**
     * Mounts controllers under the given route prefix.
     *
     * @param string                   $name        The route group prefixed name
     * @param callable|RouteCollection $controllers A RouteCollection instance or a callable for defining routes
     *
     * @throws \LogicException
     */
    public function group(string $name, $controllers): self
    {
        if (\is_callable($controllers)) {
            $collection = new static();
            \call_user_func($controllers, $collection);

It seems like $controllers can also be of type Flight\Routing\RouteCollection; however, parameter $callback of call_user_func() does only seem to accept callable, maybe add an additional type check?

            $controllers = clone $collection;
        } elseif (!$controllers instanceof self) {
            throw new \LogicException('The "mount" method takes either a "RouteCollection" instance or callable.');
        }

        $controllers->namePrefix = $name;

        $this[] = $controllers;

        return $controllers;
    }

    /**
     * Maps a HEAD request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function head(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_HEAD], $handler);
    }

    /**
     * Maps a GET and HEAD request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function get(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_GET, Router::METHOD_HEAD], $handler);
    }

    /**
     * Maps a POST request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function post(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_POST], $handler);
    }

    /**
     * Maps a PUT request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function put(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_PUT], $handler);
    }

    /**
     * Maps a PATCH request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function patch(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_PATCH], $handler);
    }

    /**
     * Maps a DELETE request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function delete(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_DELETE], $handler);
    }

    /**
     * Maps a OPTIONS request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function options(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, [Router::METHOD_OPTIONS], $handler);
    }

    /**
     * Maps any request to a handler.
     *
     * @param string $pattern Matched route pattern
     * @param mixed  $handler Handler that returns the response when matched
     *
     * @return Route
     */
    public function any(string $pattern, $handler = null): Route
    {
        return $this->addRoute($pattern, Router::HTTP_METHODS_STANDARD, $handler);
    }

    /**
     * Maps any request to a resource handler and prefix class method by request method.
     * If you request on "/account" path with a GET method, prefixed by the name
     * parameter eg: 'user', class method will match `getUser`.
     *
     * @param string              $name     The prefixed name attached to request method
     * @param string              $pattern  matched path where request should be sent to
     * @param class-string|object $resource Handler that returns the response

The doc comment class-string|object at position 0 could not be parsed: Unknown type name 'class-string' at position 0 in class-string|object.

     *
     * @return Route
     */
    public function resource(string $name, string $pattern, $resource): Route
    {
        if (!\is_object($resource) || (\is_string($resource) && \class_exists($resource))) {
            throw new InvalidControllerException(
                'Resource handler type should be a class string or class object, but not a callable or array'
            );
        }

        $route = $this->any($pattern, [$resource, $name]);

        return $route->bind($route->generateRouteName($name) . '__restful');
    }

    /**
     * Find a route by name.
     *
     * @param string $name The route name
     *
     * @return null|Route A Route instance or null when not found
     */
    public function find(string $name): ?Route
    {
        foreach ($this as $route) {
            if ($name === $route->getName()) {
                return $route;
            }
        }

        return null;
    }

    /**
     * @param string $prefix
     * @param self   $routes
     *
     * @return Route[]
     */
    private function doMerge(string $prefix, self $routes): array
    {
        /** @var Route|RouteCollection $route */
        foreach ($this as $route) {
            if ($route instanceof Route) {
                if (null === $name = $route->getName()) {
                    $name = $base = $route->generateRouteName('');
                    $i    = 0;

                    while ($routes->find($name)) {
                        $name = $base . '_' . ++$i;
                    }
                }

                $routes[] = $route->bind($prefix . $name);
            } else {
                $route->doMerge($prefix . $route->namePrefix, $routes);
            }
        }

        return $routes->getArrayCopy();
    }
}