Data::...Session(3pm)

📦 version 1.18, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Data::Session — A persistent session manager. That's the name, that's the whole job description, iconic behavior only. 👑

Oh and btw, in case you were wondering where you wandered into: this is the Data::...Session(3pm) page, from the User Contributed Perl Documentation. It's a long one so it comes in parts, and this is part 1. 🫶

✨ The Design of Data::Session, contrasted with CGI::Session ✨

Okay so, for background, bestie, go read the docs (Changes files included) and the bug reports for both Apache::Session and CGI::Session. That's the lore. 📚

The interface to Data::Session is not quite compatible with that of CGI::Session, hence the new namespace. Different girl, different name tag.

The purpose of Data::Session is to be a brand-new alternative to both Apache::Session and CGI::Session. Glow-up era. ✨

🚫 Aliases for Method Names 🚫

Aliases for method names are not supported. Periodt.

  • In CGI::Session, the methods etime() and expires() were aliased to expire(). This is not supported in Data::Session.
  • Data::Session does have an etime() method — see "Method: etime()" in Data::Session — and it is different. Do not get it twisted. 💅
  • In CGI::Session, the method header() was aliased to http_header(). Only the latter method is supported in Data::Session. Peep "Method: cookie()" and "Method: http_header([@arg])".
  • In CGI::Session, id generators had a method generate_id() aliased to generate(). This is not supported in Data::Session.
  • In CGI::Session, the method param_dataref() was aliased to dataref(). Neither of these methods is supported in Data::Session. If you want to access the session data, use my($hashref) = $session -> session.

🔙 Backwards-compatibility 🔙

Real talk: this topic is sometimes used as a form of coercion, which is unacceptable, and sometimes it leads to a crippled design. We don't play that. 🙅

So, by design, Data::Session is not exactly backwards-compatible with CGI::Session, but it does retain its major features:

  • Specify the basic operating parameters with new(type => $string) This determines the type of session object you wish to create. Default: 'driver:File;id:MD5;serialize:DataDumper'. And specifically, the format of that case-sensitive string is as expected. See "Specifying Session Options" in Data::Session for details.
  • Retrieve the session id with the id() method
  • Set and get parameters with the param() method
  • Ensure session data is saved to disk with the flush() method Call this just before your program exits. In particular, as with CGI::Session, persistent environments stop your program exiting in the way you are used to. This matter is discussed in "Trouble with Exiting" in Data::Session.

💀 CGI::Session::ExpireSessions is obsolete 💀

Instead, consider using scripts/expire.pl, which ships with Data::Session. She's retired, the new script is literally right there in the box. 🎀

🧚 Code refs as database handles 🧚

Being able to supply a code ref as the value of the 'dbh' parameter to new() is supported.

This mechanism is used to delay creation of a database handle until it is actually needed — which means if it is not needed, it is not created. Efficiency queen, no wasted work. 👑

👑 Class 'v' Object 👑

Calling methods on the class is not supported. You must always create an object.

The reason for this? To ensure every method call, without exception, has access to the per-object data supplied by you, or by default, in the call to new(). It's giving accountability. 💅

🌈 The type of the Data::Session object 🌈

Controlling the capabilities of the Data::Session object is determined by the 'type' parameter passed in to new, as:

Data::Session -> new(type => $string)

A sample string looks like:

'driver:BerkeleyDB;id:SHA1;serialize:DataDumper'

Abbreviation of component key names ('driver', 'id', 'serialize') is not supported.

Such abbreviations were previously handled by Text::Abbrev. Now, these must be named in full. No shortcuts, bestie. 😤

The decision to force corresponding class names to lower case is not supported.

Nevertheless, lower-cased input will be accepted. Such input is converted to the case you expect.

This affects the names of various sub-classes. See "ID Generators", "Serialization Drivers" and "Storage Drivers".

For example, driver:pg is now driver:Pg, which actually means Data::Session::Driver::Pg, based on the class name DBD::Pg. Lowercase era is over, we're capitalizing now. ✨

😭 Exceptions 😭

