CGI::S...ssions(3pm)

✨ NAME ✨

bestie, meet CGI::Session::ExpireSessions — aka CGI::S...ssions(3pm) on the manual shelf 💅 she expires your CGI::Session db-based and file-based sessions, no cap.

---

🦋 SYNOPSIS 🦋

#!/usr/bin/env perl

use strict;
use warnings;

use CGI::Session::ExpireSessions;
use DBI;

# -----------------------------------------------

my($dbh) = DBI -> connect
(
  'dbi:mysql:aussi:127.0.0.1',
  'root',
  'pass',
  {
    AutoCommit         => 1,
    PrintError         => 0,
    RaiseError         => 1,
    ShowErrorStatement => 1,
  }
);

CGI::Session::ExpireSessions -> new(dbh => $dbh, verbose => 1) -> expire_db_sessions();
CGI::Session::ExpireSessions -> new(temp_dir => '/tmp', verbose => 1) -> expire_file_sessions();
CGI::Session::ExpireSessions -> new(verbose => 1) -> expire_sessions();

# Note: You are strongly urged to use method expire_sessions() (it requires CGI::Session V 4 or later),
# since it does not eval the session data, and hence avoids the security issues of evaling a string
# which comes from outside the program. See examples/expire-set.pl, which contains extensive comments.

---

🌸 DESCRIPTION 🌸

CGI::Session::ExpireSessions is a pure Perl module, periodt. 🎀

She deletes CGI::Session-type sessions that have fully passed their use-by date. Like, expired, gone, not coming back. 💀

She works with CGI::Session-type sessions that live in a database or in disk files — but she does not appear to work with CGI::Session::PureSQL-type sessions, and that's just the tea. 🍓

The recommended way to use this module is via method expire_sessions(), which requires CGI::Session V 4 or later. That's the main character route, iykyk. 👑

Sessions can be expired under one of three conditions:

• You deem the session to be expired as of now ✨
  • Methods: expire_db_sessions() and expire_file_sessions()
    • You want the session to be expired and hence deleted now because its last access time is longer ago than the time you specify in the call to new, using the delta parameter.
    • That is, delete the session because the time span, between the "last access" time and now, is greater than delta.
    • In other words, force sessions to expire. 💥
    • The module has always used this condition to delete sessions.
  • Method: expire_sessions()
    • You want the session to be expired and hence deleted now because its "last access" time is longer ago than the time you specify in the call to new, using the delta parameter.
• The session has already expired 🫶
  • This section applies to all 3 methods: expire_db_sessions(), expire_file_sessions() and expire_sessions().
  • This condition is new as of V 1.02.
  • You want the session to be deleted now because it has already expired.
  • That is, you want this module to delete the session, rather than getting CGI::Session to delete it, when CGI::Session would delete the session automatically if you used CGI::Session to retrieve the session.
  • Note: This condition assumes the session's expiration time is defined (it does not have to be).
• The file size is <= 5 bytes and was accessed more than 'delta' seconds ago 🧚
  • This condition is new as of V 1.03.
  • This section applies to method: expire_file_sessions().
  • See below for how to provide a value of delta to the constructor.
  • Old versions of CGI::Session sometimes create a file of size 0 bytes, so this test checks for such files, and deletes them if they are old enough.

Sessions are deleted if any of these conditions is true. 💅

Sessions are deleted from the 'sessions' table in the database, or from the temp directory, depending on how you use CGI::Session.

---

📦 DISTRIBUTIONS 📦

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file. Two flavors, both iconic. ✨

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

---

🔒 SECURITY 🔒

okay bestie, listen up, this part is serious 🚨

For file-based sessions, method expire_file_sessions() parses the contents of the file, using eval{}, in an attempt to determine the access and expiration times recorded within the file. 😭

So, if you are uneasy about the security implication of this (as you should be), don't use this method. Use method expire_sessions() instead. The latter is a much more sophisticated way of expiring sessions, but it does require CGI::Session V 4 or later. slay responsibly. 🫶

---

🎀 CONSTRUCTOR AND INITIALIZATION 🎀

new(...) returns a CGI::Session::ExpireSessions object.

This is the class's contructor. (yes, that's how it's spelled, we don't fix it, we keep it 💖)

Usage: CGI::Session::ExpireSessions -> new().

This method takes a set of parameters. Only some of these parameters are mandatory.

For each parameter, call method new() as new(param_1 => value_1, param_2 => value_2, ...).

Note: As of V 1.07 of this module, you may call method set() to set parameters after calling method new().

