> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/router/contracts.md).

# Contracts

This page documents behavior you can rely on when integrating with Router.

## Route definition forms

```php
$route->get('health', function () {
    return response()->json(['ok' => true]);
});

$route->get('posts', 'PostController', 'index');
```

Contract:

* Closure route: closure handler only
* Controller route: controller + non-empty action required
* Handler return value must be `Quantum\Http\Response`

## HTTP methods

Methods are required.

`add()` accepts a pipe-delimited list (example: `GET|POST`) and normalizes values before matching.

## Naming

```php
$route->get('dashboard', 'DashboardController', 'index')->name('dashboard');
```

Contract:

* `name()` must follow a route definition
* names are unique per module
* the same name can exist in another module

## Group contracts

```php
$route->group('account', function ($route) {
    $route->get('profile', 'AccountController', 'profile');
    $route->post('avatar', 'AccountController', 'avatar')
        ->middlewares(['VerifiedUser']);
})->middlewares(['Auth']);
```

Contract:

* Nested groups are rejected
* Shared middleware/cache/rate-limit config should be chained after `group(...)`
* Route-level chaining applies only to that route

## Pattern contracts

Supported segment types:

* `:alpha`
* `:num`
* `:any`

Rules:

* explicit parameter names are alphabetic
* duplicate parameter names in one route are rejected
* optional segments resolve to `null` when absent

## Dispatch contracts

For controller routes:

* the controller is instantiated directly for each dispatch, so constructor-free controllers fit best here
* target action method must exist
* controller action returns `Response`
* action parameters and `__before()` / `__after()` hook parameters are resolved through the DI container
* if `__before()` / `__after()` exist, they run around the action

## Controller request contracts

Use the controller property below when a route should participate in CSRF checks for state-changing request methods:

```php
class AccountController
{
    protected bool $csrfVerification = true;

    public function update(Request $request): Response
    {
        // ...
    }
}
```

When that property is enabled, Router asks the CSRF package to validate the request before the action runs.

## Integration checks

Keep these contracts in mind when wiring routes:

* invalid method declarations
* incomplete controller/action definitions
* duplicate route names in one module
* nested groups
* invalid route parameter names
* non-`Response` handler return values


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/router/contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.