Session Variable

Session Variable is a Drupal module to help you use session variables the same way you use Drupal variables. When session variables are appropriate, they are faster. Read the What, When, Where, and Why of session variables.

What

Drupal is based on PHP code. One of the first things you learn about PHP is variables including arrays. Arrays are lists of variables and, as arrays are variables, an entry in an array can be an array. The session variable is an array that is passed automatically from one page to another when you browse a web site. The session variable can carry any data you like from page to page.

Session Variable supplies easy functions for storing data in the session. If you write Drupal code, you know how to use the Drupal variable functions, variable_set, variable_get, and variable_delete. Session Variable supplies an equivalent session_variable_set, session_variable_get, and session_variable_delete plus additional functions for testing your code.

When

A session is created by Drupal after Drupal processes part of the Drupal code. Sessions require HTML cookie headers and once the HTML headers are set, you cannot redirect a page. Drupal performs page redirects first then starts a session. Most of your code runs after the session is set. An initialisation function might run before the session is set. You can use session_variable_check_session() to test for an active session. See session_variable.test.txt for an example.

A session is created when a visitor arrives at your site and is deleted when some time has expired. Some content management systems create a new session when a user logs. Many content management systems delete the current session when a user logs out. You can pass session variables for one user from page to page but you may lose the variables if the user logs in or logs out or goes out to lunch.

A session is unique to a visitor. If you want information accessed by all visitors, use the Drupal variable functions.

Where

You can use Session Variable functions anywhere in your module code and in content with an input format that includes PHP code. If you write startup code, code designed to run very early in the Drupal startup sequence, the session may not exist. There is a function to test for a session.

Why

The Drupal variable system has to store code in in the database and it stores each variable as a separate row, creating overheads. Sessions already exist. There is one session read when you visit a page and one session write after the code completes the processing of the page. You can add a variable to the session without increasing the number of reads or writes. Your code is more efficient.

Some data is too large for the way some systems handle sessions and the same data would be too large for the Drupal variable system. If your data fits in a Drupal variable then it can fit in a session variable with less overhead.

Some data is only ever temporary. As an example, a visitor to your site might ask for an exchange rate from one currency to another. You look up the exchange rate using a Web service. There are 200 countries in the world with most having unique currencies. You could have 200 x 200 exchange rates, a total of 40,000. Your Web service might provide new exchange rates every 5 minutes. Do you want to store 40,000 exchange rates in a database and update them every 5 minutes? Not is you have only a few thousand users of your Web site. You could write your code to get the current exchange rate for that user and store it in the session for 5 minutes.

In the exchange rate example, you may choose to store a temporary copy of the exchange rate in the Web service providing the exchange rate so the exchange rate can be automatically updated. Web services have a greater overhead than a session variable and you would not want to continually access a Web service if you can replace most of the accesses with a session variable. The ideal would be to receive an exchange rate and an expiry time for the rate. You would store the rate and the expiry time in the session then use the value from the session until it expires.

session_variable.zip

session_variable.zip contains all the files you need to install and test Session Variable. Download session_variable.zip. Expand the .zip file then copy the resultant directory to your sites/all/modules directory. In Drupal, select Administer » Site building » Modules then activate Session Variable. session_variable.tar.gz contains exactly the same files compressed a different way.

session_variable.info

session_variable.info is required by Drupal to identify the module.

session_variable.module

session_variable.module contains the code used by Drupal.

session_variable.test.txt

session_variable.test.txt is included in the download to test the module. After you activate the module, create a Drupal page with a input format of PHP then copy the test text into the page and preview. You will see the result of the test. You do not have to save the page because you always have the test text if you want to test again.

Test the code

Here is a test of session_variable.test.txt copied direct into this page.

name = Session Variable
description = Store variables in your session. From PeterMoulding.com.
copyright PeterMoulding.com 2007. Free for use with Drupal.
version = "6.0-1.0"
package = "Pet"
core = 6.x
Session variable is not installed.

Documentation

Here are the functions provided by Session Variable.

session_variable_set

session_variable_set($module, $name, $value = '')

You put data into a variable using session_variable_set. The format is similar to the Drupal variable_set with the addition of your module name to make your variables unique. The module value could be anything when used outside a module. Code in a page content could use the title of the page.

The value is optional for those occasions when you want to set a quick default value for a string. The value could be an object or any other type of variable. For objects, PHP stores only the data from an object in the session. The class code for the object has to be loaded before you can get the object from the session. PHP can autoload classes if your PHP is set up with the right configuration.

Here is an example of storing variable test for module example.

session_variable_set('example', 'test', 'Some data');

session_variable_get

session_variable_get($module, $name)

You get data from a variable using session_variable_get. The format is similar to the Drupal variable_get with the addition of your module name.

If the value is an object, the class code for the object has to be loaded before you can get the object from the session. See the comments in session_variable_set.

Here is an example of getting variable test for module example.

session_variable_get('example', 'test');

session_variable_delete

session_variable_delete($module, $name)

When you are finished with a variable, delete the variable so the session does not bloat from too many variables. The format is similar to the Drupal variable_delete with the addition of your module name.

This function returns true if the variable exists and false if the variable does not exist.

Here is an example of deleting variable test for module example.

session_variable_delete('example', 'test');

session_variable_is

session_variable_is($module, $name)

There are times when you want to find out if the module is created. You cannot always test for a default value because some variables have wide variety of value values. This function returns true if the variable is in the list of variables for the module and false if the variable does not exist.

Here is an example of checking variable test for module example.

if(session_variable_is('example', 'test'))

session_variable_check_module

session_variable_check_module($module)

Are you using replacing the module name with a value from a title or a similar unknown field? you can use session_variable_check_module to check the validity of the value. This check is not important because the module field is cleaned up before use.

Here is an example of checking variable $title.

if(session_variable_check_module($title))

session_variable_check_session

session_variable_check_session()

Does the session exist at the point where you want to use session variables? In most cases, yes. For page content, always yes. You can add a test for the session when first developing a module. This function returns true when the session exists and false when the session does not exist. Here is an example of checking for a session.

if(session_variable_check_session())

session_variable_safe

session_variable_($name = '')

You will not need this function. It is an internal function using a quick simple method to make a string safe for use as a variable name. You could use it if you want to use a safe name outside of Session Variable. Here is an example of making a string safe for use as a variable name.

$safe_name = session_variable_safe('Example string')