/ 
PAGI-FastAPI-v0.1.0
/ PAGI::FastAPI::Context

NAME

PAGI::FastAPI::Context - Request and Response Lifecycle Context for PAGI::FastAPI

VERSION

Version v0.1.0

SYNOPSIS

# Inspecting Request Parameters
my $user_id = $c->path_param('id');
my $limit   = $c->query_param('limit');
my $name    = $c->body('name');

# Generic Parameter Fallback (Path -> Query -> Body)
my $token   = $c->param('token');

# Headers & Scope
my $ua      = $c->header('User-Agent');
my $scope   = $c->scope;

# Stash Storage
$c->stash->{user} = { id => 42, role => 'admin' };

# Modifying Response State
$c->status(201);
$c->set_header('X-Custom-Header' => 'value');

DESCRIPTION

PAGI::FastAPI::Context encapsulates the request environment, parsed parameters, payload data, and response state for an individual HTTP exchange processed by PAGI::FastAPI.

An instance of this context is passed as the primary argument to route handlers, middleware functions, and dependency blocks.

METHODS

new(%args)

Constructor called internally by PAGI::FastAPI. Accepts:

  • scope - PAGI environment HashRef.

  • query_params - HashRef of validated query parameters.

  • path_params - HashRef of route path variables.

  • body - Decoded payload body (HashRef, ArrayRef, or Scalar).

  • status - Initial HTTP response code (default: 200).

  • res_headers - Initial response headers ArrayRef (default: []).

  • stash - Context-bound storage HashRef (default: {}).

scope()

Returns the raw PAGI scope HashRef for the current request.

status([ $code ])

Gets or sets the HTTP status code for the response.

$c->status(403);
my $code = $c->status; # 403

res_headers()

Returns the current list of outgoing response header pairs as an ArrayRef of tuple pairs [ [$name, $val], ... ].

set_header($key, $val)

Appends an outgoing HTTP header pair to the response headers list.

$c->set_header('X-Frame-Options' => 'DENY');

header($name)

Case-insensitively searches incoming request headers (from $c->scope->{headers}) and returns its scalar value, or undef if missing.

my $auth = $c->header('Authorization');

path_params()

Returns the HashRef containing all parsed path parameters.

path_param($key)

Returns a specific parsed path parameter by name, or undef if absent.

query_params()

Returns the HashRef containing all parsed query parameters.

query_param($key)

Returns a specific parsed query parameter by name, or undef if absent.

body([ $key ])

If called without parameters, returns the full raw/decoded request body.

If called with a $key parameter and the body is a HashRef, returns the value for that key, or undef if missing or if the body is not a HashRef.

my $full_body = $c->body;
my $user_name = $c->body('username');

param($key)

Convenience parameter accessor that checks parameter stores in priority order:

1. Path parameters (path_param) 2. Query parameters (query_param) 3. JSON/Body fields (body($key))

Returns the first matching non-undef value, or undef if the key is not present in any store.

stash()

Returns a HashRef tied to the lifecycle of this context. Useful for sharing data between middleware, dependency injection blocks, and final route handlers.

$c->stash->{db_session} = $db;

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::Context

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0