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 | |
5e7e6b27 |
12 | sub PSGI_KEY () { 'Catalyst.Stash.v2' } |
6561feae |
13 | |
300b04ce |
14 | sub get_stash { |
15 | my $env = shift; |
4b0b7489 |
16 | return $env->{+PSGI_KEY} || |
17 | croak "You requested a stash, but one does not exist."; |
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 { |
5e7e6b27 |
27 | my $self = shift; |
561098d1 |
28 | my $stash = shift || +{}; |
29 | return sub { |
30 | if(@_) { |
31 | my $new_stash = @_ > 1 ? {@_} : $_[0]; |
32 | croak('stash takes a hash or hashref') |
33 | unless ref $new_stash; |
300b04ce |
34 | foreach my $key (keys %$new_stash) { |
561098d1 |
35 | $stash->{$key} = $new_stash->{$key}; |
36 | } |
37 | } |
38 | $stash; |
39 | }; |
40 | } |
41 | |
6561feae |
42 | sub call { |
43 | my ($self, $env) = @_; |
5e7e6b27 |
44 | $env->{+PSGI_KEY} = $self->_create_stash |
45 | unless exists($env->{+PSGI_KEY}); |
4b0b7489 |
46 | |
bde334da |
47 | return $self->app->($env); |
6561feae |
48 | } |
49 | |
0dd88998 |
50 | =head1 NAME |
6561feae |
51 | |
52 | Catalyst::Middleware::Stash - The Catalyst stash - in middleware |
53 | |
54 | =head1 DESCRIPTION |
55 | |
56 | We've moved the L<Catalyst> stash to middleware. Please don't use this |
57 | directly since it is likely to move off the Catalyst namespace into a stand |
58 | alone distribution |
59 | |
561098d1 |
60 | We store a coderef under the C<PSGI_KEY> which can be dereferenced with |
566678d0 |
61 | key values or nothing to access the underlying hashref. |
6561feae |
62 | |
5e7e6b27 |
63 | Anything placed into the stash will be available in the stash of any 'mounted' |
79fb8f95 |
64 | Catalyst applications. A mounted Catalyst application may set the stash and |
5e7e6b27 |
65 | 'pass back' information to the parent application. Non Catalyst applications |
66 | may use this middleware to access and set stash values. |
67 | |
68 | Please note I highly recommend having a stronger interface than a stash key |
69 | between applications. |
4b0b7489 |
70 | |
71 | For more information the current test case t/middleware-stash.t is the best |
72 | documentation. |
73 | |
561098d1 |
74 | =head1 SUBROUTINES |
75 | |
76 | This class defines the following subroutines. |
6561feae |
77 | |
78 | =head2 PSGI_KEY |
79 | |
300b04ce |
80 | Returns the hash key where we store the stash. You should not assume |
81 | the string value here will never change! Also, its better to use |
82 | L</get_stash> or L</stash>. |
6561feae |
83 | |
561098d1 |
84 | =head2 get_stash |
6561feae |
85 | |
300b04ce |
86 | Expect: $psgi_env. |
87 | |
88 | Exportable subroutine. |
89 | |
e77ad76e |
90 | Get the stash out of the C<$env>. |
6561feae |
91 | |
561098d1 |
92 | =head2 stash |
93 | |
300b04ce |
94 | Expects: An object that does C<env> and arguments |
95 | |
561098d1 |
96 | Exportable subroutine. |
97 | |
98 | Given an object with a method C<env> get or set stash values, either |
99 | as a method or via hashref modification. This stash is automatically |
100 | reset for each request (it is not persistent or shared across connected |
101 | clients. Stash key / value are stored in memory. |
102 | |
300b04ce |
103 | use Plack::Request; |
104 | use Catalyst::Middleware::Stash 'stash'; |
561098d1 |
105 | |
300b04ce |
106 | my $app = sub { |
107 | my $env = shift; |
108 | my $req = Plack::Request->new($env); |
109 | my $stashed = $req->stash->{in_the_stash}; # Assume the stash was previously populated. |
561098d1 |
110 | |
300b04ce |
111 | return [200, ['Content-Type' => 'text/plain'], |
112 | ["I found $stashed in the stash!"]]; |
113 | }; |
561098d1 |
114 | |
4b0b7489 |
115 | If the stash does not yet exist, an exception is thrown. |
561098d1 |
116 | |
117 | =head1 METHODS |
118 | |
119 | This class defines the following methods. |
120 | |
6561feae |
121 | =head2 call |
122 | |
123 | Used by plack to call the middleware |
124 | |
125 | =cut |
126 | |
127 | 1; |