lib/Catalyst/Middleware/Stash.pm

   1 use strict;
   2 use warnings;
   3
   4 package Catalyst::Middleware::Stash;
   5
   6 use base 'Plack::Middleware';
   7 use Exporter 'import';
   8 use Carp 'croak';
   9
  10 our @EXPORT_OK = qw(stash get_stash);
  11
  12 sub PSGI_KEY () { 'Catalyst.Stash.v1' }
  13
  14 sub get_stash {
  15   my $env = shift;
  16   return $env->{+PSGI_KEY} ||
  17    croak "You requested a stash, but one does not exist.";
  18 }
  19
  20 sub stash {
  21   my ($host, @args) = @_;
  22   return get_stash($host->env)
  23     ->(@args);
  24 }
  25
  26 sub _create_stash {
  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;
  33       foreach my $key (keys %$new_stash) {
  34         $stash->{$key} = $new_stash->{$key};
  35       }
  36     }
  37     $stash;
  38   };
  39 }
  40
  41 sub call {
  42   my ($self, $env) = @_;
  43   my $new_env = +{ %$env };
  44   my %stash = %{ ($env->{+PSGI_KEY} || sub {})->() || +{} };
  45
  46   $new_env->{+PSGI_KEY} = _create_stash( \%stash  );
  47   return $self->app->($new_env);
  48 }
  49
  50 =head1 NAME
  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
  60 We store a coderef under the C<PSGI_KEY> which can be dereferenced with
  61 key values or nothing to access the underlying hashref.
  62
  63 The stash middleware is designed so that you can 'nest' applications that
  64 use it.  If for example you have a L<Catalyst> application that is called
  65 by a controller under a parent L<Catalyst> application, the child application
  66 will inherit the full stash of the parent BUT any new keys added by the child
  67 will NOT bubble back up to the parent.  However, children of children will.
  68
  69 For more information the current test case t/middleware-stash.t is the best
  70 documentation.
  71
  72 =head1 SUBROUTINES
  73
  74 This class defines the following subroutines.
  75
  76 =head2 PSGI_KEY
  77
  78 Returns the hash key where we store the stash.  You should not assume
  79 the string value here will never change!  Also, its better to use
  80 L</get_stash> or L</stash>.
  81
  82 =head2 get_stash
  83
  84 Expect: $psgi_env.
  85
  86 Exportable subroutine.
  87
  88 Get the stash out of the C<$env>.
  89
  90 =head2 stash
  91
  92 Expects: An object that does C<env> and arguments
  93
  94 Exportable subroutine.
  95
  96 Given an object with a method C<env> get or set stash values, either
  97 as a method or via hashref modification.  This stash is automatically
  98 reset for each request (it is not persistent or shared across connected
  99 clients.  Stash key / value are stored in memory.
 100
 101     use Plack::Request;
 102     use Catalyst::Middleware::Stash 'stash';
 103
 104     my $app = sub {
 105       my $env = shift;
 106       my $req = Plack::Request->new($env);
 107       my $stashed = $req->stash->{in_the_stash};  # Assume the stash was previously populated.
 108
 109       return [200, ['Content-Type' => 'text/plain'],
 110         ["I found $stashed in the stash!"]];
 111     };
 112
 113 If the stash does not yet exist, an exception is thrown.
 114
 115 =head1 METHODS
 116
 117 This class defines the following methods.
 118
 119 =head2 call
 120
 121 Used by plack to call the middleware
 122
 123 =cut
 124
 125 1;