Provides central static variable storage.

Provides central static variable storage.

All functions requiring a static variable to persist or cache data within a single page request are encouraged to use this function unless it is absolutely certain that the static variable will not need to be reset during the page request. By centralizing static variable storage through this function, other functions can rely on a consistent API for resetting any other function's static variables.


function language_list($field = 'language') {
  $languages = &drupal_static(__FUNCTION__);
  if (!isset($languages)) {
    // If this function is being called for the first time after a reset,
    // query the database and execute any other code needed to retrieve
    // information about the supported languages.
  if (!isset($languages[$field])) {
    // If this function is being called for the first time for a particular
    // index field, then execute code needed to index the information already
    // available in $languages by the desired field.
  // Subsequent invocations of this function for a particular index field
  // skip the above two code blocks and quickly return the already indexed
  // information.
  return $languages[$field];
function locale_translate_overview_screen() {
  // When building the content for the translations overview page, make
  // sure to get completely fresh information about the supported languages.

In a few cases, a function can have certainty that there is no legitimate use-case for resetting that function's static variable. This is rare, because when writing a function, it's hard to forecast all the situations in which it will be used. A guideline is that if a function's static variable does not depend on any information outside of the function that might change during a single page request, then it's ok to use the "static" keyword instead of the drupal_static() function.


function actions_do(...) {
  // $stack tracks the number of recursive calls.
  static $stack;
  if ($stack > variable_get('actions_max_stack', 35)) {

In a few cases, a function needs a resettable static variable, but the function is called many times (100+) during a single page request, so every microsecond of execution time that can be removed from the function counts. These functions can use a more cumbersome, but faster variant of calling drupal_static(). It works by storing the reference returned by drupal_static() in the calling function's own static variable, thereby removing the need to call drupal_static() for each iteration of the function. Conceptually, it replaces:

$foo =& drupal_static(__FUNCTION__);


// Unfortunately, this does not work.
static $foo = &drupal_static(__FUNCTION__);

However, the above line of code does not work, because PHP only allows static variables to be initializied by literal values, and does not allow static variables to be assigned to references.

  • http://php.net/manual/language.variables.scope.php#language.variables.scope.static
  • http://php.net/manual/language.variables.scope.php#language.variables.scope.references

The example below shows the syntax needed to work around both limitations. For benchmarks and more information, see http://drupal.org/node/619666.


function user_access($string, $account = NULL) {
  // Use the advanced drupal_static() pattern, since this is called very often.
  static $drupal_static_fast;
  if (!isset($drupal_static_fast)) {
    $drupal_static_fast['perm'] = &drupal_static(__FUNCTION__);
  $perm = &$drupal_static_fast['perm'];


mishly’s picture

Here is a good introduction to drupal_static as it relates to caching in D7 from Jeff Eaton here:


jeff.rigby’s picture

drupal_static() can also be used to access variables from any function. This is similar to using $_GLOBALS but drupal_static() gives you more control. For example, you can use drupal_static_reset() to clear out all static variables where clearing $_GLOBALS will remove essential Drupal variables.

For example:

function test_function_a() {
  $global_var = &drupal_static('my_global_var');
  $global_var['key1'] = 'value1';
  $global_var['key2'] = 'value2';
  return $global_var['key1'];

function test_function_b() {
  $global_var = &drupal_static('my_global_var');
  $global_var['key1'] = 'value3';
  return !empty($global_var['key2']) ? $global_var['key2'] : NULL;

function test_function_c() {
  $global_var = &drupal_static('my_global_var');
  return !empty($global_var['key1']) ? $global_var['key1'] : NULL;

print test_function_a(); // prints 'value1'
print test_function_b(); // prints 'value2'
print test_function_c(); // prints 'value3'
dbezdek’s picture

The usage above is very clear to me;

however, I keep seeing the following call (Which I don't understand at all):

$value = drupal_static(__FUNCTION__, NULL);

What is the difference between the above line and the following line:

$global_var = &drupal_static('my_global_var');

krisis’s picture

The __FUNCTION__ constant (most often referred to as a magic constant) contains the string value of the name of the currently executing function.

If you were to call &drupal_static(__FUNCTION__, $my_data) from within a function called my_function, this would in turn make drupal_static store your data ($my_data) under a key named after the function (__FUNCTION__ produced the value my_function).

littlethoughts’s picture

I am not sure which part you didn't understand, so I will explain the whole function call.

__FUNCTION__ is a magic constant returning a string with the function name. It is just another way to give the function a unique name.
If you call it with NULL, then you are setting the default value to NULL. Which is not necessary, because the default value for $default_value is already NULL. Both calls are essentially the same if you look at the parameters.

You should always call it by reference though, since this way you will get the reference to the variable.

afeijo’s picture

also in your question you asked about the 2nd parameter, it's default to NULL, so you don't need to call the function with NULL in it, it'd be redundant

Jaypan’s picture

Note that __FUNCTION__ only returns the function name. If you are using &drupal_static() from within a class (OOP), and you are using a generic function name, you can run into problems where your static cross-saves values from other classes.

An example of this is a load() function in a class for some sort of data retrieval function. Let's say you have a class called 'Share' and a class called 'Follow', and each of these have a load() function within the class. If you use &drupal_static() in both of these functions, your static values will pollute each other, since __FUNCTION__ only returns 'load', with no reference to the class in which the function is contained. In this case, you should use:

&drupal_static(__CLASS__ . '::' . __FUNCTION__);

Note that this construction is just my own suggestion, and you can use whatever you want in place of __FUNCTION__, just make sure that it will be unique.

travis uribe’s picture

You're looking for the __METHOD__ constant. That produces exactly the same value as __CLASS__ . '::' . __FUNCTION__