1 package Catalyst::TraitFor::Request::REST::ForBrowsers;
3 use namespace::autoclean;
5 with 'Catalyst::TraitFor::Request::REST';
8 $VERSION = eval $VERSION;
10 has _determined_real_method => (
15 has looks_like_browser => (
19 builder => '_build_looks_like_browser',
23 # All this would be much less gross if Catalyst::Request used a builder to
24 # determine the method. Then we could just wrap the builder.
25 around method => sub {
29 return $self->$orig(@_)
30 if @_ || $self->_determined_real_method;
32 my $method = $self->$orig();
35 if ( defined $method && uc $method eq 'POST' ) {
36 $tunneled = $self->param('x-tunneled-method')
37 || $self->header('x-http-method-override');
40 $self->$orig( defined $tunneled ? uc $tunneled : $method );
42 $self->_determined_real_method(1);
44 return $self->$orig();
48 my %HTMLTypes = map { $_ => 1 } qw(
53 sub _build_looks_like_browser {
56 my $with = $self->header('x-requested-with');
58 if $with && grep { $with eq $_ }
59 qw( HTTP.Request XMLHttpRequest );
61 if ( uc $self->method eq 'GET' ) {
62 my $forced_type = $self->param('content-type');
64 if $forced_type && !$HTMLTypes{$forced_type};
67 # IE7 does not say it accepts any form of html, but _does_
68 # accept */* (helpful ;)
70 if $self->accepts('*/*');
73 if grep { $self->accepts($_) } keys %HTMLTypes;
76 if @{ $self->accepted_content_types() };
78 # If the client did not specify any content types at all,
79 # assume they are a browser.
92 Catalyst::TraitFor::Request::REST::ForBrowsers - A request trait for REST and browsers
98 use Catalyst::TraitFor::Request::REST::ForBrowsers;
104 Writing REST-y apps is a good thing, but if you're also trying to support web
105 browsers, you're probably going to need some hackish workarounds. This module
106 provides those workarounds for you.
108 Specifically, it lets you do two things. First, it lets you "tunnel" PUT and
109 DELETE requests across a POST, since most browsers do not support PUT or
110 DELETE actions (as of early 2009, at least).
112 Second, it provides a heuristic to check if the client is a web browser,
113 regardless of what content types it claims to accept. The reason for this is
114 that while a browser might claim to accept the "application/xml" content type,
115 it's really not going to do anything useful with it, and you're best off
120 This class provides the following methods:
122 =head2 $request->method
124 This method works just like C<< Catalyst::Request->method() >> except it
125 allows for tunneling of PUT and DELETE requests via a POST.
127 Specifically, you can provide a form element named "x-tunneled-method" which
128 can override the request method for a POST. This I<only> works for a POST, not
131 You can also use a header named "x-http-method-override" instead (Google uses
132 this header for its APIs).
134 =head2 $request->looks_like_browser
136 This attribute provides a heuristic to determine whether or not the request
137 I<appears> to come from a browser. You can use this however you want. I
138 usually use it to determine whether or not to give the client a full HTML page
139 or some sort of serialized data.
141 This is a heuristic, and like any heuristic, it is probably wrong
142 sometimes. Here is how it works:
148 If the request includes a header "X-Request-With" set to either "HTTP.Request"
149 or "XMLHttpRequest", this returns false. The assumption is that if you're
150 doing XHR, you don't want the request treated as if it comes from a browser.
154 If the client makes a GET request with a query string parameter
155 "content-type", and that type is I<not> an HTML type, it is I<not> a browser.
159 If the client provides an Accept header which includes "*/*" as an accepted
160 content type, the client is a browser. Specifically, it is IE7, which submits
161 an Accept header of "*/*". IE7's Accept header does not include any html types
166 If the client provides an Accept header and accepts either "text/html" or
167 "application/xhtml+xml" it is a browser.
171 If it provides an Accept header of any sort, it is I<not> a browser.
175 The default is that the client is a browser.
179 This all works well for my apps, but read it carefully to make sure it meets
180 your expectations before using it.
184 Dave Rolsky, C<< <autarch@urth.org> >>
188 Please report any bugs or feature requests to
189 C<bug-catalyst-action-rest@rt.cpan.org>, or through the web interface at
190 L<http://rt.cpan.org>. We will be notified, and then you'll automatically be
191 notified of progress on your bug as I make changes.
193 =head1 COPYRIGHT & LICENSE
195 Copyright 2008-2010 Dave Rolsky, All Rights Reserved.
197 This program is free software; you can redistribute it and/or modify it under
198 the same terms as Perl itself.