local-lib5/lib/perl5/Catalyst/Component/InstancePerContext.pm

   1 package Catalyst::Component::InstancePerContext;
   2
   3 use Moose::Role;
   4 use Scalar::Util qw/blessed refaddr/;
   5 use strict;
   6 use warnings;
   7
   8 our $VERSION = '0.001001';
   9
  10 requires 'build_per_context_instance';
  11
  12 # Hi, this is why I exist:
  13 # <mst> I'd like to see a Catalyst::Component::InstancePerContext role
  14 # <mst> that requires 'build_per_context_instance'
  15 # <mst> and provides an ACCEPT_CONTEXT that does the appropriate magic
  16 # <mst> ACCEPT_CONTEXT would do the stash persist as well
  17
  18 sub ACCEPT_CONTEXT {
  19     my $self = shift;
  20     my ($c) = @_;
  21
  22     return $self->build_per_context_instance(@_) unless ref $c;
  23     my $key = blessed $self ? refaddr $self : $self;
  24     return $c->stash->{"__InstancePerContext_${key}"} ||= $self->build_per_context_instance(@_);
  25 }
  26
  27 1;
  28
  29 =head1 NAME
  30
  31 Catalyst::Component::InstancePerContext -
  32 Return a new instance a component on each request
  33
  34 =head1 SYNOPSYS
  35
  36     package MyComponent;
  37     use Moose;
  38     with 'Catalyst::Component::InstancePerContext';
  39
  40     sub build_per_context_instance{
  41         my ($self, $c) = @_;
  42         # ... do your thing here
  43         return SomeModule->new(%args);
  44     }
  45
  46 =head1 REQUIRED METHODS
  47
  48 Your consuming class B<must> implement the following method.
  49
  50 =head2 build_per_context_instance
  51
  52 The value returned by this call is what you will recieve when you call
  53 $c->component('YourComponent').
  54
  55 =head1 PROVIDED METHODS
  56
  57 This role will add the following method to your consuming class.
  58
  59 =head2 ACCEPT_CONTEXT
  60
  61 If the context is not blessed, it will simple pass through the value of
  62 C<build_per_context_instance>. If context is blessed it will look in the
  63 C<stash> for an instance of the requested component and return that or,
  64 if the value is not found, the value returned by C<build_per_context_instance>
  65 will be stored and return.
  66
  67 The idea behind this behavior is that a component can be built on a
  68 per-request basis, as the name of this module implies.
  69
  70 =head1 SEE ALSO
  71
  72 L<Moose>, L<Moose::Role>, L<Catalyst::Component>
  73
  74 =head1 AUTHOR
  75
  76 Guillermo Roditi (groditi) <groditi@cpan.org>
  77
  78 =head1 LICENSE
  79
  80 You may distribute this code under the same terms as Perl itself.
  81
  82 =cut