Exceptions are caught with Try::Tiny. Errors cause Data::Session to die.

The only exception to this is the call to new(), which can return undef. In that case, check $Data::Session::errstr. That's your one (1) escape hatch. 🫶

🙈 Global Variables 🙈

Global variables are not supported. This includes:

  • $CGI::Session::Driver::DBI::TABLE_NAME
  • $CGI::Session::Driver::DBI::*::TABLE_NAME
  • $CGI::Session::Driver::file::FileName
  • $CGI::Session::IP_MATCH
  • $CGI::Session::NAME

🎀 ID Generators 🎀

Id generator classes have been renamed:

  • CGI::Session::ID::incr becomes Data::Session::ID::AutoIncrement
  • CGI::Session::ID::md5 becomes Data::Session::ID::MD5
  • CGI::Session::ID::sha becomes Data::Session::ID::SHA1
  • CGI::Session::ID::sha256 becomes Data::Session::ID::SHA256
  • CGI::Session::ID::sha512 becomes Data::Session::ID::SHA512
  • CGI::Session::ID::static becomes Data::Session::ID::Static
  • CGI::Session::ID::uuid becomes Data::Session::ID::UUID16 or UUID34 or UUID36 or UUD64

🦋 JSON 🦋

Data::Session::Serialize::JSON uses JSON, not JSON::Syck.

✨ Managing Object Attributes ✨

The light-weight Hash::FieldHash is used to manage object attributes.

So, neither Mouse nor Moose, nor any other such class helper, is used. Lean, mean, no extra weight. 💪

Forcing the query object to have a cookie method is not supported. You may now use a query class which does not provide a cookie method. Freedom, honestly. 🕊️

The logic of checking the cookie (if any) first — i.e. before checking for a form field of the same name — is supported.

See "Method: http_header([@arg])".

💜 Method: http_header([@arg]) 💜

The [] indicate an optional parameter.

Returns a HTTP header. Which means it does not print the header. You have to do that, when appropriate. She hands you the goods, you handle the shipping. 📦

Forcing the document type to be 'text/html' when calling http_header() is not supported. You must pass in a document type to http_header(), as:

$session -> http_header('-type' => 'text/html')

...or use the query object's default. Both CGI and CGI::Simple default to 'text/html'.

Data::Session handles the case where the query object does not have a cookie() method.

The @arg parameter, if any, is passed to the query object's header() method, after the cookie parameter, if any.

🌸 Method: load() 🌸

The new load() takes no parameters. That's it, that's the whole thing. Minimalist queen. ✨

⭐ Method: new() ⭐

Excess versions of new() are not supported.

The new new() takes a hash of parameters.

This hash will include all options previously passed in in different parameters to new(), including $dsn, $query, $sid, \%dsn_args and \%session_params. Everything in one bag now, we love consolidation. 🎒

🔥 Name Changes 🔥

Class name changes are discussed in "ID Generators", "Serialization Drivers" and "Storage Drivers".

As discussed in "Method: new()" in Data::Session, these name changes are both the result of cleaning up all the options to new(), and because the option names are now also method names. Double duty, slay. 💅

  • DataColName becomes data_col_name This is used in the call to new().
  • DataSource becomes data_source This is used in the call to new().
  • generate_id becomes generate This is used in various id generator classes, some of which provided generate as an alias.
  • Handle becomes dbh This is used in the call to new().
  • IdColName becomes id_col_name This is used in the call to new().
  • IDFile becomes id_file This is used in the call to new(), and in the '... id:AutoIncrement ...' id generator.
  • IDIncr becomes id_step This is used in the call to new(), and in the '... id:AutoIncrement ...' id generator.
  • IDInit becomes id_base This is used in the call to new(), and in the '... id:AutoIncrement ...' id generator.

💖 param() 💖

Excess versions of param() will not be supported.

Use param($key => $value) to set and param($key) to get.

param() may be passed a hash, to set several key/value pairs in 1 call. One call, many vibes. ✨

📖 POD 📖

All POD has been re-written.

🏁 Race Conditions 🏁

