Methods

__construct()

__construct(array $hosts, string $user, string $password, string $bucket, boolean $persistent)

Parameters

array $hosts

An array of hostnames[:port] where the Couchbase cluster is running. The port number is optional (and only needed if you're using a non- standard port).

string $user

The username used for authentication to the cluster

string $password

The password used to authenticate to the cluster

string $bucket

The name of the bucket to connect to

boolean $persistent

If a persistent object should be used or not

add()

add(string $id, object $document, integer $expiry, integer $persist_to, integer $replicate_to) : string

Add a document to the cluster.

The add operation adds a document to the cluster only if no document exists in the cluster with the same identifier.

Parameters

string $id

the identifier to store the document under

object $document

the document to store

integer $expiry

the lifetime of the document (0 == infinite)

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value of the object if success

set()

set(string $id, object|string $document, integer $expiry, string $cas, integer $persist_to, integer $replicate_to) : string

Store a document in the cluster.

The set operation stores a document in the cluster. It differs from add and replace in that it does not care for the presence of the identifier in the cluster.

If the $cas field is specified, set will only succeed if the identifier exists in the cluster with the exact same cas value as the one specified in this request.

Parameters

string $id

the identifier to store the document under

object|string $document

the document to store

integer $expiry

the lifetime of the document (0 == infinite)

string $cas

a cas identifier to restrict the store operation

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value of the object if success

setMulti()

setMulti(array $documents, integer $expiry, integer $persist_to, integer $replicate_to) : boolean

Store multiple documents in the cluster.

Parameters

array $documents

an array containing "id" => "document" pairs

integer $expiry

the lifetime of the document (0 == infinite)

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true if success

replace()

replace(string $id, object $document, integer $expiry, string $cas, integer $persist_to, integer $replicate_to) : string

Replace a document in the cluster.

The replace operation replaces an existing document in the cluster. It differs from add and set in the way that it requires the precense of the identifier in the cluster.

If the $cas field is specified set will only succeed if the identifier exists in the cluster with the exact same cas value as the one specified in this request.

Parameters

string $id

the identifier to store the document under

object $document

the document to store

integer $expiry

the lifetime of the document (0 == infinite)

string $cas

a cas identifier to restrict the replace operation

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value of the object if success

prepend()

prepend(string $id, object $document, integer $expiry, string $cas, integer $persist_to, integer $replicate_to) : string

Prepend a document to another document.

The prepend operation prepends the attached document to the document already stored in the cluster.

If the $cas field is specified prepend will only succeed if the identifier exists in the cluster with the exact same cas value as the one specified in this request.

Parameters

string $id

identifies the document

object $document

the document to prepend

integer $expiry

the lifetime of the document (0 == infinite)

string $cas

a cas identifier to restrict the prepend operation

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value of the object if success

append()

append(string $id, object $document, integer $expiry, string $cas, integer $persist_to, integer $replicate_to) : string

Append a document to another document.

The append operation appends the attached document to the document already stored in the cluster.

If the $cas field is specified append will only succeed if the identifier exists in the cluster with the exact same cas value as the one specified in this request.

Parameters

string $id

identifies the document

object $document

the document to append

integer $expiry

the lifetime of the document (0 == infinite)

string $cas

a cas identifier to restrict the append operation

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value of the object if success

cas()

cas( $cas,  $id,  $document,  $expiry)

Please use replace with the $cas field specified.

Parameters

$cas
$id
$document
$expiry

get()

get(string $id, callable $callback, string $cas) : object

Retrieve a document from the cluster.

Parameters

string $id

identifies the object to retrieve

callable $callback

a callback function to call for missing objects. The function signature looks like: bool function($res, $id, &$val) if the function returns true the value returned through $val is returned. Please note that the cas field is not updated in these cases.

string $cas

where to store the cas identifier of the object

Throws

\CouchbaseException

if an error occurs

Returns

object —

The document from the cluster

getMulti()

getMulti(array $ids, array $cas, int $flags) : array

Retrieve multiple documents from the cluster.

Parameters

array $ids

an array containing all of the document identifiers

array $cas

an array to store the cas identifiers of the documents

int $flags

may be 0 or COUCHBASE_GET_PRESERVE_ORDER

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing the documents

getReplica()

getReplica(string $id, callable $callback, string $cas) : object

Retrieve a replica of a document from the cluster.

Please note that this method is currently experimental and its signature may change in a future release.

Parameters

string $id

identifies the object to retrieve

callable $callback

a callback function to call for missing objects. The function signature looks like: bool function($res, $id, &$val) if the function returns true the value returned through $val is returned. Please note that the cas field is not updated in these cases.

string $cas

where to store the cas identifier of the object

Throws

\CouchbaseException

if an error occurs

Returns

object —

The document from the cluster

getReplicaMulti()

getReplicaMulti(array $ids, array $cas) : array

Retrieve multiple replica documents from the cluster.

Please note that this method is currently experimental and its signature may change in a future release.

Parameters

array $ids

an array containing all of the document identifiers

array $cas

an array to store the cas identifiers of the documents

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing the documents

getAndLock()

getAndLock(string $id, string $cas, integer $expiry) : object

Retrieve an object from the cache and lock it from modifications.

While the object is locked it may only be modified by providing the cas field returned in the cas field. Modifying the object automatically unlocks the object. To manually unlock the object use the unlock() method. All locks is automatically released after a configurable (on the cluster) time interaval.

Parameters

string $id

identifies the document

string $cas

where to store the cas identifier

integer $expiry

a configuratble lock expiry time (0 == use the value configured on the server).

Throws

\CouchbaseException

if an error occurs

Returns

object —

The requested document from the cluster

getAndLockMulti()

getAndLockMulti(array $ids, array $cas, int $flags, integer $expiry) : array

Retrieve and lock multiple documents from the cache.

While the object is locked it may only be modified by providing the cas field returned in the cas field. Modifying the object automatically unlocks the object. To manually unlock the object use the unlock() method. All locks is automatically released after a configurable (on the cluster) time interaval.

Bear in mind that locking multiple objects at the same time may not be a good idea and may lead to deadlock ;-)

