SimpleSAML_Memcache Class Reference

Collaboration diagram for SimpleSAML_Memcache:

Static Public Member Functions
static	get ($key)
	Find data stored with a given key. More...
static	set ($key, $value, $expire=null)
	Save a key-value pair to the memcache servers. More...
static	delete ($key)
	Delete a key-value pair from the memcache servers. More...
static	getStats ()
	This function retrieves statistics about all memcache server groups. More...
static	getRawStats ()
	Retrieve statistics directly in the form returned by getExtendedStats, for all server groups. More...

Static Private Member Functions
static	addMemcacheServer ($memcache, $server)
	This function adds a server from the 'memcache_store.servers' configuration option to a Memcache object. More...
static	loadMemcacheServerGroup (array $group)
	This function takes in a list of servers belonging to a group and creates a Memcache object from the servers in the group. More...
static	getMemcacheServers ()
	This function gets a list of all configured memcache servers. More...
static	getExpireTime ()
	This is a helper-function which returns the expire value of data we should store to the memcache servers. More...

Static Private Attributes
static	$serverGroups = null
static	$extension = ''

Detailed Description

Definition at line 20 of file Memcache.php.

Member Function Documentation

addMemcacheServer()

static SimpleSAML_Memcache::addMemcacheServer (   $memcache,   $server  )

staticprivate

This function adds a server from the 'memcache_store.servers' configuration option to a Memcache object.

The server parameter is an array with the following keys:

• hostname Hostname or ip address to the memcache server.
• port (optional) port number the memcache server is running on. This defaults to memcache.default_port if no value is given. The default value of memcache.default_port is 11211.
• weight (optional) The weight of this server in the load balancing cluster.
• timeout (optional) The timeout for contacting this server, in seconds. The default value is 3 seconds.

Parameters

Memcache	$memcache	The Memcache object we should add this server to.
array	$server	An associative array with the configuration options for the server to add.

Exceptions

Exception

If any configuration option for the server is invalid.

Definition at line 215 of file Memcache.php.

References $memcache, and $server.

    {
        // the hostname option is required
        if (!array_key_exists('hostname', $server)) {
            throw new Exception(
                "hostname setting missing from server in the 'memcache_store.servers' configuration option."
            );
        }

        $hostname = $server['hostname'];

        // the hostname must be a valid string
        if (!is_string($hostname)) {
            throw new Exception(
                "Invalid hostname for server in the 'memcache_store.servers' configuration option. The hostname is".
                ' supposed to be a string.'
            );
        }

        // check if we are told to use a socket
        $socket = false;
        if (strpos($hostname, 'unix:///') === 0) {
            $socket = true;
        }

        // check if the user has specified a port number
        if ($socket) {
            // force port to be 0 for sockets
            $port = 0;
        } elseif (array_key_exists('port', $server)) {
            // get the port number from the array, and validate it
            $port = (int) $server['port'];
            if (($port <= 0) || ($port > 65535)) {
                throw new Exception(
                    "Invalid port for server in the 'memcache_store.servers' configuration option. The port number".
                    ' is supposed to be an integer between 0 and 65535.'
                );
            }
        } else {
            // use the default port number from the ini-file
            $port = (int) ini_get('memcache.default_port');
            if ($port <= 0 || $port > 65535) {
                // invalid port number from the ini-file. fall back to the default
                $port = 11211;
            }
        }

        // check if the user has specified a weight for this server
        if (array_key_exists('weight', $server)) {
            // get the weight and validate it
            $weight = (int) $server['weight'];
            if ($weight <= 0) {
                throw new Exception(
                    "Invalid weight for server in the 'memcache_store.servers' configuration option. The weight is".
                    ' supposed to be a positive integer.'
                );
            }
        } else {
            // use a default weight of 1
            $weight = 1;
        }

        // check if the user has specified a timeout for this server
        if (array_key_exists('timeout', $server)) {
            // get the timeout and validate it
            $timeout = (int) $server['timeout'];
            if ($timeout <= 0) {
                throw new Exception(
                    "Invalid timeout for server in the 'memcache_store.servers' configuration option. The timeout is".
                    ' supposed to be a positive integer.'
                );
            }
        } else {
            // use a default timeout of 3 seconds
            $timeout = 3;
        }

        // add this server to the Memcache object
        if (self::$extension === 'memcached') {
            $memcache->addServer($hostname, $port);
        } else {
            $memcache->addServer($hostname, $port, true, $weight, $timeout, $timeout, true);
        }
    }

