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

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)

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

route_param(NAME)

Return's 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');
};

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.

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 a URI::Fast object, if you have the URI::Fast module installed and your app turned on this 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.