NAME
Kelp::Request - Request class for a Kelp application
SYNOPSIS
my $request = Kelp::Request( app => $app, env => $env );
DESCRIPTION
This module provides a convenience layer on top of Plack::Request. It extends it to add several convenience methods.
ATTRIBUTES
app
A reference to the Kelp application.
stash
Returns a hashref, which represents the stash of the current the request
An all use, utility hash to use to pass information between routes. The stash is a concept originally conceived by the developers of Catalyst. It's a hash that you can use to pass data from one route to another.
# put value into stash
$self->req->stash->{username} = app->authenticate();
# more convenient way
$self->stash->{username} = app->authenticate();
# get value from stash
return "Hello " . $self->req->stash->{username};
# more convenient way
return "Hello " . $self->stash('username');
named
This hash is initialized with the named placeholders of the path that the current route is processing.
route_name
Contains a string name of the route matched for this request. Contains route pattern if the route was not named.
param
Returns the HTTP parameters of the request. It has two modes of operation. Normally, it behaves like "param" in Plack::Request, but has no context sensivity vulnerability - will always return a list when called without parameters and a scalar when called with a parameter.
The behavior is changed when the content type of the request is application/json
and a JSON module is loaded. In that case, it will decode the JSON body and return as follows:
If no arguments are passed, then it will return the names of the HTTP parameters when called in array contest, and a reference to the entire JSON hash when called in scalar context.
# JSON body = { bar => 1, foo => 2 } my @names = $self->param; # @names = ('bar', 'foo') my $json = $self->param; # $json = { bar => 1, foo => 2 }
If a single argument is passed, then the corresponding value in the JSON document is returned.
my $bar = $self->param('bar'); # $bar = 1
If the root contents of the JSON document is not an
HASH
(after decoding), then it will be wrapped into a hash with its reftype as a key, for example:{ ARRAY => [...] } # when JSON contains an array as root element { '' => [...] } # when JSON contains something that's not a reference my $array = $kelp->param('ARRAY');
Since this method has so many ways to use it, you're encouraged to use other, more specific methods from Plack::Request.
cgi_param
Calls param
in Plack::Request, which is CGI.pm compatible. It is not recommended to use this method, unless for some reason you have to maintain CGI.pm compatibility. Misusing this method can lead to bugs and security vulnerabilities.
address, remote_host, user
These are shortcuts to the REMOTE_ADDR, REMOTE_HOST and REMOTE_USER environment variables.
if ( $self->req->address eq '127.0.0.1' ) {
...
}
Note: See "Deploying" in Kelp::Cookbook for configuration required for these fields when using a proxy.
session
Returns the Plack session hash or dies if no Session
middleware was included.
sub get_session_value {
my $self = shift;
$self->session->{user} = 45;
}
If called with a single argument, returns that value from the session hash:
sub set_session_value {
my $self = shift;
my $user = $self->req->session('user');
# Same as $self->req->session->{'user'};
}
Set values in the session using key-value pairs:
sub set_session_hash {
my $self = shift;
$self->req->session(
name => 'Jill Andrews',
age => 24,
email => 'jill@perlkelp.com'
);
}
Set values using a Hashref:
sub set_session_hashref {
my $self = shift;
$self->req->session( { bar => 'foo' } );
}
Clear the session:
sub clear_session {
my $self = shift;
$self->req->session( {} );
}
Common tasks with sessions
- Initialize file sessions
-
In your config file:
middleware => ['Session'], middleware_init => { Session => { store => 'File' } }
- Delete session value
-
delete $self->req->session->{'useless'};
- Remove all session values
-
$self->req->session( {} );
is_ajax
Returns true if the request was called with XMLHttpRequest
.
is_json
Returns true if the request's content type was application/json
.