NAME

PlackX::Framework::Request - A subclass of Plack::Request

Differences from Plack::Request

This module adds some additional methods, and changes the behavior of the param() method to only return a scalar. The original behavior is provided by cgi_param().

# Safe! param always returns scalar
my %okay_hash = (
  key => $request->param('key')
);

# Not safe! cgi_param may return empty list or multiple values!
my %bad_hash = (
  key => $request->cgi_param('key')
);

# ?color=red&color=green&color=blue
my @colors = $request->cgi_param('color'); # red, green, blue

Please see the documentation for Plack::Request for more ways to get params, e.g. the parameters() method, which is unchanged here.

In addition, this class has a destination() method, which returns the path_info or a path set manually via the reroute() method. See below.

CLASS METHODS

max_reroutes()

Returns the maximum number of PlackX::Framework "re-routes." By default, this is 16. As this is a class method, the only way to change it is to override the method in your subclass.

package MyApp::Request {
  sub max_reroutes() { 1 }
}

GlobalRequest()

If your app's subclass of PlackX::Framework::Handler overrides the use_global_request_response() method to return a true value, PXF will set up a global $request object, which can be accessed here.

This feature is turned off by default to avoid action-at-a-distance bugs. It is preferred to use the request object instance passed to the route's subroutine.

package MyApp { use PlackX::Framework; }
package MyApp::Handler { use_global_request_response { 1 } }
package MyApp::Routes {
  use MyApp::Router;
  route '/someroute' => sub ($request, $response) {
    my $g_request = MyApp::Request->GlobalRequest();
    # $request and $g_request "should" be the same object
    ...
  };
}

Attempting to use this method when the feature is turned off will result in an error, most like of the "not an arrayref" variety.

OBJECT METHODS

abs_to(STR), rel_to(STR)

Returns a URI with (abs_to) or without (rel_to) the http scheme, host, and (if necessary) the port, which are derived from the PSGI environment.

app_rel_to(STR), route_rel_to(STR)

Returns a URI relative to the app or route, if an app_base or route base has been defined. For example, if your app has defined an app_base of '/app-base', and your route has defined a base of '/route-base', these methods will return:

app_rel_to('/')   # /app-base
route_rel_to('/') # /app-base/route-bsae
rel_to('/')       # /

Internally, these methods rely on app_base() and route_base() methods described below.

app_abs_to(STR), route_abs_to(STR)

Like app_rel_to() and route_rel_to(), but with the HTTP scheme, host, and (if necessary) the port.

app_base(), route_base()

Returns the PXF application's app_base (or uri_prefix) and the route's base() as set with the 'base' DSL keyword. These are set by PlackX::Framework::Handler, during request processing, and will be undef in a new object instantiated directly from PlackX::Framework::Request.

param(NAME)

Unlike Plack::Request, our param() method always returns a single scalar value. If you want the original behavior, which was modeled after CGI.pm, you can call cgi_param().

cgi_param(NAME)

Equivalent to Plack::Request's param(), which may return a scalar or list, depending on context, like CGI.pm or the mod_perl Apache request object.

route_param(NAME)

Returns the value of a route parameter, parsed by PlackX::Framework's router engine. For example:

route '/{page_name}' => sub ($request, $response) {
  my $page_name = $request->route_param('page_name');
};

At this time, route parameters do not get merged into the general parameters list, and cannot be obtained with the param() method (or the parent class parameters() method), even if the route param name is unique.

stash_param(NAME)

Accesses the request/response cycle's stash hashref, returning the value based on the given key. For example:

# Somewhere, like a route filter
$request->stash->{session} = $session;

# Somewhere else
my $session = $request->stash_param('session');

# The above is just a shortcut for
my $session = $request->stash->{'session'};

flash()

Gets the content of the PXF app's flash cookie, if set on the previous request. This feature is meant to help pass messages to users, and should not be used to store any information that might be subject to security concerns. If the flash was automatically encoded to a JSON string by PXF::Response, it is automatically decoded.

flash_cookie_name()

Returns the name of the PXF app's flash cookie, which should be unique per app, as it is based on the md5 of the app's namespace. This method is used internally, and there should be no need to access or override it in your app.

is_get(), is_post(), is_put(), is_delete()

Returns true if the HTTP request was a GET, POST, PUT, or DELETE request. This is syntactic sugar for $request->method eq $verb;

is_ajax()

Returns true if the HTTP X-Requested-With header is set as expected for an AJAX request.

destination()

Returns the request's path_info, or the app's alternative destination, if set using the reroute() method.

reroute(URL)

Sets the destination to URL and returns the modified request object.

# In a route sub:
route '/old/url' => sub ($request, $response) {
  return $request->reroute('/new/url');
};

When PlackX::Framework::Handler receives a request object as a response, instead of a response object, request processing will start over with the new route. Think of this as an internal redirect (which does not issue an HTTP redirect to the user).

For debugging, you can access a list of reroutes through the $request->{reroutes} hash key, which may be undefined or an arrayref. Routes are remembered in order from oldest to newest.

urix()

Returns a new instance of your app's subclass of PlackX::Framework::URIx if you have turned on the URIx feature.

package MyApp {
  use PlackX::Framework qw(:URIx); # or :all
  use MyApp::Router;
  route '/seomwhere' => sub ($request, $response) {
    my $uri_fast = $request->urix;
    ...
  };
}

META

For author, copyright, and license, see PlackX::Framework.