Exceptions

This page documents all exceptions thrown by the hypervel/router package, including when they occur, their error messages, and their relationships to the routing system's core components.

For information about the middleware that triggers these exceptions, see Middleware System. For details about parameter binding that may throw resolution exceptions, see Route Parameter Binding and Model Binding and UrlRoutable.

---

Exception Overview

The hypervel/router package defines four custom exceptions, each thrown at specific points in the request lifecycle. These exceptions are organized into three functional categories:

Exception	Category	HTTP Status	Trigger Point
UrlRoutableNotFoundException	Parameter Resolution	N/A (runtime)	Model binding fails in SubstituteBindings
BackedEnumCaseNotFoundException	Parameter Resolution	N/A (runtime)	Enum binding fails in SubstituteBindings
InvalidSignatureException	Security	403	Signature validation fails in ValidateSignature
InvalidMiddlewareExclusionException	Configuration	N/A (config)	Invalid middleware exclusion syntax

Sources: src/Exceptions/UrlRoutableNotFoundException.php1-18 src/Exceptions/BackedEnumCaseNotFoundException.php1-18 src/Exceptions/InvalidSignatureException.php1-18 src/Exceptions/InvalidMiddlewareExclusionException.php1-22

---

Exception Hierarchy and Base Classes

The exception hierarchy reveals three inheritance patterns:

• Parameter resolution exceptions extend RuntimeException directly, indicating runtime failures during request processing
• Security exceptions extend HttpException, enabling automatic HTTP 403 responses
• Configuration exceptions extend InvalidArgumentException, indicating developer configuration errors

Sources: src/Exceptions/UrlRoutableNotFoundException.php9 src/Exceptions/BackedEnumCaseNotFoundException.php9 src/Exceptions/InvalidSignatureException.php9 src/Exceptions/InvalidMiddlewareExclusionException.php9

---

Parameter Resolution Exceptions

These exceptions are thrown by the SubstituteBindings middleware when route parameters cannot be resolved to their target types. They occur during the parameter resolution phase after route matching completes.

UrlRoutableNotFoundException

Namespace: Hypervel\Router\Exceptions\UrlRoutableNotFoundException

Thrown when: A route parameter bound to a model implementing UrlRoutable cannot be resolved to an instance. This occurs when the database query returns no results for the given route key.

Constructor signature:

__construct(string $class, string $routeKey)

Error message format:

No query results for url routable [{$class}] {$routeKey}.

Example scenario: A route defined as /users/{user} with {user} bound to a User model. If the request is /users/999 and no user with route key 999 exists, this exception is thrown.

Sources: src/Exceptions/UrlRoutableNotFoundException.php1-18

---

BackedEnumCaseNotFoundException

Namespace: Hypervel\Router\Exceptions\BackedEnumCaseNotFoundException

Thrown when: A route parameter typed as a BackedEnum receives a value that doesn't match any enum case. The SubstituteBindings middleware attempts to resolve the parameter using BackedEnum::tryFrom(), and this exception is thrown when resolution fails.

Constructor signature:

__construct(string $class, string $case)

Error message format:

Case [{$case}] not found on Backed Enum [{$class}].

Example scenario: A route with parameter typed as Status enum (with cases ACTIVE, INACTIVE). If the request provides /items/pending, and pending is not a valid enum value, this exception is thrown.

Sources: src/Exceptions/BackedEnumCaseNotFoundException.php1-18

---

Exception Flow in Parameter Binding

Sources: src/Exceptions/UrlRoutableNotFoundException.php1-18 src/Exceptions/BackedEnumCaseNotFoundException.php1-18

---

Security Exceptions

InvalidSignatureException

Namespace: Hypervel\Router\Exceptions\InvalidSignatureException

Base class: HttpException (HTTP status 403)

Thrown when: The ValidateSignature middleware detects an invalid or expired signature on a signed URL. This occurs when:

• The signature parameter doesn't match the computed HMAC
• The URL has expired (for temporary signed routes)
• Required signature parameters are missing

Constructor signature:

__construct()

Error message: Invalid signature.

HTTP status code: 403 Forbidden

