/ 
Leyland-1.000001
River stage zero No dependents
/ Leyland::Exception

NAME

Leyland::Exception - Throwable class for Leyland application exceptions

VERSION

version 1.000001

SYNOPSIS

# in your controllers:

# throw a simple exception
$c->exception({ code => 400, error => "You need to give me your name" })
	unless $c->params->{name};

# you can even render the error according to the requested media type
create_something()
	|| $c->exception({
		code => 500,
		error => "Man, I have no idea what went wrong",
		mimes => {
			'text/html' => 'error.html',
			'application/json' => 'error.json',
		},
	});

# or you can create an error that redirects (don't do this unless
# you have a good reason to, you'd most likely want to use
# $c->res->redirect to redirect requests). The only place where
# this should be acceptable is inside controller methods such
# as auto() and pre_route(), where redirecting responses is not
# yet possible.
$c->exception({
	code => 303,
	error => "The resource you're requesting is available at a different location",
	location => $c->uri_for('/some_other_place'),
});

DESCRIPTION

This module provides Leyland applications the ability to throw HTTP exceptions in a consistent and standard way. Leyland applications are meant to throw standard HTTP errors, like "404 Not Found", "400 Bad Request", "500 Internal Server Error", etc. Check out List of HTTP status codes at Wikipedia for a list of HTTP status codes and their descriptions/use cases (the 4xx and 5xx family of status codes are most relevant).

When your application throws a Leyland::Exception, it is caught and automatically serialized to a format the request accepts (or text if the client doesn't accept anything we support). You can, however, render the errors into views with your application's view class (like Leyland::View::Tenjin), mostly useful for rendering HTML representations of errors inside your application's layout, thus preserving the design of your application even when throwing errors.

While you can use this class to throw errors with any HTTP status code, you really only should do this with the 4xx and 5xx family of status codes. You can, however, throw errors with a 3xx status code, in which case you are also expected to provide a URI to redirect to. You should only use this if you have a good reason to, as it is much more proper to redirect using $c->res->redirect (see "ROUTES" in Leyland::Manual::Controller) for more information.

Note that you don't use this class directly. Instead, to throw exceptions, use exception() in Leyland::Context.

If your application throws an error without calling the exception() method just mentioned, it will still be caught and automatically turned into a 500 Internal Server Error. This makes the most sense, as such errors are most likely to be runtime errors thrown by modules your application uses.

CONSUMES

Throwable

ATTRIBUTES

code

The HTTP status code of the error. Required.

error

An error message describing the error that occured. Optional.

location

A URI to redirect to if this is a redirecting exception.

mimes

A hash-ref of media types and template names to use for rendering the error.

use_layout

A boolean value indicating whether to render the errors inside a layout view (if exception has the "mimes" attribute). Defaults to true.

previous_exception

Consumed from Throwable.

OBJECT METHODS

has_error()

Returns a true value if the "error" attribute has a value.

has_location()

Returns a true value if the "location" attribute has a value.

has_mimes()

Returns a true value if the "mimes" attribute has a value.

has_mime( $mime )

Returns a true value if the "mimes" attribute has a value for the provided mime type.

mime( $mime )

Returns the value of provided mime type from the "mimes" attribute, or undef if it doesn't exist.

name()

Returns the name of the exception. For example, if the error status code is 404, the name will be "Not Found".

hash()

Returns a hash-ref representation of the error. This hash-ref will have the keys error (which will hold the exception code and the exception name, separated by a space, e.g. 404 Not Found), and message, which will hold the error message.

INTERNAL METHODS

The following methods are only to be used internally.

BUILD()

AUTHOR

Ido Perlmuter, <ido at ido50.net>

BUGS

Please report any bugs or feature requests to bug-Leyland at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Leyland. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Leyland::Exception

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010-2014 Ido Perlmuter.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.