Parameters

array $ids

an array containing the identifiers to retrieve

array $cas

where to store the cas identifier

int $flags

TODO update document for this param

integer $expiry

a configuratble lock expiry time (0 == use the value configured on the server).

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containint the requested documents

getAndTouch()

getAndTouch(string $id, integer $expiry, string $cas) : object

Retrieve a document from the cluster and update its time to live.

Parameters

string $id

identifies the document

integer $expiry

the new time to live (0 == infinite)

string $cas

where to store the cas identifier

Throws

\CouchbaseException

if an error occurs

Returns

object —

The requested document from the cluster

getAndTouchMulti()

getAndTouchMulti(array $ids, integer $expiry, array $cas) : array

Retrieve multiple documents from the cluster and update their time to live.

Parameters

array $ids

an array containint the document identifiers

integer $expiry

the new time to live (0 == infinite)

array $cas

where to store the cas identifier

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing the requested documents

unlock()

unlock(string $id, string $cas) : boolean

Unlock a previously locked document.

Parameters

string $id

the document to unlock

string $cas

the cas value obtained from getAndLock()

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true upon success

touch()

touch(string $id, integer $expiry) : boolean

Touch (update time to live) a document in the cluster.

Parameters

string $id

identifies the document

integer $expiry

the new time to live (0 == infinite)

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true upon success

touchMulti()

touchMulti(array $ids, integer $expiry) : boolean

Touch (update time to live) multiple documents in the cluster.

Parameters

array $ids

an array containing the document identifiers

integer $expiry

the new time to live (0 == infinite)

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true upon success

delete()

delete(string $id, string $cas, integer $persist_to, integer $replicate_to) : string

Delete a document from the cluster.

Parameters

string $id

the document identifier

string $cas

a cas identifier to restrict the store operation

integer $persist_to

wait until the document is persisted to (at least) this many nodes

integer $replicate_to

wait until the document is replicated to (at least) this many nodes

Throws

\CouchbaseException

if an error occurs

Returns

string —

the cas value representing the delete document if success

increment()

increment(string $id, integer $delta, boolean $create, integer $expire, integer $initial) : integer

Increment a numeric value in the cluster.

If the value isn't created by using increment / decrement, it has to be created as a "textual" string like: $cb->add("mycounter", "0");. The reason for this is that the operation is performed in the cluster and it has to know the datatype in order to perform the operation.

Parameters

string $id

the document identifier

integer $delta

the amount to increment

boolean $create

should the value be created if it doesn't exist

integer $expire

the time to live for the document (0 == infinite)

integer $initial

the initial value for the counter if it doesn't exist

Throws

\CouchbaseException

if an error occurs

Returns

integer —

the new value upon success

decrement()

