NAME

Web::Response - common response class for web frameworks

VERSION

version 0.11

SYNOPSIS

  use Web::Request;

  my $app = sub {
      my ($env) = @_;
      my $req = Web::Request->new_from_env($env);
      # ...
      return $req->new_response(status => 404)->finalize;
  };

DESCRIPTION

Web::Response is a response class for PSGI applications. Generally, you will want to create instances of this class via new_response on the request object, since that allows a framework which subclasses Web::Request to also return an appropriate subclass of Web::Response.

All attributes on Web::Response objects are writable, and the final state of them will be used to generate a real PSGI response when finalize is called.

METHODS

status($status)

Sets (and returns) the status attribute, as described above.

headers($headers)

Sets (and returns) the headers attribute, as described above.

header($name, $val)

Shortcut for $ret->headers->header($name, $val).

content_length($length)

Shortcut for $ret->headers->content_length($length).

content_type($type)

Shortcut for $ret->headers->content_type($type).

content_encoding($encoding)

Shortcut for $ret->headers->content_encoding($encoding).

location($location)

Shortcut for $ret->headers->header('Location', $location).

content($content)

Sets (and returns) the content attribute, as described above.

streaming_response

Sets and returns the streaming response coderef, as described above.

has_streaming_response

Returns whether or not a streaming response was provided.

cookies($cookies)

Sets (and returns) the cookies attribute, as described above.

has_cookies

Returns whether or not any cookies have been defined.

redirect($location, $status)

Sets the Location header to $location, and sets the status code to $status (defaulting to 302 if not given).

finalize

Returns a valid PSGI response, based on the values given. This can be either an arrayref or a coderef, depending on if an immediate or streaming response was provided. If both were provided, the streaming response will be preferred.

to_app

Returns a PSGI application which just returns the response in this object directly.

CONSTRUCTOR

new(%params)

Returns a new Web::Response object. Valid parameters are:

status

The HTTP status code for the response.

headers

The headers to return with the response. Can be provided as an arrayref, a hashref, or an HTTP::Headers object. Defaults to an HTTP::Headers object with no contents.

content

The content of the request. Can be provided as a string, an object which overloads "", an arrayref containing a list of either of those, a filehandle, or an object that implements the getline and close methods. Defaults to [].

streaming_response

Instead of status/headers/content, you can provide a coderef which implements the streaming response API described in the PSGI specification.

cookies

A hashref of cookies to return with the response. The values in the hashref can either be the string values of the cookies, or a hashref whose keys can be any of value, domain, path, expires, max-age, secure, httponly. In addition to the date format that expires normally uses, expires can also be provided as a UNIX timestamp (an epoch time, as returned from time). Defaults to {}.

In addition, a single parameter which is a valid PSGI response (a three element arrayref or a coderef) will also be accepted, and will populate the attributes as appropriate. If an arrayref is passed, the first element will be stored as the status attribute, the second element if it exists will be interpreted as in the PSGI specification to create an HTTP::Headers object and stored in the headers attribute, and the third element if it exists will be stored as the content attribute. If a coderef is passed, it will be stored in the streaming_response attribute.

AUTHOR

Jesse Luehrs <doy@tozt.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jesse Luehrs.

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