NAME

VERSION

SYNOPSIS

Actually, you probably want to use HTTP::Throwable::Factory, so here's a sample of how that works:

  use HTTP::Throwable::Factory qw(http_throw http_exception);

  # you can just throw a generic exception...
  HTTP::Throwable::Factory->throw({
      status_code => 500,
      reason      => 'Internal Server Error',
      message     => 'Something has gone very wrong!'
  });

  # or with a little sugar...
  http_throw({
      status_code => 500,
      reason      => 'Internal Server Error',
      message     => 'Something has gone very wrong!'
  });


  # ...but it's much more convenient to throw well-defined exceptions, like
  # this:

  http_throw(InternalServerError => {
    message => 'Something has gone very wrong!',
  });

  # or you can use the exception objects as PSGI apps:
  builder {
      mount '/old' => http_exception(MovedPermanently => { location => '/new' }),
      # ...
  };

DESCRIPTION

This particular package (HTTP::Throwable) is the shared role for all the exceptions involved. It's not intended that you use HTTP::Throwable directly, although you can, and instructions for using it correctly are given below. Instead, you probably want to use HTTP::Throwable::Factory, which will assemble exception classes from roles needed to build an exception for your use case.

For example, you can throw a redirect:

  use HTTP::Throwable::Factory qw(http_throw);

  http_throw(MovedPermanently => { location => '/foo-bar' });

...or a generic fully user-specified exception...

  http_throw({
    status_code => 512,
    reason      => 'Server on fire',
    message     => "Please try again after heavy rain",
  });

For a list of pre-defined, known errors, see "WELL-KNOWN TYPES" below. These types will have the correct status code and reason, and will understand extra status-related arguments like redirect location or authentication realms.

For information on using HTTP::Throwable directly, see "COMPOSING WITH HTTP::THROWABLE", below.

ATTRIBUTES

METHODS

WELL-KNOWN TYPES

The implementation for each of these is in a role with a name in the form "HTTP::Throwable::Role::Status::STATUS-NAME". For example, "Gone" is "HTTP::Throwable::Role::Status::Gone". When throwing the exception with the factory, just pass "Gone"

COMPOSING WITH HTTP::THROWABLE

HTTP::Throwable is mostly concerned about providing basic headers and a PSGI representation. It doesn't worry about the body or a stringification. You must provide the methods "body" and "body_headers" and "as_string".

The "body" method returns the string (of octets) to be sent as the HTTP entity. That body is passed to the "body_headers" method, which must return an arrayref of headers to add to the response. These will generally include the Content-Type and Content-Length headers.

The "as_string" method should return a printable string, even if the body is going to be empty.

For convenience, these three methods are implemented by the roles HTTP::Throwable::Role::TextBody and HTTP::Throwable::Role::NoBody.

SEE ALSO

• <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>
• Plack::Middleware::HTTPExceptions

AUTHORS

• Stevan Little <stevan.little@iinteractive.com>
• Ricardo Signes <rjbs@cpan.org>

CONTRIBUTORS

• Brian Cassidy <bricas@cpan.org>
• Chris Prather <chris@prather.org>
• Edward Betts <edward@4angle.com>
• Fitz Elliott <felliott@fiskur.org>
• Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE

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