delete()

static SimpleSAML_Memcache::delete (   $key )

static

Delete a key-value pair from the memcache servers.

Parameters

string

$key

The key we should delete.

Definition at line 180 of file Memcache.php.

References $key, $server, and SimpleSAML\Logger\debug().

Referenced by SimpleSAML\Store\Memcache\delete().

    {
        assert('is_string($key)');
        SimpleSAML\Logger::debug("deleting key $key from memcache");

        // store this object to all groups of memcache servers
        foreach (self::getMemcacheServers() as $server) {
            $server->delete($key);
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

get()

static SimpleSAML_Memcache::get (   $key )

static

Find data stored with a given key.

Parameters

string

$key

The key of the data.

Returns

mixed The data stored with the given key, or null if no data matching the key was found.

Definition at line 46 of file Memcache.php.

References $info, $key, $server, SimpleSAML\Logger\debug(), and SimpleSAML\Logger\warning().

    {
        SimpleSAML\Logger::debug("loading key $key from memcache");

        $latestInfo = null;
        $latestTime = 0.0;
        $latestData = null;
        $mustUpdate = false;
        $allDown = true;

        // search all the servers for the given id
        foreach (self::getMemcacheServers() as $server) {
            $serializedInfo = $server->get($key);
            if ($serializedInfo === false) {
                // either the server is down, or we don't have the value stored on that server
                $mustUpdate = true;
                $up = $server->getstats();
                if ($up !== false) {
                    $allDown = false;
                }
                continue;
            }
            $allDown = false;

            // unserialize the object
            $info = unserialize($serializedInfo);

            /*
             * Make sure that this is an array with two keys:
             * - 'timestamp': The time the data was saved.
             * - 'data': The data.
             */
            if (!is_array($info)) {
                SimpleSAML\Logger::warning(
                    'Retrieved invalid data from a memcache server. Data was not an array.'
                );
                continue;
            }
            if (!array_key_exists('timestamp', $info)) {
                SimpleSAML\Logger::warning(
                    'Retrieved invalid data from a memcache server. Missing timestamp.'
                );
                continue;
            }
            if (!array_key_exists('data', $info)) {
                SimpleSAML\Logger::warning(
                    'Retrieved invalid data from a memcache server. Missing data.'
                );
                continue;
            }

            if ($latestInfo === null) {
                // first info found
                $latestInfo = $serializedInfo;
                $latestTime = $info['timestamp'];
                $latestData = $info['data'];
                continue;
            }

            if ($info['timestamp'] === $latestTime && $serializedInfo === $latestInfo) {
                // this data matches the data from the other server(s)
                continue;
            }

            // different data from different servers. We need to update at least one of them to maintain sync
            $mustUpdate = true;

            // update if data in $info is newer than $latestData
            if ($latestTime < $info['timestamp']) {
                $latestInfo = $serializedInfo;
                $latestTime = $info['timestamp'];
                $latestData = $info['data'];
            }
        }

        if ($latestData === null) {
            if ($allDown) {
                // all servers are down, panic!
                $e = new SimpleSAML_Error_Error('MEMCACHEDOWN', null, 503);
                throw new SimpleSAML_Error_Exception('All memcache servers are down', 503, $e);
            }
            // we didn't find any data matching the key
            SimpleSAML\Logger::debug("key $key not found in memcache");
            return null;
        }

        if ($mustUpdate) {
            // we found data matching the key, but some of the servers need updating
            SimpleSAML\Logger::debug("Memcache servers out of sync for $key, forcing sync");
            self::set($key, $latestData);
        }

        return $latestData;
    }

Here is the call graph for this function:

getExpireTime()

static SimpleSAML_Memcache::getExpireTime ( )

staticprivate

This is a helper-function which returns the expire value of data we should store to the memcache servers.

The value is set depending on the configuration. If no value is set in the configuration, then we will use a default value of 0. 0 means that the item will never expire.

Returns

integer The value which should be passed in the set(...) calls to the memcache objects.

Exceptions

Exception

If the option 'memcache_store.expires' has a negative value.

Definition at line 416 of file Memcache.php.

References $config, $expire, SimpleSAML_Configuration\getInstance(), and time.

    {
        // get the configuration instance
        $config = SimpleSAML_Configuration::getInstance();
        assert($config instanceof SimpleSAML_Configuration);

        // get the expire-value from the configuration
        $expire = $config->getInteger('memcache_store.expires', 0);

        // it must be a positive integer
        if ($expire < 0) {
            throw new Exception(
                "The value of 'memcache_store.expires' in the configuration can't be a negative integer."
            );
        }

        /* If the configuration option is 0, then we should return 0. This allows the user to specify that the data
         * shouldn't expire.
         */
        if ($expire == 0) {
            return 0;
        }

        /* The expire option is given as the number of seconds into the future an item should expire. We convert this
         * to an actual timestamp.
         */
        $expireTime = time() + $expire;

        return $expireTime;
    }

Here is the call graph for this function:

getMemcacheServers()

static SimpleSAML_Memcache::getMemcacheServers ( )

staticprivate

This function gets a list of all configured memcache servers.

This list is initialized based on the content of 'memcache_store.servers' in the configuration.

Returns

Memcache[] Array with Memcache objects.

Exceptions

Exception

If the servers configuration is invalid.

Definition at line 357 of file Memcache.php.

References $config, $index, array, and SimpleSAML_Configuration\getInstance().

    {
        // check if we have loaded the servers already
        if (self::$serverGroups != null) {
            return self::$serverGroups;
        }

        // initialize the servers-array
        self::$serverGroups = array();

        // load the configuration
        $config = SimpleSAML_Configuration::getInstance();


        $groups = $config->getArray('memcache_store.servers');

        // iterate over all the groups in the 'memcache_store.servers' configuration option
        foreach ($groups as $index => $group) {
            // make sure that the group doesn't have an index. An index would be a sign of invalid configuration
            if (!is_int($index)) {
                throw new Exception(
                    "Invalid index on element in the 'memcache_store.servers'".
                    ' configuration option. Perhaps you have forgotten to add an array(...)'.
                    ' around one of the server groups? The invalid index was: '.$index
                );
            }

            /*
             * Make sure that the group is an array. Each group is an array of servers. Each server is
             * an array of name => value pairs for that server.
             */
            if (!is_array($group)) {
                throw new Exception(
                    "Invalid value for the server with index ".$index.
                    ". Remeber that the 'memcache_store.servers' configuration option".
                    ' contains an array of arrays of arrays.'
                );
            }

            // parse and add this group to the server group list
            self::$serverGroups[] = self::loadMemcacheServerGroup($group);
        }

        return self::$serverGroups;
    }

Here is the call graph for this function:

getRawStats()

static SimpleSAML_Memcache::getRawStats ( )

static

Retrieve statistics directly in the form returned by getExtendedStats, for all server groups.

Returns

array An array with the extended stats output for each server group.

Definition at line 482 of file Memcache.php.

References $ret, $stats, and array.

Referenced by memcacheMonitor_hook_sanitycheck().

    {
        $ret = array();

        foreach (self::getMemcacheServers() as $sg) {
            $stats = method_exists($sg, 'getExtendedStats') ? $sg->getExtendedStats() : $sg->getStats();
            $ret[] = $stats;
        }

        return $ret;
    }

Here is the caller graph for this function:

getStats()

static SimpleSAML_Memcache::getStats ( )

static

This function retrieves statistics about all memcache server groups.

Returns

array Array with the names of each stat and an array with the value for each server group.

Exceptions

Exception

If memcache server status couldn't be retrieved.

Definition at line 455 of file Memcache.php.

References $data, $ret, $server, $stats, array, and SimpleSAML\Utils\Arrays\transpose().

    {
        $ret = array();

        foreach (self::getMemcacheServers() as $sg) {
            $stats = method_exists($sg, 'getExtendedStats') ? $sg->getExtendedStats() : $sg->getStats();
            foreach ($stats as $server => $data) {
                if ($data === false) {
                    throw new Exception('Failed to get memcache server status.');
                }
            }

            $stats = SimpleSAML\Utils\Arrays::transpose($stats);

            $ret = array_merge_recursive($ret, $stats);
        }

        return $ret;
    }

Here is the call graph for this function:

loadMemcacheServerGroup()

static SimpleSAML_Memcache::loadMemcacheServerGroup ( array  $group )

staticprivate

This function takes in a list of servers belonging to a group and creates a Memcache object from the servers in the group.

Parameters

array

$group

Array of servers which should be created as a group.

Returns

Memcache A Memcache object of the servers in the group

Exceptions

Exception

If the servers configuration is invalid.

Definition at line 311 of file Memcache.php.

References $index, $memcache, and $server.

    {
        $class = class_exists('Memcache') ? 'Memcache' : (class_exists('Memcached') ? 'Memcached' : FALSE);
        if (!$class) {
            throw new Exception('Missing Memcached implementation. You must install either the Memcache or Memcached extension.');
        }
        self::$extension = strtolower($class);

        // create the Memcache object
        $memcache = new $class();

        // iterate over all the servers in the group and add them to the Memcache object
        foreach ($group as $index => $server) {
            // make sure that we don't have an index. An index would be a sign of invalid configuration
            if (!is_int($index)) {
                throw new Exception(
                    "Invalid index on element in the 'memcache_store.servers' configuration option. Perhaps you".
                    ' have forgotten to add an array(...) around one of the server groups? The invalid index was: '.
                    $index
                );
            }

            // make sure that the server object is an array. Each server is an array with name-value pairs
            if (!is_array($server)) {
                throw new Exception(
                    'Invalid value for the server with index '.$index.
                    '. Remeber that the \'memcache_store.servers\' configuration option'.
                    ' contains an array of arrays of arrays.'
                );
            }

            self::addMemcacheServer($memcache, $server);
        }

        return $memcache;
    }

set()

static SimpleSAML_Memcache::set (   $key,   $value,   $expire = null  )

static

Save a key-value pair to the memcache servers.

Parameters

string	$key	The key of the data.
mixed	$value	The value of the data.
integer | null	$expire	The expiration timestamp of the data.

Definition at line 149 of file Memcache.php.

References $key, $server, array, and SimpleSAML\Logger\debug().

Referenced by SimpleSAML\Store\Memcache\set().

    {
        SimpleSAML\Logger::debug("saving key $key to memcache");
        $savedInfo = array(
            'timestamp' => microtime(true),
            'data'      => $value
        );

        if ($expire === null) {
            $expire = self::getExpireTime();
        }

        $savedInfoSerialized = serialize($savedInfo);

        // store this object to all groups of memcache servers
        foreach (self::getMemcacheServers() as $server) {
            if (self::$extension === 'memcached') {
                $server->set($key, $savedInfoSerialized, $expire);
            }
            else {
                $server->set($key, $savedInfoSerialized, 0, $expire);
            }
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

Field Documentation

$extension

SimpleSAML_Memcache::$extension = ''

staticprivate

Definition at line 36 of file Memcache.php.

$serverGroups

SimpleSAML_Memcache::$serverGroups = null

staticprivate

Definition at line 28 of file Memcache.php.

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/simplesamlphp/simplesamlphp/lib/SimpleSAML/Memcache.php