The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


CGI::Session::Flash - Session Flash Object


    use CGI::Session;
    use CGI::Session::Flash;

    my $session = CGI::Session->new(...);
    my $flash   = CGI::Session::Flash->new($session, \%options);

    # Get and set the values
    $flash->set(KEY => @VALUES);
    my @values = $flash->get('KEY');

    # Checking for keys and if the flash is empty.
    print "Flash is empty\n"     if ($flash->is_empty);
    print "Flash contains key\n" if ($flash->has_key('NAME'));
    print "Flash keys: ", join(", ", $flash->keys), "\n";

    # Dump the contents of the flash for debugging purposes.
    warn $flash->dump();

    # Refresh the flash, this basically just wipes it and starts fresh.


This module implements a Flash object. A flash is session data with a specific life cycle. When you put something into the flash it stays there until two cleanup calls have been made. What this generally means is that in a web application the data in the flash will stay until the end of the next request (the first cleanup call is made at the end of the first request). This allows you to use it for storing messages that can be accessed after a redirect, but then are automatically cleaned up.

Textual messages are not the only data that can be stored in the flash though. You can use it to store anything that can be properly serialized into the session. Another example use for it is to store previous form arguments for when redirecting back to a form after an error occurred.

The advantage of using the flash instead of the session directly is that you do not need to worry about cleaning up after yourself.



CLASS->new($session, %options)

Create a new flash object. The first parameter is a session object. This is used to initialize the flash.

Additional arguments specify options for the flash. The possible options are


This is the name of the key to use when storing the flash data in the session. The default value is _flash. This actual flash data is stored in this key and the list of flash keys to keep is stored in a key with _keep appended.



Returns true or false, depending on whether the cleanup process has been performed already.


Returns the associated session object.


Return the session key.

Getting and Setting Data


Retrieve the values from the flash for the specified key.

An undefined value is returned if the key does not exist.

If only a single piece of data is in the flash for the key then it is returned. Otherwise all of the data is returned. This method is context aware so if there are multiple pieces of data for the key then they will be returned as an arrayref in scalar context.

$flash->set('KEY' => @values)

Set the values in the flash. Values can be a single item or a list of items. Internally they are stored as an arrayref.

Keep in mind that since we are storing the data for the flash in the session that it is best to just store simple things and not complex objects.

$flash->now('KEY' => @values)

This method is very similar to set. It takes the same arguments and sets the data in the flash. The primary difference is that after the data is set in the flash, a call to discard is made for the key. This causes the data to removed on the next call to cleanup.

Contents and Keys


This returns a hashref that represents the contents of the flash. The keys are the keys in the flash and the values are an arrayref of the values.

This is not likely to be called directly, instead using get. This method is used internally when storing the flash data into the session.


Returns a list of keys that are currently marked as being kept. If called in scalar context then it will return an arrayref.


Returns a list of keys that are in the flash.


Returns true or false depending on if the flash contains the specified key.


Returns true or false depending on if the flash is empty.


Reset the flash. This wipes all data and kept keys.


When an object goes out of scope the flush method is automatically called. This will perform a cleanup if it has not already been done.


Mark the specified keys as being kept. If no keys are specified then all keys currently in the flash will be kept. See cleanup for details on how this works.

Call this method if you know you want to keep everything for an additional life cycle.


Mark the specified keys as being discarded. If no keys are specified then all keys currently in the flash will be marked as being discarded. Once marked as discarded they will be removed the next time that cleanup is called.


Perform cleanup of the flash.

This method goes through all of the keys in the flash. If the key is not marked as being kept it is removed. If it is marked as being kept then it is not removed, but it is instead marked as being discarded for the next time that the method is called. Generally this method is not directly called, but instead automatically called during flush.

The cleanup process is tracked so that it will not run more than once unless you pass a true value to specify force.


Perform cleanup then save the contents of the flash back into the session. This is automatically called when the flash object is destroyed.



This method returns a Data::Dumper representation of the contents of the flash. This is useful for debugging purposes.


The flush method is automatically called when the object is destroyed. However, there can be times when an object may not get properly destroyed such as in the event of a circular reference. Because of this, you may want to explicitly call flush in your cleanup code.


Please report any bugs or feature requests to bug-cgi-session-flash at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


The flash object is useful for passing data around between requests, but it is not always needed. Sometimes a simpler approach is better such as redirecting with a query parameter such as is_success=1 and then checking for that in your code. This is particularly useful when not using sessions.


The concept and name of this module was inspired by the Ruby on Rails framework.




Bradley C Bailey, <cgi-session-flash at>


Copyright 2008 Bradley C Bailey, all rights reserved.

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