decrement(string $id, integer $delta, boolean $create, integer $expire, integer $initial) : integer

Decrement a numeric value in the cluster.

If the value isn't created by using increment / decrement, it has to be created as a "textual" string like: $cb->add("mycounter", "0");. The reason for this is that the operation is performed in the cluster and it has to know the datatype in order to perform the operation.

Parameters

string $id

the document identifier

integer $delta

the amount to decrement

boolean $create

should the value be created if it doesn't exist

integer $expire

the time to live for the document (0 == infinite)

integer $initial

the initial value for the counter if it doesn't exist

Throws

\CouchbaseException

if an error occurs

Returns

integer —

the new value upon success

flush()

flush() : boolean

Delete all documents in the bucket.

Please note that flush is disabled from the server by default, so it must explicitly be enabled on the bucket. Flush also require the object to be used to contain all the credentials (username, password and bucket name).

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true upon success

getDelayed()

getDelayed(array $ids, boolean $with_cas, callable $callback, integer $expiry, boolean $lock) : boolean

Issue a get request, but do not wait for responses.

Parameters

array $ids

the document identifiers to retrieve

boolean $with_cas

if the cas identifier should be retrieved

callable $callback

function to call per retrieved document

integer $expiry

lock expiry time

boolean $lock

if the documents should be locked or not

Throws

\CouchbaseException

if an error occurs

Returns

boolean —

true upon success, false otherwise

fetch()

fetch() : array

Fetch the one of the received documents requested from getDelayed.

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array representing the next document retrieved, or NULL if there are no more documents.

fetchAll()

fetchAll() : array

Fetch the one of the received documents requested from getDelayed.

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array representing the documents retrieved, or NULL if there are no more documents.

view()

view(string $document, string $view, array $options, boolean $return_errors) : array

Execute a view request.

The following options are recognized.

NameDatatype
descendingboolean
endkeyJSON value
endkey_docidstring
full_setboolean
groupboolean
group_levelnumeric
inclusive_endboolean
keyJSON
keysJSON array
on_errorcontinue or stop
reduceboolean
staleboolean
skipnumeric
limitnumeric
startkeyJSON
startkey_docidstring
debugboolean
connection_timeoutnumeric

Parameters

string $document

The design document containing the view to call

string $view

The view to execute

array $options

extra options to add to the view request (see above)

boolean $return_errors

Should error messages be returned upon failures

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array with the result of the view request upon success, or an array containing an error message

viewGenQuery()

viewGenQuery(string $document, string $view, array $options, boolean $return_errors) : string

Generate a view request.

Parameters

string $document

The design document containing the view to call

string $view

The view to execute

array $options

extra options to add to the view request (see view() for more information)

boolean $return_errors

Should error messages be returned upon failures

Throws

\CouchbaseException

if an error occurs

Returns

string —

generated view request in format: "/_design/$doc/_view/$view?stale=ok&..."

getStats()

getStats() : array

Retrieve statistics information from the cluster.

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing all "key" => "value" pairs upon success

getResultCode()

getResultCode() : integer

Get the last result code from the extension internals.

Returns

integer —

An error code representing the last error code as seen by libcouchbase

getResultMessage()

getResultMessage() : string

Get a textual representation of the last result from the extension internals.

Returns

string —

An textual string describing last error code as seen by libcouchbase

setOption()

setOption(integer $option, integer $value)

Update one of the tunables.

The following tunables exist:

NameDescription
COUCHBASE_OPT_SERIALIZERSpecifies the serializer to use to store objects in the cluster. The following values may be used: COUCHBASE_SERIALIZER_PHP, COUCHBASE_SERIALIZER_JSON, COUCHBASE_SERIALIZER_JSON_ARRAY
COUCHBASE_OPT_COMPRESSIONSpecifies the compression to use for big objects. It may be set to the following values: COUCHBASE_COMPRESSION_NONE, COUCHBASE_COMPRESSION_FASTLZ, COUCHBASE_COMPRESSION_ZLIB
COUCHBASE_OPT_PREFIX_KEYA text string used as a prefix for all keys (may be used to create your own namespace).
COUCHBASE_OPT_IGNOREFLAGSThis options is used to disable the deserialisation of the data received from the cluster. It is mainly used by the developers of the extension to be able to test variable parts of the API and should not be used by end users (it may be removed without notice if we find a better way to do this).

Parameters

integer $option

the option to set

integer $value

the new value for the option

Throws

\CouchbaseException

if an error occurs (e.g illegal option / value)

