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 $key
  43
  44 =item store_session_data $key, $data
  45
  46 Retrieve or store session data by key.
  47
  48 C<$data> is currently either a hash reference (for most keys) or an integer value
  49 (for expires), but all value types should be supported.
  50
  51 Keys are in the format C<prefix:id>, where C<prefix> is C<session>, C<expires>,
  52 or C<flash>, and C<id> is always the session ID. Plugins such as
  53 L<Catalyst::Plugin::Session::PerUser> store extensions to this, like
  54 C<user:username>.
  55
  56 The store is encouraged to split on the column and store the data more
  57 efficiently if the store author is inclined to do so - the API should remain
  58 pretty stable, with the possible addition of new prefixes in the future, but
  59 not much more.
  60
  61 For example, C<Store::DBI> maps C<expires:id> a column of C<session:id> by special
  62 casing C<get_session_data> and C<store_session_data> for that key format, in
  63 order to ease the implementation of C<delete_expired_sessions>.
  64
  65 The only assurance stores are requred to make is that given
  66
  67     $c->store_session_data( $x, $y );
  68
  69 for any $x,
  70
  71     $y == $c->get_session_data( $x )
  72
  73 will hold.
  74
  75 Store a session whose ID is the first parameter and data is the second
  76 parameter in storage.
  77
  78 The second parameter is an hash reference, that should normally be serialized
  79 (and later deserialized by C<get_session_data>).
  80
  81 =item delete_session_data $sid
  82
  83 Delete the session whose ID is the first parameter.
  84
  85 =item delete_expired_sessions
  86
  87 This method is not called by any code at present, but may be called in the
  88 future, as part of a catalyst specific maintenance script.
  89
  90 If you are wrapping around a backend which manages it's own auto expiry you can
  91 just give this method an empty body.
  92
  93 =back
  94
  95 =head2 Error handling
  96
  97 All errors should be thrown using L<Catalyst::Exception>. Return values are not
  98 checked at all, and are assumed to be OK.
  99
 100 Missing values are not errors.
 101
 102 =head2 Auto-Expirey on the Backend
 103
 104 Storage plugins are encouraged to use C<< $c->session_expires >>, C<<
 105 $c->config->{session}{expires} >> or the storage of the C<expires:$sessionid>
 106 key to perform more efficient expiration, but only for the key prefixes
 107 C<session>, C<flash> and C<expires>.
 108
 109 If the backend chooses not to do so, L<Catalyst::Plugin::Session> will detect
 110 expired sessions as they are retrieved and delete them if necessary.
 111
 112 Note that session storages that use this approach may leak disk space, since
 113 nothing will actively delete expired session. The C<delete_expired_sessions>
 114 method is there so that regularly scheduled maintenance scripts can give your
 115 backend the opportunity to clean up.
 116
 117 =cut
 118
 119