The exception is raised at src/Middleware/ValidateSignature.php64 when hasValidSignatureWhileIgnoring() returns false:

Sources: src/Exceptions/InvalidSignatureException.php1-18 src/Middleware/ValidateSignature.php56-65

---

Configuration Exceptions

InvalidMiddlewareExclusionException

Namespace: Hypervel\Router\Exceptions\InvalidMiddlewareExclusionException

Base class: InvalidArgumentException

Thrown when: Middleware exclusion configuration contains middleware parameters. The MiddlewareExclusionManager validates that middleware names in without_middleware arrays do not include parameter notation (e.g., throttle:60,1 is invalid; should be throttle).

Constructor signature:

__construct(string $middleware)

Error message format:

Middleware exclusion '{$middleware}' should not contain parameters. Use '{$name}' instead.

The constructor extracts the base middleware name by splitting on : and provides a corrected suggestion at src/Exceptions/InvalidMiddlewareExclusionException.php16-20:

Example invalid configuration:

Corrected configuration:

Sources: src/Exceptions/InvalidMiddlewareExclusionException.php1-22

---

Exception Triggering Contexts

Sources: src/Middleware/ValidateSignature.php56-65 src/Exceptions/InvalidMiddlewareExclusionException.php1-22

---

Exception Properties and Inspection

Exception Properties Table

Exception	Public Properties	Constructor Parameters	Computed Properties
UrlRoutableNotFoundException	None	$class, $routeKey	Message includes both parameters
BackedEnumCaseNotFoundException	None	$class, $case	Message includes both parameters
InvalidSignatureException	None (inherits from HttpException)	None	Status code: 403, Message: "Invalid signature."
InvalidMiddlewareExclusionException	None	$middleware	Message suggests corrected syntax

All exceptions store their messages in the parent Exception::$message property. The parameter resolution exceptions construct descriptive messages at src/Exceptions/UrlRoutableNotFoundException.php16 and src/Exceptions/BackedEnumCaseNotFoundException.php16 that include the class name and the problematic value.

Sources: src/Exceptions/UrlRoutableNotFoundException.php14-17 src/Exceptions/BackedEnumCaseNotFoundException.php14-17 src/Exceptions/InvalidSignatureException.php14-17 src/Exceptions/InvalidMiddlewareExclusionException.php14-21

---

Exception Usage Patterns

Catching Parameter Resolution Exceptions

When implementing custom error handling for parameter binding failures:

Preventing InvalidSignatureException

The InvalidSignatureException is automatically handled by the framework with a 403 response. To prevent it, ensure signed URLs are generated correctly and haven't expired:

• Use UrlGenerator::signedRoute() or temporarySignedRoute() for URL generation
• Verify signatures with Request::hasValidSignature() before processing
• Configure ignored parameters with ValidateSignature::except() if needed

Avoiding InvalidMiddlewareExclusionException

This exception occurs during route configuration. To avoid it:

• Use middleware base names without parameters in without_middleware
• Extract middleware name from parameterized middleware: throttle:60,1 → throttle
• Configure middleware parameters on the route definition, not in exclusions

Sources: src/Exceptions/InvalidSignatureException.php1-18 src/Exceptions/InvalidMiddlewareExclusionException.php1-22 src/Middleware/ValidateSignature.php1-92

---

Class Location Reference

All exceptions are located in the Hypervel\Router\Exceptions namespace:

Exception Class	File Path	Lines
UrlRoutableNotFoundException	src/Exceptions/UrlRoutableNotFoundException.php	1-18
BackedEnumCaseNotFoundException	src/Exceptions/BackedEnumCaseNotFoundException.php	1-18
InvalidSignatureException	src/Exceptions/InvalidSignatureException.php	1-18
InvalidMiddlewareExclusionException	src/Exceptions/InvalidMiddlewareExclusionException.php	1-22

Sources: src/Exceptions/UrlRoutableNotFoundException.php1-18 src/Exceptions/BackedEnumCaseNotFoundException.php1-18 src/Exceptions/InvalidSignatureException.php1-18 src/Exceptions/InvalidMiddlewareExclusionException.php1-22