Class Yiisoft\Router\Route

All Classes | Methods

Inheritance	Yiisoft\Router\Route
Implements	Stringable
Subclasses	Yiisoft\Router\Route\Delete, Yiisoft\Router\Route\Get, Yiisoft\Router\Route\Head, Yiisoft\Router\Route\Options, Yiisoft\Router\Route\Patch, Yiisoft\Router\Route\Post, Yiisoft\Router\Route\Put

Route defines a mapping from URL to callback / name and vice versa.

Public Methods

Hide inherited methods

Method	Description	Defined By
__construct()	Creates a route.	Yiisoft\Router\Route
__debugInfo()		Yiisoft\Router\Route
__toString()		Yiisoft\Router\Route
action()	Appends action handler. It is a primary middleware definition that should be invoked last for a matched route.	Yiisoft\Router\Route
defaults()	Parameter default values indexed by parameter names.	Yiisoft\Router\Route
delete()		Yiisoft\Router\Route
disableMiddleware()	Excludes middleware from being invoked when action is handled.	Yiisoft\Router\Route
get()		Yiisoft\Router\Route
getData()		Yiisoft\Router\Route
head()		Yiisoft\Router\Route
host()		Yiisoft\Router\Route
hosts()		Yiisoft\Router\Route
methods()		Yiisoft\Router\Route
middleware()	Appends a handler middleware definition that should be invoked for a matched route.	Yiisoft\Router\Route
name()		Yiisoft\Router\Route
options()		Yiisoft\Router\Route
override()	Marks route as override. When added it will replace existing route with the same name.	Yiisoft\Router\Route
patch()		Yiisoft\Router\Route
pattern()		Yiisoft\Router\Route
post()		Yiisoft\Router\Route
prependMiddleware()	Prepends a handler middleware definition that should be invoked for a matched route. Last added handlers will be executed first.	Yiisoft\Router\Route
put()		Yiisoft\Router\Route

Method Details

Hide inherited methods

__construct() public method

Creates a route.

public mixed __construct ( string $pattern, string[] $methods, string\|null $name = null, array\|callable\|string\|null $action = null, array[]\|callable[]\|string[] $middlewares = [], array $defaults = [], string[] $hosts = [], boolean $override = false, array[]\|callable[]\|string[] $disabledMiddlewares = [] )
$pattern	string	URL pattern to match.
$methods	string[]	HTTP methods to match.
$name	string\|null	Route name.
$action	array\|callable\|string\|null	Primary middleware definition that should be invoked last for a matched route.
$middlewares	array[]\|callable[]\|string[]	Handler middleware definitions that should be invoked for a matched route.
$defaults	array	Parameter default values indexed by parameter names.
$hosts	string[]	Hosts that the route applies to.
$override	boolean	Whether the route should replace an existing route with the same name.
$disabledMiddlewares	array[]\|callable[]\|string[]	Middleware definitions to exclude when the action is handled.

Source code

                public function __construct(
    private string $pattern,
    private array $methods,
    private ?string $name = null,
    array|callable|string|null $action = null,
    array $middlewares = [],
    array $defaults = [],
    array $hosts = [],
    private bool $override = false,
    array $disabledMiddlewares = [],
) {
    /** @infection-ignore-all Array keys are discarded by MiddlewareFilter::filter(). */
    $this->middlewares = array_values($middlewares);
    $this->setDefaults($defaults);
    /** @infection-ignore-all Array keys are discarded by MiddlewareFilter::filter(). */
    $this->disabledMiddlewares = array_values($disabledMiddlewares);
    $this->setHosts($hosts);
    if ($action !== null) {
        $this->middlewares[] = $action;
        $this->actionAdded = true;
    }
}

__debugInfo() public method

public mixed __debugInfo ( )

Source code

                public function __debugInfo()
{
    return [
        'name' => $this->name,
        'methods' => $this->methods,
        'pattern' => $this->pattern,
        'hosts' => $this->hosts,
        'defaults' => $this->defaults,
        'override' => $this->override,
        'actionAdded' => $this->actionAdded,
        'middlewares' => $this->middlewares,
        'disabledMiddlewares' => $this->disabledMiddlewares,
        'enabledMiddlewares' => $this->getEnabledMiddlewares(),
    ];
}

__toString() public method

public string __toString ( )

Source code

                public function __toString(): string
{
    $result = $this->name === null
        ? ''
        : '[' . $this->name . '] ';
    if ($this->methods !== []) {
        $result .= implode(',', $this->methods) . ' ';
    }
    if ($this->hosts) {
        $quoted = array_map(static fn($host) => preg_quote($host, '/'), $this->hosts);
        if (!preg_match('/' . implode('|', $quoted) . '/', $this->pattern)) {
            $result .= implode('|', $this->hosts);
        }
    }
    $result .= $this->pattern;
    return $result;
}

action() public method

Appends action handler. It is a primary middleware definition that should be invoked last for a matched route.

public self action ( array\|callable\|string $middlewareDefinition )
$middlewareDefinition	array\|callable\|string

Source code

                public function action(array|callable|string $middlewareDefinition): self
{
    $route = clone $this;
    $route->middlewares[] = $middlewareDefinition;
    $route->actionAdded = true;
    return $route;
}

defaults() public method

Parameter default values indexed by parameter names.

public self defaults ( array $defaults )
$defaults	array

Source code

                public function defaults(array $defaults): self
{
    $route = clone $this;
    $route->setDefaults($defaults);
    return $route;
}

delete() public static method

Deprecated Use new \Yiisoft\Router\Route\Delete() instead.

public static self delete ( string $pattern )
$pattern	string

Source code

                public static function delete(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::DELETE], $pattern);
}

disableMiddleware() public method

Excludes middleware from being invoked when action is handled.

