3 package Catalyst::Plugin::Session::Store;
16 Catalyst::Plugin::Session::Store - Base class for session storage
21 package Catalyst::Plugin::Session::Store::MyBackend;
22 use base qw/Catalyst::Plugin::Session::Store/;
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") >>. When you write
29 a session storage plugin you should subclass this module for this
30 reason. This documentation is intended for authors of session storage
31 plugins, not for end users.
33 =head1 WRITING STORE PLUGINS
35 All session storage plugins need to adhere to the following interface
36 specification to work correctly:
38 =head2 Required Methods
42 =item get_session_data $key
44 =item store_session_data $key, $data
46 Retrieve or store session data by key.
48 C<$data> is currently either a hash reference (for most keys) or an
49 integer value (for expires), but all value types should be supported.
51 Keys are in the format C<prefix:id>, where C<prefix> is C<session>,
52 C<expires>, or C<flash>, and C<id> is always the session ID. Plugins
53 such as L<Catalyst::Plugin::Session::PerUser> store extensions to this
54 format, such as C<user:username>.
56 It is suggested that the store should split on the colon and store the
57 data more efficiently - the API should remain stable, with the possible
58 addition of new prefixes in the future.
60 For example, C<Store::DBI> maps C<expires:id> a column of C<session:id>
61 by special-casing C<get_session_data> and C<store_session_data> for that
62 key format, in order to ease the implementation of
63 C<delete_expired_sessions>.
65 The only assurance stores are requred to make is that given
67 $c->store_session_data( $x, $y );
71 $y == $c->get_session_data( $x )
75 =item store_session_data ( $key, $data )
77 Store a session whose KEY is the first parameter and data is the second
80 The second parameter is a hash reference, which should normally be
81 serialized (and later deserialized by C<get_session_data>).
83 =item delete_session_data ( $key )
85 Delete the session whose KEY is the parameter.
87 =item delete_expired_sessions
89 This method is not called by any code at present, but may be called in the
90 future, as part of a Catalyst-specific maintenance script.
92 If you are wrapping around a backend which manages its own auto expiry
93 you can just give this method an empty body.
99 All errors should be thrown using L<Catalyst::Exception>. Return values
100 are not checked, and are assumed to be OK. Missing values are not errors.
102 =head2 Auto-Expiry on the Backend
104 Storage plugins are encouraged to use C<< $c->session_expires >>, C<<
105 $c->config->{session}{expires} >>, or the storage of the
106 C<expires:$sessionid> key to perform more efficient expiration, but only
107 for the key prefixes C<session>, C<flash> and C<expires>.
109 If the backend chooses not to do so, L<Catalyst::Plugin::Session> will
110 detect expired sessions as they are retrieved and delete them if
113 Note that session store that use this approach may leak disk space,
114 since nothing will actively delete an expired session. The
115 C<delete_expired_sessions> method is there so that regularly scheduled
116 maintenance scripts can give your backend the opportunity to clean up.