File Coverage

lib/Mojolicious/Plugin/RESTRoutes.pm

Criterion	Covered	Total	%
statement	38	39	97.4
branch	9	12	75.0
condition	6	8	75.0
subroutine	5	5	100.0
pod	1	1	100.0
total	59	65	90.7

use Modern::Perl; # strict, warnings etc.;
package Mojolicious::Plugin::RESTRoutes;
# ABSTRACT: routing helper for RESTful operations
# VERSION
$Mojolicious::Plugin::RESTRoutes::VERSION = '0.010012';
use Mojo::Base 'Mojolicious::Plugin';

#pod =encoding utf8
#pod
#pod =head1 DESCRIPTION
#pod
#pod This Mojolicious plugin adds a routing helper for
#pod Lful
#pod L
#pod operations via HTTP to the app.
#pod
#pod The routes are intended, but not restricted to be used by AJAX applications.
#pod
#pod =cut

use Lingua::EN::Inflect qw/PL/;

#pod =method register
#pod
#pod Adds the routing helper. Is called by Mojolicious.
#pod
#pod =cut
sub register {
	my ($self, $app) = @_;

#pod =mojo_short rest_routes
#pod
#pod Can be used to easily generate the needed RESTful routes for a resource.
#pod
#pod 	my $r = $self->routes;
#pod 	my $userroute = $r->rest_routes(name => 'user');
#pod
#pod 	# Installs the following routes (given that $r->namespaces == ['My::Mojo']):
#pod 	#    GET /users                      --> My::Mojo::User::rest_list()
#pod 	#   POST /users                      --> My::Mojo::User::rest_create()
#pod 	#    GET /users/:userid              --> My::Mojo::User::rest_show()
#pod 	#    PUT /users/:userid              --> My::Mojo::User::rest_update()
#pod 	# DELETE /users/:userid              --> My::Mojo::User::rest_remove()
#pod
#pod I: the english plural form of the given C attribute will be
#pod used in the route, i.e. "users" instead of "user". If you want to specify
#pod another string, see parameter C below.
#pod
#pod You can also chain C:
#pod
#pod 	$userroute->rest_routes(name => 'hat', readonly => 1);
#pod
#pod 	# Installs the following additional routes:
#pod 	#    GET /users/:userid/hats         --> My::Mojo::Hat::rest_list()
#pod 	#    GET /users/:userid/hats/:hatid  --> My::Mojo::Hat::rest_show()
#pod
#pod The target controller has to implement the following methods:
#pod
#pod =for :list
#pod * C
#pod * C
#pod * C
#pod * C
#pod * C
#pod
#pod B
#pod
#pod =over
#pod
#pod =item name
#pod
#pod The name of the resource, e.g. a "user", a "book" etc. This name will be used to
#pod build the route URL as well as the controller name (see example above).
#pod
#pod =item readonly (optional)
#pod
#pod If set to 1, no create/update/delete routes will be created
#pod
#pod =item controller (optional)
#pod
#pod Default behaviour is to use the resource name to build the CamelCase controller
#pod name (this is done by L). You can change this by
#pod directly specifying the controller's name via the I attribute.
#pod
#pod Note that you have to give the real controller class name (i.e. CamelCased or
#pod whatever you class name looks like) including the full namespace.
#pod
#pod 	$r->rest_routes(name => 'user', controller => 'My::Mojo::Person');
#pod
#pod 	# Installs the following routes:
#pod 	#    GET /users         --> My::Mojo::Person::rest_list()
#pod 	#    ...
#pod
#pod =item route (optional)
#pod
#pod Specify a name for the route, i.e. prevent automatic usage of english plural
#pod form of the C parameter as the route component.
#pod
#pod 	$r->rest_routes(name => 'angst', route => 'aengste');
#pod
#pod 	# Installs the following routes (given that $r->namespaces == ['My::Mojo']):
#pod 	#    GET /aengste       --> My::Mojo::Angst::rest_list()
#pod
#pod =back
#pod
#pod B
#pod
#pod There are two ways to retrieve the IDs given by the client in your C,
#pod C and C methods.
#pod
#pod Example request: C
#pod
#pod 1. New way: the stash entry C holds a hash with all ids:
#pod
#pod 	package My::Mojo::Hats;
#pod 	use Mojo::Base 'Mojolicious::Controller';
#pod
#pod 	sub rest_show {
#pod 		use Data::Dump qw(dump);
#pod 		print dump($self->stash('fm.ids'));
#pod
#pod 		# { user => 5, hat => 'no9' }
#pod 	}
#pod
#pod 2. Old way: for each resource there will be a parameter C<***id>, e.g.:
#pod
#pod 	package My::Mojo::Hat;
#pod 	use Mojo::Base 'Mojolicious::Controller';
#pod
#pod 	sub rest_show {
#pod 		my ($self) = @_;
#pod 		my $user = $self->param('userid');
#pod 		my $hat = $self->param('hatid');
#pod 		return $self->render(text => "$userid, $hatid");
#pod
#pod 		# text: "5, no9"
#pod 	}
#pod
#pod Furthermore, the parameter C holds the name of the last ID in the route:
#pod
#pod 	package My::Mojo::Hat;
#pod 	use Mojo::Base 'Mojolicious::Controller';
#pod
#pod 	sub rest_show   {
#pod 		my $p_name = $self->param('idname');
#pod 		my $id = $self->param($p_name);
#pod 		return $self->render(text => sprintf("%s = %s", $p_name, $id || ''));
#pod
#pod 		# text: "hatid = 5"
#pod 	}
#pod
#pod =cut
	# For the following TODOs also see http://pastebin.com/R9zXrtCg
	# TODO Add GET /users/new            --> rest_create_user_form
	# TODO Add GET /users/:userid/edit   --> rest_edit_user_form
	# TODO Add GET /users/:userid/delete --> rest_delete_user_form
	# TODO Add GET /users/search         --> rest_search_user_form
	# TODO Add PUT /users/search/:term   --> rest_search_user_form (submit/execution)
	$app->routes->add_shortcut(
		rest_routes => sub {
			my $r = shift;
			my $params = { @_ ? (ref $_[0] ? %{ $_[0] } : @_) : () };

			my $name = $params->{name} or die "Parameter 'name' missing";
			my $readonly = $params->{readonly} || 0;
			my $controller = $params->{controller} || $name;
			my $route_part = $params->{route} || PL($name, 10); # build english plural form

			$app->log->info("Creating REST routes for resource '$name' (controller: $controller)");

			#
			# Generate "/$name" route, handled by controller $name
			#
			my $resource = $r->route("/$route_part")->to(controller => $controller);

			# GET requests - lists the collection of this resource
			$resource->get->to('#rest_list')->name("list_$route_part");
			$app->log->debug("Created route    GET ".$r->to_string."/$route_part   (rest_list)");

			if (!$readonly) {
				# POST requests - creates a new resource
				$resource->post->to('#rest_create')->name("create_$name");
				$app->log->debug("Created route   POST ".$r->to_string."/$route_part   (rest_create)");
			};

			#
			# Generate "/$name/:id" route, also handled by controller $name
			#

			# resource routes might be chained, so we need to define an
			# individual id and pass its name to the controller (idname)
			$resource = $r
			->under("/$route_part/:${name}id" => sub {
				my ($c) = @_;
				$c->app->log->debug(sprintf("Feeding ID into stash: \$c->stash('fm.ids')->{'%s'} = %s", $name, $c->param("${name}id")));
				$c->stash('fm.ids' => {}) unless $c->stash('fm.ids');
				$c->stash('fm.ids')->{$name} = $c->param("${name}id");
				return 1;
			})
			->to(controller => $controller, idname => "${name}id");

			# GET requests - lists a single resource
			$resource->get->to("#rest_show")->name("show_$name");
			$app->log->debug("Created route    GET ".$r->to_string."/$route_part/:${name}id   (rest_show)");

			if (!$readonly) {
				# DELETE requests - deletes a resource
				$resource->delete->to('#rest_remove')->name("delete_$name");
				$app->log->debug("Created route DELETE ".$r->to_string."/$route_part/:${name}id   (rest_delete)");

				# PUT requests - updates a resource
				$resource->put->to('#rest_update')->name("update_$name");
				$app->log->debug("Created route    PUT ".$r->to_string."/$route_part/:${name}id   (rest_update)");
			}

			# return "/$name/:id" route so that potential child routes make sense
			return $resource;
		}
	);
}

1;

__END__