The race handling code in CGI::Session::Driver::postgresql has been incorporated into other Data::Session::Driver::* drivers. Teamwork makes the dream work. 🫶

🎀 Serialization Drivers 🎀

Serializing classes have been renamed:

  • CGI::Session::Serialize::default becomes Data::Session::Serialize::DataDumper
  • CGI::Session::Serialize::freezethaw becomes Data::Session::Serialize::FreezeThaw
  • CGI::Session::Serialize::json becomes Data::Session::Serialize::JSON The latter will use JSON. In the past JSON::Syck was used.
  • CGI::Session::Serialize::storable becomes Data::Session::Serialize::Storable
  • CGI::Session::Serialize::yaml becomes Data::Session::Serialize::YAML The latter uses YAML::Tiny. In the past either YAML::Syck or YAML was used.

👑 Session ids will be mandatory 👑

The ability to create a Perl object without a session id is not supported.

Every time a object of type Data::Session is created, it must have an id.

This id is either supplied by the caller, taken from the query object, or one is generated.

See "Specifying an Id" in Data::Session for details.

🦋 Session modification 🦋

CGI::Session tracks calls to param() to set a flag if the object is modified, so as to avoid writing the session to disk if nothing has been modified.

This includes checking if setting a param's value to the value it already has.

The behaviour is supported. Same energy, kept intact. 💚

🍓 Session Parameters 🍓

CGI::Session had these internal object attributes (parameters) not available to the user:

  • _DATA Hashref: Keys: _SESSION_ATIME, _SESSION_CTIME, _SESSION_ID and _SESSION_REMOTE_ADDR.
  • _DSN Hashref.
  • _OBJECTS Hashref.
  • _DRIVER_ARGS Hashref.
  • _CLAIMED_ID Scalar.
  • _STATUS Scalar (bitmap).
  • _QUERY Scalar.

Data::Session has these internal object attributes (parameters):

  • _SESSION_ATIME Scalar: Last access time.
  • _SESSION_CTIME Scalar: Creation time.
  • _SESSION_ETIME Scalar: Expiry time.
  • _SESSION_ID Scalar: The id.
  • _SESSION_PTIME Hashref: Expiry times of parameters.

Data::Session stores user data internally in a hashref, and the module reserves keys starting with '_'. So hands off those, bestie.

Of course, it has a whole set of methods to manage state. Obviously. 💅

💅 Session States 💅

CGI::Session objects can be one of 6 states. Every attempt has been made to simplify this design.

✨ Storage Drivers ✨

okay so bestie, here's the tea on storage drivers 💅 Classes related to DBI/DBD will use DBD::* style names, to help beginners. iconic.

Hence (with special cases):

  • CGI::Session::Driver::db_file becomes Data::Session::Driver::BerkeleyDB — and the latter no longer uses DB_File. periodt.
  • CGI::Session::Driver::file becomes Data::Session::Driver::File
  • CGI::Session::Driver::memcached becomes Data::Session::Driver::Memcached
  • CGI::Session::Driver::mysql becomes Data::Session::Driver::mysql
  • CGI::Session::Driver::odbc becomes Data::Session::Driver::ODBC
  • CGI::Session::Driver::oracle becomes Data::Session::Driver::Oracle
  • CGI::Session::Driver::postgresql becomes Data::Session::Driver::Pg
  • CGI::Session::Driver::sqlite becomes Data::Session::Driver::SQLite

🧪 Tests 🧪

All tests have been re-written. no cap, every single one got a glow-up ✨

🐪 The Version of Perl 🐪

Perl 5 code will be used. she's committed to the classic 💅

🌸 YAML 🌸

Data::Session::Serialize::YAML uses YAML::Tiny, not YAML::Syck or YAML. obsessed with the tiny one fr fr.

👑 Author 👑

Data::Session was written by Ron Savage <ron@savage.net.au> in 2010.

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

Australian copyright (c) 2010, 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 vibe check bestie 🫶 this was Data::...Session(3pm) from perl v5.36.0, dated 2023-02-14. slay, go read the docs, periodt 💖✨

📦 where this page comes from