6.7. PHP

6.7.1. Quick Reference

Return Type Name Arguments
QdbBatch QdbBatch::__construct (void)
QdbBatch::compareAndSwap (string $alias, string $new_content, string $comparand [, int $expiry_time = 0 ] )
QdbBatch::get (string $alias)
QdbBatch::getRemove (string $alias)
QdbBatch::getUpdate (string $alias, string $content [, int $expiry_time = 0 ])
QdbBatch::put (string $alias, string $content [, int $expiry_time = 0 ])
QdbBatch::remove (string $alias)
QdbBatch::removeIf (string $alias, string $comparand)
QdbBatch::update (string $alias, string $content [, int $expiry_time = 0 ])
QdbCluster QdbCluster::__construct (array $nodes)
string QdbCluster::compareAndSwap (string $alias, string $new_content, string $comparand [, int $expiry_time = 0 ] )
QdbCluster::expiresAt (string $alias, int $expiry_time)
QdbCluster::expiresFromNow (string $alias, int $time_delta)
string QdbCluster::get (string $alias)
int QdbCluster::getExpiryTime (string $alias)
QdbCluster::getRemove (string $alias)
string QdbCluster::getUpdate (string $alias, string $content [, int $expiry_time = 0 ])
QdbCluster::put (string $alias, string $content [, int $expiry_time = 0 ])
QdbCluster::remove (string $alias)
bool QdbCluster::removeIf (string $alias, string $comparand)
QdbBatchResult QdbCluster::runBatch (QdbBatch $batch)
QdbCluster::update (string $alias, string $content [, int $expiry_time = 0 ])

6.7.2. Introduction

Using quasardb cluster from a PHP program is extremely straightforward, just create a QdbCluster and perform the operations.

$nodes = array(array('address' => '127.0.0.1', 'port' => 2836));

$cluster = new QdbCluster($nodes);
$cluster->put('key 0', 'value 0');
$cluster->put('key 1', 'value 1');
$value2 = $cluster->get('key 2');

Not fast enough? Try the QdbBatch class:

$batch = new QdbBatch();
$batch->put('key 0', 'value 0');
$batch->put('key 1', 'value 1');
$batch->get('key 2');

$result = $cluster->runBatch($batch);

$value2 = $result[2];

This will reduce the number of network request and it will be faster by orders of magnitudes.

6.7.3. Requirements and Installation

6.7.3.1. Linux

The example below assumes the following:
  1. php and php-devel are installed
  2. qdb-capi is installed in /path/to/qdb_capi
  3. qdb-php-api.tar.gz has been downloaded

Please adapt to your configuration.

Instructions:

tar xvf qdb-php-api.tar.gz
cd qdb-php-api
phpize
./configure --with-qdb=/path/to/qdb_capi
make
make install

6.7.3.2. Windows

The example below assumes the following:
  1. Visual Studio is installed
  2. PHP source code is decompressed in ‘C:php-src’
  3. ‘qdb-capi’ is installed in ‘C:qdb-capi’
  4. ‘qdb-php-api.tar.gz’ has been decompressed in ‘C:php-srcextqdb’

Please adapt to your configuration.

Instructions
  1. If ‘qdb_api.dll’ is not available on the ‘PATH’, copy it to ‘C:php’.

  2. Open a Visual Studio Developer Command Prompt (either x86 or x64).

  3. Type:

    cd /d C:\php-src\
    buildconf
    configure --with-qdb=C:\qdb-capi
    nmake
    nmake install
    

    You may want to customize configure’s flags, for instance ‘–enable-zts’ or ‘–disable-zts’ to control thread-safety.

6.7.4. Runtime configuration

The following settings can be changed in php.ini:

  • qdb.log_level - Specifies the log verbosity. Allowed values are detailed, debug, info, warning, error, panic. The default is panic.

6.7.5. Reference

6.7.5.1. The QdbBatch class

Represents a collection of operations that can be executed with a single query.

Operations are executed by a call to QdbCluster::runBatch ( $batch )

Example:

$batch = new QdbBatch();
$batch->put('key 0', 'value 0');
$batch->put('key 1', 'value 1');
$batch->get('key 2');

$result = $cluster->runBatch($batch);

$value2 = $result[2];
class QdbBatch
__construct(void)