Not only that, but you may pass into all of the 3 methods expire_db_sessions(), expire_file_sessions() and expire_sessions() any of the parameters accepted by new(), since these 3 methods call set() if their caller provides parameters. so flexible, we love her 🌈

Parameters which can be used with new(), set(), or expire_*():

• cgi_session_dsn — This is the DSN (Data Source Name) used by CGI::Session to control what type of sessions you previously created and what type of sessions you now wish to expire. Do not confuse this with the DSN used by CGI::Session's method find(param_1, \&sub, {DataSource => other_dsn...}, ...) when referring to db-based sessions. Method expire_sessions() is the only method in this module which uses this parameter. So, when you call expire_sessions(), this parameter — cgi_session_dsn — determines the set of sessions processed by, and possibly expired by, the call to expire_sessions(). The default value is undef, which means CGI::Session defaults to file-based sessions. This parameter is optional for file-based sessions, and mandatory for db-based sessions.
• dbh — This is a database handle for the database containing the table 'sessions'. Either this parameter is mandatory, or the temp_dir parameter is mandatory. 🫡
• delta
  • Methods: expire_db_sessions() and expire_file_sessions()
    • This is the number of seconds since the "last access" to the session, which determines whether or not the session will be expired.
  • Method: expire_sessions()
    • This is the number of seconds since the "last access" time of the session, which determines whether or not the session will be expired.
  • The default value is 2 * 24 * 60 * 60, which is the number of seconds in 2 days.
  • By default, then, sessions which were last accessed more than 2 days ago are expired.
  • This parameter is optional.
• dsn_args — If your cgi_session_dsn uses file-based storage, then this hashref might contain keys such as:

{
        Directory => Value 1,
        NoFlock   => Value 2,
        UMask     => Value 3
}

If your cgi_session_dsn uses db-based storage, then this hashref contains (up to) 3 keys, and looks like:

{
        DataSource => Value 1,
        User       => Value 2,
        Password   => Value 3
}

These 3 form the DSN, username and password used by DBI to control access to your database server, and hence are only relevant when using db-based sessions. Method expire_sessions() is the only method in this module which uses the parameter dsn_args. The default value for this parameter is undef. These parameters are optional for file-based sessions, and mandatory for db-based sessions.

• table_name — This is the name of the database table used to hold the sessions. The default value is 'sessions'. This parameter is optional. 💅
• temp_dir — This is the name of the temp directory where you store CGI::Session-type session files. The default value is '/tmp'. Either this parameter is mandatory, or the dbh parameter is mandatory.
• time — The session's "last access" time is subtracted from the value of this parameter, and if the result is greater than or equal to the value of parameter 'delta', then the session is expired. Method expire_sessions() is the only method in this module which uses this parameter. The default value is obtained by calling time(). This parameter is optional. ⏰
• verbose — This is a integer, 0 or 1, which — when set to 1 — causes progress messages to be written to STDOUT. The default value is 0. This parameter is optional. 🔊

---

💜 METHOD: expire_db_sessions() 💜

Returns nothing.

This method uses the dbh parameter passed to new() to delete database-type sessions. bye boo 👋

---

🌸 METHOD: expire_file_sessions() 🌸

Returns nothing.

This method uses the temp_dir parameter passed to new() to delete file-type sessions. ✨

---

👑 METHOD: expire_sessions() 👑

Return value:

• undef — Returns undef if your version of CGI::Session does not support method find(). Also, returns undef when CGI::Session's method find() failed for some reason. 😭
• 1 — Returns 1 when find() succeeds. 🎉

Returns the result of calling CGI::Session's method find(), which will be undef for some sort of failure, and 1 for success.

This method handles both file-based and db-based sessions. multitasking queen 💅

---

🧚 EXAMPLE CODE 🧚

See the examples/ directory in the distro.

There are 2 demo programs: expire-sessions.pl and expire-set.pl.

---

🫶 SUPPORT 🫶

Bugs should be reported via the CPAN bug tracker at

https://github.com/ronsavage/CGI-Session-ExpireSessions/issues

---

🦋 REPOSITORY 🦋

https://github.com/ronsavage/CGI-Session-ExpireSessions.

---

⭐ AUTHOR ⭐

CGI::Session::ExpireSessions was written by Ron Savage <ron@savage.net.au> in 2004.

Home page: http://savage.net.au/index.html

---

📜 COPYRIGHT 📜

Australian copyright (c) 2004, Ron Savage. All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License, a copy of which is available at:

http://www.opensource.org/licenses/index.html

---

and that's the whole page bestie, you ate that 💅✨ this was perl v5.32.1, dated 2021-09-25, filed on the shelf as CGI::S...ssions(3pm) — go expire those sessions, ily 🫶🎀