> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apivalk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Lifecycle

> This page describes the lifecycle of an HTTP request within the Apivalk framework, from the initial entry point to the final response rendering

## Overview

The Apivalk request lifecycle follows a structured path involving routing, request population, middleware execution, and controller dispatching.

```mermaid theme={null}
graph TD
    A[Entry Point: index.php] --> B[Apivalk Configuration]
    B --> C[Apivalk::run]
    C --> D[Router::dispatch]
    D --> E{Route Match?}
    E -- No --> F[404 Not Found]
    E -- Yes --> G[Build Request & Controller]
    G --> H[Request::populate]
    H --> I[Middleware Stack]
    I --> J[Middleware 1]
    J --> K[Middleware N]
    K --> L[Controller::__invoke]
    L --> M[Return Response]
    M --> N[Middleware N Post-process]
    N --> O[Middleware 1 Post-process]
    O --> P[Renderer::render]
    P --> Q[Send Headers & Output]
```

## Stages

### 1. Bootstrapping

The application starts by creating an `ApivalkConfiguration` object. This configuration requires a `Router` and can optionally include a `Renderer`, an `ExceptionHandler`, and a PSR-11 `Container`. The `Apivalk` instance is then initialized with this configuration.

### 2. Application Execution

Calling `$apivalk->run()` initiates the request processing. If an `ExceptionHandler` was configured, it is registered at this stage to catch any unhandled exceptions during the lifecycle.

### 3. Routing

The `Apivalk::run()` method calls `Router::dispatch()`. The router performs the following:

* Extracts the HTTP method and URI path from `$_SERVER`.
* Iterates through cached routes to find a match for the URI.
* If no URI matches, it returns a `NotFoundApivalkResponse` (404).
* If the URI matches but the HTTP method does not, it returns a `MethodNotAllowedApivalkResponse` (405).

### 4. Request & Controller Preparation

Once a route is matched:

* The `Router` identifies the specific `Request` and `Controller` classes associated with the route.
* The `Controller` is instantiated using the `ApivalkControllerFactory` (which integrates with the DI container if available).
* The `Request` object is instantiated.

### 5. Request Population

Before dispatch, the router builds a fully merged `ApivalkRequestDocumentation` for the route via `RequestDocumentationFactory::buildRuntimeDocumentation()`. This combines the request class's base documentation with route-derived properties (pagination query params, filter fields, `order_by`, available sort fields).

The `Request` object's `populate()` method then runs a pipeline of small, single-purpose strategies implementing `PopulationStrategyInterface`. The `RequestPopulationStrategyCollection` wires up the default set:

* `HeaderPopulationStrategy` — extracts headers from `$_SERVER`.
* `QueryParameterPopulationStrategy` — extracts declared query params and filter fields from `$_GET`.
* `PathParameterPopulationStrategy` — parses the URI against the route's path pattern.
* `BodyParameterPopulationStrategy` — decodes `php://input` (JSON) and `$_POST`.
* `FilePopulationStrategy` — builds the file bag from `$_FILES`.
* `SortingPopulationStrategy` — applies route default sortings, then parses `order_by` from `$_GET`.
* `FilteringPopulationStrategy` — clones the route's declared filters and binds values from the query bag.
* `PaginationPopulationStrategy` — builds the correct paginator (page / offset / cursor) when the route declares pagination.
* `AuthIdentityPopulationStrategy` — sets a default `GuestAuthIdentity` (middleware replaces it if auth succeeds).
* `IpPopulationStrategy` — resolves the client IP.
* `MethodPopulationStrategy` — attaches the HTTP method from the route.

Each strategy is independent, easy to test in isolation, and receives a `RequestPopulationContext` carrying the `Route` and the runtime documentation.

### 6. Middleware Pipeline

The `MiddlewareStack` handles the request and controller. It implements an **onion-style** middleware execution:

* Middlewares are executed in the order they were added.
* Each middleware receives the `Request`, the `Controller` instance, and a `$next` callable.
* A middleware can perform actions before passing control to the next layer, or it can short-circuit the request by returning a response immediately.

### 7. Controller Dispatch

The final step in the middleware pipeline is the execution of the Controller itself. Since all Apivalk controllers implement `__invoke()`, they are called with the populated `Request` object. The controller executes the business logic and MUST return an `AbstractApivalkResponse`.

### 8. Response Rendering

The response returned by the middleware stack is passed back to the `run()` method, which returns it to the caller (e.g., your `index.php`). The developer then typically uses the configured `Renderer` to:

* Set the HTTP status code.
* Send the necessary HTTP headers (including `Content-Type: application/json`).
* Serialize the response data (and optional pagination info) to JSON and output it.

### 9. Exception Handling

If an exception is thrown anywhere during the lifecycle and an `ExceptionHandler` is active:

* It catches the `Throwable`.
* It creates an `InternalServerErrorApivalkResponse` (500).
* It uses the `JsonRenderer` to immediately send the error response and exit.