Creates an empty batch, i.e. an empty collection of operations. Batch operations can greatly increase performance when it is necessary to run many small operations.

Operations in a QdbBatch are not executed until QdbCluster::runBatch is called.

Returns:An empty QdbBatch collection.
compareAndSwap(string $alias, string $new_content, string $comparand[, int $expiry_time = 0])

Adds a “compare and swap” operation to the batch. When executed, the “compare and swap” operation atomically compares the entry with $comparand and updates it to $new_content if, and only if, they match. If the entry does not exist, a QdbAliasNotFoundException will be thrown when reading the value.

Parameters:
  • $alias (string) – A string representing the entry’s alias to compare to.
  • $new_content (string) – A string representing the entry’s content to be updated in case of match.
  • $comparand (string) – A string representing the entry’s content to be compared to.
  • $expiry_time (int) – The absolute expiry time of the entry, in seconds, relative to epoch.
Returns:

The original value of the entry is stored in the array returned by QdbCluster::runBatch.

get(string $alias)

Adds a “get” operation to the batch. When executed, the “get” operation retrieves an entry’s content.

If the entry does not exist, a QdbAliasNotFoundException will be thrown when reading the value.

Parameters:
  • $alias (string) – A string representing the entry’s alist to retrieve.
Returns:

The value of the entry is stored in the array returned by QdbCluster::runBatch.

getRemove(string $alias)

Adds a “get and remove” operation to the batch. When executed, the “get and remove” operation atomically gets an entry and removes it.

If the entry does not exist, a QdbAliasNotFoundException will be thrown when reading the content.

Parameters:
  • $alias (string) – A string representing the entry’s alist to retrieve.
Returns:

The value of the entry is stored in the array returned by QdbCluster::runBatch.

getUpdate(string $alias, string $content[, int $expiry_time = 0])

Adds a “get and update” operation to the batch. When executed, the “get and update” operation atomically gets and updates (in this order) the entry.

If the entry does not exist, a QdbAliasNotFoundException will be throw when reading the value.

Parameters:
  • $alias (string) – a string representing the entry’s alias to update.
  • $content (string) – a string representing the entry’s content to be set.
  • $expiry_time (int) – the absolute expiry time of the entry, in seconds, relative to epoch.
Returns:

The content of the entry (before the update) is stored in the array returned by QdbCluster::runBatch.

put(string $alias, string $content[, int $expiry_time = 0])

Adds a “put” operation to the batch. When executed, the “put” operation adds an entry. Aliases beginning with “qdb” are reserved and cannot be used.

Parameters:
  • $alias (string) – a string string representing the entry’s alias to create.
  • $content (string) – a string representing the entry’s content to be added.
  • expiry_time (int) – the absolute expiry time of the entry, in seconds, relative to epoch
remove(string $alias)

Adds a “remove” operation to the batch. When executed, the “remove” operation removes an entry.

If the entry does not exist, the operation will fail and a QdbAliasNotFoundException will be thrown when reading the matching item of the array returned by QdbCluster::runBatch.

Parameters:
  • $alias (string) – a string representing the entry’s alias to delete.
removeIf(string $alias, string $comparand)

Adds a “remove if” operation to the batch. When executed, the “remove if” operation removes an entry if it matches $comparand. The operation is atomic.

If the entry does not exist, the operation will fail and a QdbAliasAlreadyExistsException will be throw when reading the matching item of the array returned by QdbCluster::runBatch.

Parameters:
  • $alias (string) – a string representing the entry’s alias to delete.
  • $comparand (string) – a string representing the entry’s content to be compared to.
Returns:

The result of the operation, true if the entry was actually removed or false otherwise, is stored in the array returned by QdbCluster::runBatch.

update(string $alias, string $content[, int $expiry_time = 0])

Adds an “update” operation to the batch. When executed, the “update” operation updates an entry. If the entry already exists, the content will be updated. If the entry does not exist, it will be created.

Aliases beginning with “qdb” are reserved and cannot be used.

