lib/Catalyst/Plugin/Session/Store.pm

   1 #!/usr/bin/perl
   2
   3 package Catalyst::Plugin::Session::Store;
   4
   5 use strict;
   6 use warnings;
   7
   8 __PACKAGE__;
   9
  10 __END__
  11
  12 =pod
  13
  14 =head1 NAME
  15
  16 Catalyst::Plugin::Session::Store - Base class for session storage
  17 drivers.
  18
  19 =head1 SYNOPSIS
  20
  21     package Catalyst::Plugin::Session::Store::MyBackend;
  22     use base qw/Catalyst::Plugin::Session::Store/;
  23
  24 =head1 DESCRIPTION
  25
  26 This class doesn't actually provide any functionality, but when the
  27 C<Catalyst::Plugin::Session> module sets up it will check to see that
  28 C<< YourApp->isa("Catalyst::Plugin::Session::Store") >>.
  29
  30 When you write a session storage plugin you should subclass this module this
  31 reason only.
  32
  33 =head1 WRITING STORE PLUGINS
  34
  35 All session storage plugins need to adhere to the following interface
  36 specification to work correctly:
  37
  38 =head2 Required Methods
  39
  40 =over 4
  41
  42 =item get_session_data $sid
  43
  44 Retrieve a session from storage, whose ID is the first parameter.
  45
  46 Should return a hash reference.
  47
  48 =item store_session_data $sid, $hashref
  49
  50 Store a session whose ID is the first parameter and data is the second
  51 parameter in storage.
  52
  53 The second parameter is an hash reference, that should normally be serialized
  54 (and later deserialized by C<get_session_data>).
  55
  56 =item delete_session_data $sid
  57
  58 Delete the session whose ID is the first parameter.
  59
  60 =item delete_expired_sessions
  61
  62 This method is not called by any code at present, but may be called in the
  63 future, as part of a catalyst specific maintenance script.
  64
  65 If you are wrapping around a backend which manages it's own auto expiry you can
  66 just give this method an empty body.
  67
  68 =back
  69
  70 =head2 Error handling
  71
  72 All errors should be thrown using L<Catalyst::Exception>. Return values are not
  73 checked at all, and are assumed to be OK.
  74
  75 =head2 Auto-Expirey on the Backend
  76
  77 Storage plugins are encouraged to use C<< $c->config->{session}{expires} >> and
  78 the C<__expires> key in the session data hash reference to auto expire data on
  79 the backend side.
  80
  81 If the backend chooses not to do so, L<Catalyst::Plugin::Session> will detect
  82 expired sessions as they are retrieved and delete them if necessary.
  83
  84 Note that session storages that use this approach may leak disk space, since
  85 nothing will actively delete expired session. The C<delete_expired_sessions>
  86 method is there so that regularly scheduled maintenance scripts can give your
  87 backend the opportunity to clean up.
  88
  89 =cut
  90
  91