It is useful to avoid invoking one of the parent group middleware for a certain route.

public self disableMiddleware ( mixed $definition )
$definition	mixed

Source code

                public function disableMiddleware(mixed ...$definition): self
{
    $route = clone $this;
    array_push(
        $route->disabledMiddlewares,
        ...array_values($definition),
    );
    $route->enabledMiddlewaresCache = null;
    return $route;
}

get() public static method

Deprecated Use new \Yiisoft\Router\Route\Get() instead.

public static self get ( string $pattern )
$pattern	string

Source code

                public static function get(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::GET], $pattern);
}

getData() public method

public mixed getData ( string $key )
$key	string

Source code

                public function getData(string $key): mixed
{
    return match ($key) {
        'name' => $this->name
            ?? (implode(', ', $this->methods) . ' ' . implode('|', $this->hosts) . $this->pattern),
        'pattern' => $this->pattern,
        'host' => $this->hosts[0] ?? null,
        'hosts' => $this->hosts,
        'methods' => $this->methods,
        'defaults' => $this->defaults,
        'override' => $this->override,
        'hasMiddlewares' => $this->middlewares !== [],
        'enabledMiddlewares' => $this->getEnabledMiddlewares(),
        default => throw new InvalidArgumentException('Unknown data key: ' . $key),
    };
}

head() public static method

Deprecated Use new \Yiisoft\Router\Route\Head() instead.

public static self head ( string $pattern )
$pattern	string

Source code

                public static function head(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::HEAD], $pattern);
}

host() public method

public self host ( string $host )
$host	string

Source code

                public function host(string $host): self
{
    return $this->hosts($host);
}

hosts() public method

public self hosts ( string $hosts )
$hosts	string

Source code

                public function hosts(string ...$hosts): self
{
    $route = clone $this;
    $route->setHosts($hosts);
    return $route;
}

methods() public static method

Deprecated Use new Route(pattern: $pattern, methods: $methods) instead.

public static self methods ( string[] $methods, string $pattern )
$methods	string[]
$pattern	string

Source code

                public static function methods(array $methods, string $pattern): self
{
    if (static::class !== self::class) {
        throw new LogicException(sprintf(
            'Static factory methods are only valid on %s itself, not %s. Use the constructor instead.',
            self::class,
            static::class,
        ));
    }
    return new self($pattern, $methods);
}

middleware() public method

Appends a handler middleware definition that should be invoked for a matched route.

First added handler will be executed first. If no actions have been added, the middleware is added to the end of the list. Otherwise, it is added before the action.

public self middleware ( array\|callable\|string $definition )
$definition	array\|callable\|string

Source code

                public function middleware(array|callable|string ...$definition): self
{
    $route = clone $this;
    if ($this->actionAdded) {
        /**
         * @psalm-suppress PropertyTypeCoercion Keys in the replacement array are not preserved.
         * @infection-ignore-all
         */
        array_splice(
            $route->middlewares,
            offset: count($route->middlewares) - 1,
            length: 0,
            replacement: $definition,
        );
    } else {
        array_push(
            $route->middlewares,
            ...array_values($definition),
        );
    }
    $route->enabledMiddlewaresCache = null;
    return $route;
}

name() public method

public self name ( string\|\BackedEnum $name )
$name	string\|\BackedEnum	Name of the route. A backed enumeration is resolved to its backing value, so the route name is still a string afterwards.

Source code

                public function name(string|BackedEnum $name): self
{
    $route = clone $this;
    $route->name = $name instanceof BackedEnum ? (string) $name->value : $name;
    return $route;
}

options() public static method

Deprecated Use new \Yiisoft\Router\Route\Options() instead.

public static self options ( string $pattern )
$pattern	string

Source code

                public static function options(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::OPTIONS], $pattern);
}

override() public method

Marks route as override. When added it will replace existing route with the same name.

public self override ( )

Source code

                public function override(): self
{
    $route = clone $this;
    $route->override = true;
    return $route;
}

patch() public static method

Deprecated Use new \Yiisoft\Router\Route\Patch() instead.

public static self patch ( string $pattern )
$pattern	string

Source code

                public static function patch(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::PATCH], $pattern);
}

pattern() public method

public self pattern ( string $pattern )
$pattern	string

Source code

                public function pattern(string $pattern): self
{
    $new = clone $this;
    $new->pattern = $pattern;
    return $new;
}

post() public static method

Deprecated Use new \Yiisoft\Router\Route\Post() instead.

public static self post ( string $pattern )
$pattern	string

Source code

                public static function post(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::POST], $pattern);
}

prependMiddleware() public method

Prepends a handler middleware definition that should be invoked for a matched route. Last added handlers will be executed first.

Passed definitions will be added to beginning. For example:

// Resulting middleware stack order: Middleware1, Middleware2, Middleware3
(new \Yiisoft\Router\Route\Get('/'))
  ->middleware(Middleware3::class)
  ->prependMiddleware(Middleware1::class, Middleware2::class)

public self prependMiddleware ( array\|callable\|string $definition )
$definition	array\|callable\|string

Source code

                public function prependMiddleware(array|callable|string ...$definition): self
{
    $route = clone $this;
    array_unshift(
        $route->middlewares,
        ...array_values($definition),
    );
    $route->enabledMiddlewaresCache = null;
    return $route;
}

put() public static method

Deprecated Use new \Yiisoft\Router\Route\Put() instead.

public static self put ( string $pattern )
$pattern	string

Source code

                public static function put(string $pattern): self
{
    /** @psalm-suppress DeprecatedMethod Retain delegation between deprecated factories for compatibility. */
    return self::methods([Method::PUT], $pattern);
}

Class Yiisoft\Router\Route

Public Methods

Method Details

User Contributed Notes

Leave a comment