Parameters:
  • $alias (string) – a string representing the entry’s alias to update.
  • $content (string) – a string representing the entry’s content to be added.
  • $expiry_time` (int) – the absolute expiry time of the entry, in seconds, relative to epoch

6.7.5.2. The QdbCluster class

Represents a connection to a quasardb cluster.

Example:

$nodes = array(array('address' => '127.0.0.1', 'port' => 2836));

$cluster = new QdbCluster($nodes);
$cluster->put('key 0', 'value 0');
$cluster->put('key 1', 'value 1');
$value2 = $cluster->get('key 2');
class QdbCluster
__construct(array $nodes)

Connects to a quasardb cluster through an array of arrays.

$nodes = array(
    array('address'=>'192.168.0.1','port'=>'2836'),
    array('address'=>'192.168.0.2','port'=>'2836')
);

Throws a QdbClusterConnectionFailedException if the connection to every node fails.

Parameters:
  • $nodes (array) – An array of arrays.
Returns:

a QdbCluster object.

compareAndSwap(string $alias, string $new_content, string $comparand[, int $expiry_time = 0])

Atomically compares the entry with $comparand and updates it to $new_content if, and only if, they match.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias to compare to.
  • $new_content (string) – a string representing the entry’s content to be updated in case of match.
  • $comparand (string) – a string representing the entry’s content to be compared to.
Returns string:

Always returns the original value of the entry.

expiresAt(string $alias, int $expiry_time)

Sets the expiry time of an existing entry. An $expiry_time of zero means the entry never expires.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias for which the expiry must be set.
  • $expiry_time (int) – absolute time after which the entry expires, in seconds, relative to epoch.
expiresFromNow(string $alias, int $time_delta)

Sets the expiry time of an existing entry. An $expiry_time of zero means the entry expires as soon as possible.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias for which the expiry must be set.
  • $expiry_time (int) – time in seconds, relative to the call time, after which the entry expires.
get(string $alias)

Retrieves an entry’s content.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias whose content is to be retrieved.
Returns string:

A string representing the entry’s content.

getExpiryTime(string $alias)

Retrieves the expiry time of an existing entry. A value of zero means the entry never expires.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias for which the expiry must be get.
Returns int:

The absolute expiry time, in seconds since epoch.

getRemove(string $alias)

Atomically gets an entry and removes it.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias to delete.
Returns string:

A string representing the entry’s content.

getUpdate(string $alias, string $content[, int $expiry_time = 0])

Atomically gets and updates (in this order) the entry.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias to update.
  • $content (string) – a string representing the entry’s content to be set.
  • $expiry_time (int) – the absolute expiry time of the entry, in seconds, relative to epoch.
Returns string:

A string representing the entry’s content, before the update.

put(string $alias, string $content[, int $expiry_time = 0])

Adds an entry. Aliases beginning with “qdb” are reserved and cannot be used.

Throws a QdbAliasAlreadyExistsException if the entry already exists.

Parameters:
  • $alias (string) – a string representing the entry’s alias to create.
  • $content (string) – a string representing the entry’s content to be added.
  • $expiry_time (int) – the absolute expiry time of the entry, in seconds, relative to epoch
remove(string $alias)

Removes an entry.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias – a string representing the entry’s alias to delete.
removeIf(string $alias, string $comparand)

Removes an entry if it matches $comparand.

Throws a QdbAliasNotFoundException if the entry does not exist.

Parameters:
  • $alias (string) – a string representing the entry’s alias to delete.
  • $comparand (string) – a string representing the entry’s content to be compared to.
Returns bool:

true if the entry was actually removed, false if not.

runBatch(QdbBatch $batch)

Executes operations of a QdbBatch.

An exception related to an operation will be thrown when reading the matching item from the returned array.

Parameters:
  • $batch (QdbBatch) – a QdbBatch containing the operations to be performed.
Returns:

Returns an array (more exactly a class QdbBatchResult that behaves like an array) with the operation results. Operations results are stored in the order in which operations have been added to the QdbBatch, which is not necessarily the order in which operation are executed in the cluster.

update(string $alias, string $content[, int $expiry_time = 0])

Updates an entry. Aliases beginning with “qdb” are reserved and cannot be used.

Parameters:
  • $alias (string) – a string representing the entry’s alias to update.
  • $content (string) – a string representing the entry’s content to be added.
  • $expiry_time (int) – the absolute expiry time of the entry, in seconds, relative to epoch