getOption()

getOption(integer $option) : integer

Retrieve the current value of a tunable.

Parameters

integer $option

the option to retrieve the value for

Throws

\CouchbaseException

if an error occurs (e.g illegal option)

Returns

integer —

The current value for a tunable. See setOption() for a description of the legal options to retrieve.

getVersion()

getVersion() : array

Get the version numbers of the memcached servers in the cluster.

This method does probably not do what you think it would do. It exists for compatibility with the "memcached" extension. It does not return the Couchbase version used on each node in the cluster, but rather an internal version number from the memcached nodes in the cluster.

The easiest way to get the Couchbase version nodes would be something among the lines of:

$cb = new CouchbaseClusterManager("localhost", "Administrator", "secret");
$info = json_decode($cb->getInfo());
foreach ($info->{"nodes"} as $node) {
   print $node->{"hostname"} . " is running " . $node->{"version"} . "\n";
}

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing the memcached version on each node

getClientVersion()

getClientVersion() : string

Retrieve the version number of the client.

Returns

string —

client library version number

getNumReplicas()

getNumReplicas() : integer

Get the number of replicas configured for the bucket.

Note that even if the bucket is configured to use this number of replicas doesn't necessarily mean that this number of replicas exist. It is possible to set the number of replicas higher than the number of nodes.

Throws

\CouchbaseException

if an error occurs

Returns

integer —

The number of replicas for the bucket

getServers()

getServers() : array

Get the name of the servers in the cluster.

Throws

\CouchbaseException

if an error occurs

Returns

array —

an array containing all of the servers in the cluster

observe()

observe(string $id, string $cas, array $details) : bool

Get information about a key in the cluster.

Parameters

string $id

The identifier to get information about

string $cas

The cas for the document to get information about

array $details

an array to store the details about the key

Throws

\CouchbaseException

if an error occurs

Returns

bool —

true on success, false otherwise

observeMulti()

observeMulti(array $ids, array $details) : array

Get information about multiple keys in the cluster.

Parameters

array $ids

an array containing the identifiers to look up

array $details

an array to store the details about the documents

Throws

\CouchbaseException

if an error occurs

Returns

array —

with the keys with true on success, false otherwise

keyDurability()

keyDurability(string $id, string $cas, array $details) : bool

Wait for a document to reach a certain state.

NameDescription
persist_toThe number of nodes the document should be persisted to
replicate_toThe number of nodes the document should be replicated to
timeoutThe max time to wait for durability
intervalThe interval between checking the state of the document

Parameters

string $id

the identifier for the document to wait for

string $cas

the cas identifier for the document to wait for

array $details

an array containing the details. see above

Throws

\CouchbaseException

if an error occurs

Returns

bool —

true on success, false otherwise

keyDurabilityMulti()

keyDurabilityMulti(array $ids, array $details) : array

Wait for multiple documents to reach a certain state.

Parameters

array $ids

an array containing "identifier" => "cas" pairs

array $details

is an array containing the options to wait for. See keyDurability() for a description.

Throws

\CouchbaseException

if an error occurs

Returns

array —

with the keys with true on success, false otherwise

getTimeout()

getTimeout() : integer

Retrieve the current operation timeout.

Returns

integer —

The currently used timeout specified in usec

setTimeout()

setTimeout(integer $timeout)

Specify an operation timeout.

The operation timeout is the time it takes from the command is sent to the cluster and the result should be returned back.

Parameters

integer $timeout

the new operation timeout specified in usec

getDesignDoc()

getDesignDoc(string $name) : string

Get a design document from the cluster.

Parameters

string $name

The design document to retrieve

Throws

\CouchbaseException

if an error occurs

Returns

string —

the content of the document if success

setDesignDoc()

setDesignDoc(string $name, string $document) : bool

Store a design document in the cluster.

Please note that this method will overwrite any existing design document with the same name.

Parameters

string $name

the name of the design document to store

string $document

the new document to create

Throws

\CouchbaseException

if an error occurs

Returns

bool —

true on success

deleteDesignDoc()

deleteDesignDoc(string $name) : bool

Delete the named design document from the cluster.

Parameters

string $name

the name of the design document to delete

Throws

\CouchbaseException

if an error occurs

Returns

bool —

true on success

listDesignDocs()

listDesignDocs() : string

List all design documents for this bucket

Throws

\CouchbaseException

if an error occurs

Returns

string —

A JSON encoded string containing all information about the design documents