NAME

Maypole::Plugin::Session - simple sessions for Maypole

SYNOPSIS

    use Maypole::Application qw( Session );
    
    # Elsewhere in your app:
    my $session = $r->session;
    

DESCRIPTION

Maypole::Plugin::Authentication::UserSessionCookie has a cryptic paragraph explaining how to use that module to support basic sessions without users. This module saves you from having to figure it out.

Provides session and delete_session methods for your Maypole request class.

PUBLIC METHODS

session

Returns the session object/hash.

delete_session

Deletes the session and cookie.

PRIVATE METHODS

These are only necessary if you are writing custom authenticate method(s). Otherwise, they are called for you.

authenticate

This is called early in the Maypole request workflow, and is used as the hook to call get_session. If you are writing your own authenticate method(s), either in model classes or in the request classes, make sure your authenticate method calls get_session.

get_session

Retrieves the cookie from the browser and matches it up with a session in the store. Puts the session in the session slot of the request.

You should call this method inside any custom authenticate methods.

Configuration

The class provides sensible defaults for all that it does, but you can change its operation through Maypole configuration parameters.

First, the session data. This is retrieved as follows. The Maypole configuration parameter <$config-session->{class}>> is used as a class to tie the session hash, and this defaults to Apache::Session::File. The parameters to the tie are the session ID and the value of the <$config-session->{args}>> configuration parameter. This defaults to:

    { Directory     => "/tmp/sessions", 
      LockDirectory => "/tmp/sessionlock" 
      }

You need to create these directories with appropriate permissions if you want to use these defaults.

For instance, you might instead want to say:

    $r->config->session({
        class => "Apache::Session::Flex",
        args  => {
            Store     => 'DB_File',
            Lock      => 'Null',
            Generate  => 'MD5',
            Serialize => 'Storable'
         }
    });

The cookie name is retrieved from <$config-session->{cookie_name}>> but defaults to "sessionid". It defaults to expiry after 3 months, and this can be set in <$config-session->{cookie_expiry}>.

SEE ALSO

Maypole::Plugin::Authentication::UserSessionCookie, from which nearly all of the code was stolen.

AUTHOR

David Baird, <cpan@riverside-cms.co.uk>

BUGS

Please report any bugs or feature requests to bug-maypole-plugin-session@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Maypole-Plugin-Session. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2005 David Baird, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.