lib/Catalyst/ActionRole/HTTPMethods.pm

   1 package Catalyst::ActionRole::HTTPMethods;
   2
   3 use Moose::Role;
   4
   5 requires 'match', 'match_captures', 'list_extra_info';
   6
   7 around ['match','match_captures'] => sub {
   8   my ($orig, $self, $ctx, @args) = @_;
   9   my $expected = $self->_normalize_expected_http_method($ctx->req);
  10   return $self->_has_expected_http_method($expected) ?
  11     $self->$orig($ctx, @args) :
  12     0;
  13 };
  14
  15 sub _normalize_expected_http_method {
  16   my ($self, $req) = @_;
  17   return $req->header('X-HTTP-Method') ||
  18     $req->header('X-HTTP-Method-Override') ||
  19     $req->header('X-METHOD-OVERRIDE') ||
  20     $req->method;
  21 }
  22
  23 sub _has_expected_http_method {
  24   my ($self, $expected) = @_;
  25   return 1 unless scalar(my @allowed = $self->allowed_http_methods);
  26   return scalar(grep { lc($_) eq lc($expected) } @allowed) ?
  27     1 : 0;
  28 }
  29
  30 sub allowed_http_methods { @{shift->attributes->{Method}||[]} }
  31
  32 around 'list_extra_info' => sub {
  33   my ($orig, $self, @args) = @_;
  34   return {
  35     %{ $self->$orig(@args) },
  36     HTTP_METHODS => [sort $self->allowed_http_methods],
  37   };
  38 };
  39
  40 1;
  41
  42 =head1 NAME
  43
  44 Catalyst::ActionRole::HTTPMethods - Match on HTTP Methods
  45
  46 =head1 SYNOPSIS
  47
  48     package MyApp::Web::Controller::MyController;
  49
  50     use Moose;
  51     use MooseX::MethodAttributes;
  52
  53     extends 'Catalyst::Controller';
  54
  55     sub user_base : Chained('/') CaptureArg(0) { ... }
  56
  57       sub get_user    : Chained('user_base') Args(1) GET { ... }
  58       sub post_user   : Chained('user_base') Args(1) POST { ... }
  59       sub put_user    : Chained('user_base') Args(1) PUT { ... }
  60       sub delete_user : Chained('user_base') Args(1) DELETE { ... }
  61       sub head_user   : Chained('user_base') Args(1) HEAD { ... }
  62       sub option_user : Chained('user_base') Args(1) OPTION { ... }
  63       sub option_user : Chained('user_base') Args(1) PATCH { ... }
  64
  65
  66       sub post_and_put : Chained('user_base') POST PUT Args(1) { ... }
  67       sub method_attr  : Chained('user_base') Method('DELETE') Args(0) { ... }
  68
  69     __PACKAGE__->meta->make_immutable;
  70
  71 =head1 DESCRIPTION
  72
  73 This is an action role that lets your L<Catalyst::Action> match on standard
  74 HTTP methods, such as GET, POST, etc.
  75
  76 Since most web browsers have limited support for rich HTTP Method vocabularies
  77 we also support setting the expected match method via the follow non standard
  78 but widely used http extensions.  Our support for these should not be taken as
  79 an endorsement of the technique.   Rt is merely a reflection of our desire to
  80 work well with existing systems and common client side tools.
  81
  82 =over 4
  83
  84 =item X-HTTP-Method (Microsoft)
  85
  86 =item X-HTTP-Method-Override (Google/GData)
  87
  88 =item X-METHOD-OVERRIDE (IBM)
  89
  90 =back
  91
  92 Please note the insanity of overriding a GET request with a DELETE override...
  93 Rational practices suggest that using POST with overrides to emulate PUT and
  94 DELETE can be an acceptable way to deal with client limitations and security
  95 rules on your proxy server. I recommend going no further.
  96
  97 =head1 REQUIRES
  98
  99 This role requires the following methods in the consuming class.
 100
 101 =head2 match
 102
 103 =head2 match_captures
 104
 105 Returns 1 if the action matches the existing request and zero if not.
 106
 107 =head1 METHODS
 108
 109 This role defines the following methods
 110
 111 =head2 match
 112
 113 =head2 match_captures
 114
 115 Around method modifier that return 1 if the request method matches one of the
 116 allowed methods (see L</http_methods>) and zero otherwise.
 117
 118 =head2 allowed_http_methods
 119
 120 An array of strings that are the allowed http methods for matching this action
 121 normalized as noted above (using X-Method* overrides).
 122
 123 =head2 list_extra_info
 124
 125 Adds a key => [@values] "HTTP_METHODS" whose value is an ArrayRef of sorted
 126 allowed methods to the ->list_extra_info HashRef.  This is used primarily for
 127 debugging output.
 128
 129 =head2 _has_expected_http_method ($expected)
 130
 131 Private method which returns 1 if C<$expected> matches one of the allowed
 132 in L</http_methods> and zero otherwise.
 133
 134 =head1 AUTHORS
 135
 136 Catalyst Contributors, see Catalyst.pm
 137
 138 =head1 COPYRIGHT
 139
 140 This library is free software. You can redistribute it and/or modify it under
 141 the same terms as Perl itself.
 142
 143 =cut