Kelp::Request - Request class for a Kelp application
my $request = Kelp::Request( app => $app, env => $env );
This module provides a convenience layer on top of Plack::Request. It extends it to add several convenience methods.
A reference to the Kelp application.
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');
This hash is initialized with the named placeholders of the path that the current route is processing.
Contains a string name of the route matched for this request. Contains route pattern if the route was not named.
Change of behavior in version 1.04, see below for details
Returns the HTTP parameters of the request. This method delegates all the work to "param" in Plack::Request, except 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:
application/json
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:
HASH
{ ARRAY => [...] } # when JSON contains an array as root element { '' => [...] } # when JSON contains something that's not a reference my $array = $kelp->param('ARRAY');
Since version 1.04, a new application configuration field safe_param is introduced that changes the behavior of this method:
safe_param
Without safe_param, method will produce a warning if used in list context while passing the first argument, but will continue to work the same. This is done to combat a very nasty and easy to make bug:
$kelp->some_function( param1 => $value, param2 => $kelp->param('key'), # BUG, list context );
Since HTTP requests can accept multiple values for the same key, someone could inject additional parameters to the function with the simple query, due to array flattening:
?key=something&key=additional_hash_key&key=additional_hash_value
With safe_param, a call to param with an argument (a key to fetch from the parameters) will no longer return a list but always a scalar value regardless of context, even if there are more than one entries of that name (will then return the last one). This makes usages like the one above perfectly safe.
param
my @array = $kelp->param('name'); # changed, will never return more than one scalar
Since this method has so many ways to use it, you're still encouraged to use other, more specific methods from Plack::Request.
You are strongly advised to introduce safe_param into your configuration as quickly as possible. Currently, a value of 0 is the default, meaning that param will work the same as it did, but produce warnings. In no less than half a year from version 1.04 the old behavior of param will be removed altogether, and safe_param configuration will no longer cause any change in behavior, allowing for its safe removal. Use "cgi_param" if you'd like to retain the old behavior regardless of security risks.
0
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.
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.
Returns the Plack session hash or dies if no Session middleware was included.
Session
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( {} ); }
In your config file:
middleware => ['Session'], middleware_init => { Session => { store => 'File' } }
delete $self->req->session->{'useless'};
$self->req->session( {} );
Returns true if the request was called with XMLHttpRequest.
XMLHttpRequest
Returns true if the request's content type was application/json.
To install Kelp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Kelp
CPAN shell
perl -MCPAN -e shell install Kelp
For more information on module installation, please visit the detailed CPAN module installation guide.