NAME

Catalyst::ResponseHelpers - Concise response constructors for Catalyst controllers

SYNOPSIS

use Catalyst::ResponseHelpers qw< :helpers :status >;

sub show_user : Chained('/') PathPart('user') Args(1) {
    my ($c, $id) = @_;
    my $user = load_user($id)
        or return NotFound($c, "The user id <$id> couldn't be found.");
    ...
}

DESCRIPTION

Various helper functions for setting up the current Catalyst::Response object. All response helpers call Catalyst/detach to stop request processing. For clarity in your controller actions, it is nevertheless recommended that you call these helpers as values to return().

EXPORTS

By default, only the helper methods documented below are exported. You may explicitly request them using the :helpers tag.

You may also request :status, which re-exports the :constants from HTTP::Status into your package. This is useful for custom status codes.

FUNCTIONS

ReturnWithMsg($c, $mid)

Redirects to the request’s return parameter, or / if no such parameter exists or if the given URI appears to be external to the app. The given $mid is set as a query parameter, and should be the result of a $c->set_status_msg or $c->set_error_msg call. These context methods are normally provided by Catalyst::Plugin::StatusMessage.

Redirect($c, $action_or_action_path, @args?)

Passes arguments to "uri_for_action" in Catalyst and redirects to the returned URL.

RedirectToUrl($c, $url, $status?)

Redirects to the given URL, with an optional custom status. Status defaults to 302 (HTTP_FOUND).

Ok($c, $status?, $msg?)

Sets a body-less 204 No Content response by default, switching to a 200 OK with a body via "TextPlain" iff a message is provided. Both the status and message may be omitted or provided. If the message is omitted, a body-less response is set.

Note that if you're using Catalyst::Action::RenderView and you specify a status other than 204 but don't provide a message (e.g. Ok($c, 200)), RenderView will intercept the response and try to render a template. This probably isn't what you wanted. A workaround is to use the proper status code when sending no content (204) or specify a message (the empty string is OK).

Forbidden($c, $msg?)

Sets a plain text 403 Forbidden response, with an optional custom message.

NotFound($c, $msg?)

Sets a plain text 404 Not Found response, with an optional custom message.

ClientError($c, $status?, $msg?)

Sets a plain text 400 Bad Request response by default, with an optional custom message. Both the status and message may be omitted or provided.

ServerError($c, $status?, $msg?)

Sets a plain text 500 Internal Server Error response by default, with an optional custom message. Both the status and message may be omitted or provided. The error is logged via "log" in Catalyst.

TextPlain($c, $status?, $msg?)

Sets a plain text 200 OK response by default, with an optional custom message. Both the status and message may be omitted or provided.

AsJSON($c, $status?, $data)

Sets a JSON 200 OK response by default, with an optional custom status. Data should be serializable by a view named JSON provided by your application (e.g. via Catalyst::View::JSON).

FromFile($c, $filename, $mime_type, $headers?)

Sets a response from the contents of the filename using the specified MIME type. Content-Length and Last-Modified are set from the file.

The Content-Disposition is set to attachment by default, usually forcing a download.

An optional arrayref of additional headers may also be provided, which is passed through to "FromHandle".

FromCharString($c, $string, $mime_type, $headers?)

Sets a response from the contents of a character string using the specified MIME type. The character string will be encoded as UTF-8 bytes.

The Content-Disposition is set to attachment by default, usually forcing a download.

An optional arrayref of additional headers may also be provided, which is passed through to "FromHandle".

FromHandle($c, $handle, $mime_type, $headers?)

Sets a response from the contents of the filehandle using the specified MIME type. An optional arrayref of additional headers may also be provided, which is passed to the response’s HTTP::Headers object.

The Content-Disposition is set to attachment by default, usually forcing a download.

AUTHOR

Thomas Sibley <trsibley@uw.edu>

THANKS

Inspired in part by seeing John Napiorkowski’s (jnap) experimental response helpers in CatalystX::Example::Todo.

COPYRIGHT

Copyright 2015- by the University of Washington

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.