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; |
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) = @_; |
561098d1 |
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 | |
53 | =head1 TITLE |
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; |