Commit | Line | Data |
---|---|---|
6561feae | 1 | use strict; |
2 | use warnings; | |
561098d1 | 3 | |
4 | package Catalyst::Middleware::Stash; | |
5 | ||
6561feae | 6 | use base 'Plack::Middleware'; |
561098d1 | 7 | use Exporter 'import'; |
561098d1 | 8 | use Carp 'croak'; |
9 | ||
10 | our @EXPORT_OK = qw(stash get_stash); | |
6561feae | 11 | |
12 | sub PSGI_KEY { 'Catalyst.Stash.v1' }; | |
13 | ||
300b04ce | 14 | sub get_stash { |
15 | my $env = shift; | |
d3988c05 | 16 | return $env->{&PSGI_KEY} || |
e77ad76e | 17 | _init_stash_in($env); |
300b04ce | 18 | } |
561098d1 | 19 | |
300b04ce | 20 | sub stash { |
21 | my ($host, @args) = @_; | |
22 | return get_stash($host->env) | |
23 | ->(@args); | |
24 | } | |
25 | ||
e77ad76e | 26 | sub _create_stash { |
561098d1 | 27 | my $stash = shift || +{}; |
28 | return sub { | |
29 | if(@_) { | |
30 | my $new_stash = @_ > 1 ? {@_} : $_[0]; | |
31 | croak('stash takes a hash or hashref') | |
32 | unless ref $new_stash; | |
300b04ce | 33 | foreach my $key (keys %$new_stash) { |
561098d1 | 34 | $stash->{$key} = $new_stash->{$key}; |
35 | } | |
36 | } | |
37 | $stash; | |
38 | }; | |
39 | } | |
40 | ||
e77ad76e | 41 | sub _init_stash_in { |
300b04ce | 42 | my ($env) = @_; |
d3988c05 | 43 | return $env->{&PSGI_KEY} ||= |
e77ad76e | 44 | _create_stash; |
6561feae | 45 | } |
46 | ||
47 | sub call { | |
48 | my ($self, $env) = @_; | |
e77ad76e | 49 | _init_stash_in($env); |
6561feae | 50 | return $self->app->($env); |
51 | } | |
52 | ||
0dd88998 | 53 | =head1 NAME |
6561feae | 54 | |
55 | Catalyst::Middleware::Stash - The Catalyst stash - in middleware | |
56 | ||
57 | =head1 DESCRIPTION | |
58 | ||
59 | We've moved the L<Catalyst> stash to middleware. Please don't use this | |
60 | directly since it is likely to move off the Catalyst namespace into a stand | |
61 | alone distribution | |
62 | ||
561098d1 | 63 | We store a coderef under the C<PSGI_KEY> which can be dereferenced with |
64 | key values or nothing to access the underly hashref. | |
6561feae | 65 | |
561098d1 | 66 | =head1 SUBROUTINES |
67 | ||
68 | This class defines the following subroutines. | |
6561feae | 69 | |
70 | =head2 PSGI_KEY | |
71 | ||
300b04ce | 72 | Returns the hash key where we store the stash. You should not assume |
73 | the string value here will never change! Also, its better to use | |
74 | L</get_stash> or L</stash>. | |
6561feae | 75 | |
561098d1 | 76 | =head2 get_stash |
6561feae | 77 | |
300b04ce | 78 | Expect: $psgi_env. |
79 | ||
80 | Exportable subroutine. | |
81 | ||
e77ad76e | 82 | Get the stash out of the C<$env>. |
6561feae | 83 | |
561098d1 | 84 | =head2 stash |
85 | ||
300b04ce | 86 | Expects: An object that does C<env> and arguments |
87 | ||
561098d1 | 88 | Exportable subroutine. |
89 | ||
90 | Given an object with a method C<env> get or set stash values, either | |
91 | as a method or via hashref modification. This stash is automatically | |
92 | reset for each request (it is not persistent or shared across connected | |
93 | clients. Stash key / value are stored in memory. | |
94 | ||
300b04ce | 95 | use Plack::Request; |
96 | use Catalyst::Middleware::Stash 'stash'; | |
561098d1 | 97 | |
300b04ce | 98 | my $app = sub { |
99 | my $env = shift; | |
100 | my $req = Plack::Request->new($env); | |
101 | my $stashed = $req->stash->{in_the_stash}; # Assume the stash was previously populated. | |
561098d1 | 102 | |
300b04ce | 103 | return [200, ['Content-Type' => 'text/plain'], |
104 | ["I found $stashed in the stash!"]]; | |
105 | }; | |
561098d1 | 106 | |
300b04ce | 107 | If the stash does not yet exist, we initialize one and return that. |
561098d1 | 108 | |
109 | =head1 METHODS | |
110 | ||
111 | This class defines the following methods. | |
112 | ||
6561feae | 113 | =head2 call |
114 | ||
115 | Used by plack to call the middleware | |
116 | ||
117 | =cut | |
118 | ||
119 | 1; |