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.v2' }
  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 $self = shift;
  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;
  34       foreach my $key (keys %$new_stash) {
  35         $stash->{$key} = $new_stash->{$key};
  36       }
  37     }
  38     $stash;
  39   };
  40 }
  41
  42 sub call {
  43   my ($self, $env) = @_;
  44   $env->{+PSGI_KEY} = $self->_create_stash
  45     unless exists($env->{+PSGI_KEY});
  46
  47   return $self->app->($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 Anything placed into the stash will be available in the stash of any 'mounted'
  64 Catalyst applications.  A mounted Catalyst application may set the stash and
  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.
  70
  71 For more information the current test case t/middleware-stash.t is the best
  72 documentation.
  73
  74 =head1 SUBROUTINES
  75
  76 This class defines the following subroutines.
  77
  78 =head2 PSGI_KEY
  79
  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>.
  83
  84 =head2 get_stash
  85
  86 Expect: $psgi_env.
  87
  88 Exportable subroutine.
  89
  90 Get the stash out of the C<$env>.
  91
  92 =head2 stash
  93
  94 Expects: An object that does C<env> and arguments
  95
  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
 103     use Plack::Request;
 104     use Catalyst::Middleware::Stash 'stash';
 105
 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.
 110
 111       return [200, ['Content-Type' => 'text/plain'],
 112         ["I found $stashed in the stash!"]];
 113     };
 114
 115 If the stash does not yet exist, an exception is thrown.
 116
 117 =head1 METHODS
 118
 119 This class defines the following methods.
 120
 121 =head2 call
 122
 123 Used by plack to call the middleware
 124
 125 =cut
 126
 127 1;