Constants

PINGSVC_KV

PINGSVC_KV

Ping data (Key/Value) service.

PINGSVC_N1QL

PINGSVC_N1QL

Ping query (N1QL) service.

PINGSVC_VIEWS

PINGSVC_VIEWS

Ping views (Map/Reduce) service.

PINGSVC_FTS

PINGSVC_FTS

Ping full text search (FTS) service.

Properties

$operationTimeout

$operationTimeout : integer

The operation timeout (in microseconds) is the maximum amount of time the library will wait for an operation to receive a response before invoking its callback with a failure status.

An operation may timeout if:

  • A server is taking too long to respond
  • An updated cluster configuration has not been promptly received

Type

integer

$viewTimeout

$viewTimeout : integer

The I/O timeout (in microseconds) for HTTP requests to Couchbase Views API

Type

integer

$n1qlTimeout

$n1qlTimeout : integer

The I/O timeout (in microseconds) for N1QL queries.

Type

integer

$httpTimeout

$httpTimeout : integer

The I/O timeout (in microseconds) for HTTP queries (management API).

Type

integer

$configTimeout

$configTimeout : integer

How long (in microseconds) the client will wait to obtain the initial configuration.

Type

integer

$configNodeTimeout

$configNodeTimeout : integer

Per-node configuration timeout (in microseconds).

This timeout sets the amount of time to wait for each node within the bootstrap/configuration process. This interval is a subset of the $configTimeout option mentioned above and is intended to ensure that the bootstrap process does not wait too long for a given node. Nodes that are physically offline may never respond and it may take a long time until they are detected as being offline.

Type

integer

$configDelay

$configDelay : integer

Config refresh throttling

Modify the amount of time (in microseconds) before the configiration error threshold will forcefully be set to its maximum number forcing a configuration refresh.

Note that if you expect a high number of timeouts in your operations, you should set this to a high number. If you are using the default timeout setting, then this value is likely optimal.

Type

integer

$htconfigIdleTimeout

$htconfigIdleTimeout : integer

Idling/Persistence for HTTP bootstrap (in microseconds)

By default the behavior of the library for HTTP bootstrap is to keep the stream open at all times (opening a new stream on a different host if the existing one is broken) in order to proactively receive configuration updates.

The default value for this setting is -1. Changing this to another number invokes the following semantics:

  • The configuration stream is not kept alive indefinitely. It is kept open for the number of seconds specified in this setting. The socket is closed after a period of inactivity (indicated by this setting).

  • If the stream is broken (and no current refresh was requested by the client) then a new stream is not opened.

Type

integer

$durabilityInterval

$durabilityInterval : integer

The time (in microseconds) the client will wait between repeated probes to a given server.

Type

integer

$durabilityTimeout

$durabilityTimeout : integer

The time (in microseconds) the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements

Type

integer

Methods

getName()

getName() : string

Returns the name of the bucket for current connection

Returns

string

manager()

manager() : \Couchbase\BucketManager

Returns an instance of a CouchbaseBucketManager for performing management operations against a bucket.

Returns

\Couchbase\BucketManager

setTranscoder()

setTranscoder(callable  $encoder, callable  $decoder) 

Sets custom encoder and decoder functions for handling serialization.

Parameters

callable $encoder
callable $decoder

Examples

<?php
$cluster = new \Couchbase\Cluster("couchbase://localhost");
$bucket = $cluster->openBucket("default");
$bucket->setTranscoder("\\Couchbase\\defaultEncoder", "\\Couchbase\\passthruDecoder");
$bucket->upsert("foo", ["bar" => "baz"]);
$value = $bucket->get("foo")->value;
var_dump($value);
// => string(13) "{"bar":"baz"}"

get()

get(string|array  $ids, array  $options = array()) : \Couchbase\Document|array

Retrieves a document

Parameters

string|array $ids

one or more IDs

array $options

options

  • "lockTime" non zero if the documents have to be locked
  • "expiry" non zero if the expiration time should be updated
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

getAndLock()

getAndLock(string|array  $ids, integer  $lockTime, array  $options = array()) : \Couchbase\Document|array

Retrieves a document and locks it.

After the document has been locked on the server, its CAS would be masked, and all mutations of it will be rejected until the server unlocks the document automatically or it will be done manually with \Couchbase\Bucket::unlock() operation.

Parameters

string|array $ids

one or more IDs

integer $lockTime

time to lock the documents

array $options

options

  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

getAndTouch()

getAndTouch(string|array  $ids, integer  $expiry, array  $options = array()) : \Couchbase\Document|array

Retrieves a document and updates its expiration time.

Parameters

string|array $ids

one or more IDs

integer $expiry

time after which the document will not be accessible. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).

array $options

options

  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

getFromReplica()

getFromReplica(string|array  $ids, array  $options = array()) : \Couchbase\Document|array

Retrieves a document from a replica.

Parameters

string|array $ids

one or more IDs

array $options

options

  • "index" the replica index. If the index is zero, it will return first successful replica, otherwise it will read only selected node.
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

upsert()

upsert(string|array  $ids, mixed  $value, array  $options = array()) : \Couchbase\Document|array

Inserts or updates a document, depending on whether the document already exists on the cluster.

Parameters

string|array $ids

one or more IDs

mixed $value

value of the document

array $options

options

  • "expiry" document expiration time in seconds. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "persist_to" how many nodes the key should be persisted to (including master). If set to 0 then persistence will not be checked. If set to a negative number, will be set to the maximum number of nodes to which persistence is possible (which will always contain at least the master node).
  • "replicate_to" how many nodes the key should be persisted to (excluding master). If set to 0 then replication will not be checked. If set to a negative number, will be set to the maximum number of nodes to which replication is possible (which may be 0 if the bucket is not configured for replicas).
  • "flags" override flags (not recommended to use)
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

insert()

insert(string|array  $ids, mixed  $value, array  $options = array()) : \Couchbase\Document|array

Inserts a document. This operation will fail if the document already exists on the cluster.

Parameters

string|array $ids

one or more IDs

mixed $value

value of the document

array $options

options

  • "expiry" document expiration time in seconds. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "persist_to" how many nodes the key should be persisted to (including master). If set to 0 then persistence will not be checked. If set to a negative number, will be set to the maximum number of nodes to which persistence is possible (which will always contain at least the master node).
  • "replicate_to" how many nodes the key should be persisted to (excluding master). If set to 0 then replication will not be checked. If set to a negative number, will be set to the maximum number of nodes to which replication is possible (which may be 0 if the bucket is not configured for replicas).
  • "flags" override flags (not recommended to use)
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

replace()

replace(string|array  $ids, mixed  $value, array  $options = array()) : \Couchbase\Document|array

Replaces a document. This operation will fail if the document does not exists on the cluster.

Parameters

string|array $ids

one or more IDs

mixed $value

value of the document

array $options

options

  • "cas" last known document CAS, which serves for optimistic locking.
  • "expiry" document expiration time in seconds. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "persist_to" how many nodes the key should be persisted to (including master). If set to 0 then persistence will not be checked. If set to a negative number, will be set to the maximum number of nodes to which persistence is possible (which will always contain at least the master node).
  • "replicate_to" how many nodes the key should be persisted to (excluding master). If set to 0 then replication will not be checked. If set to a negative number, will be set to the maximum number of nodes to which replication is possible (which may be 0 if the bucket is not configured for replicas).
  • "flags" override flags (not recommended to use)
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

append()

append(string|array  $ids, mixed  $value, array  $options = array()) : \Couchbase\Document|array

Appends content to a document.

On the server side it just contatenate passed value to the existing one. Note that this might make the value un-decodable. Consider sub-document API for partial updates of the JSON documents.

Parameters

string|array $ids

one or more IDs

mixed $value

value of the document

array $options

options

  • "cas" last known document CAS, which serves for optimistic locking.
  • "expiry" document expiration time in seconds. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "persist_to" how many nodes the key should be persisted to (including master). If set to 0 then persistence will not be checked. If set to a negative number, will be set to the maximum number of nodes to which persistence is possible (which will always contain at least the master node).
  • "replicate_to" how many nodes the key should be persisted to (excluding master). If set to 0 then replication will not be checked. If set to a negative number, will be set to the maximum number of nodes to which replication is possible (which may be 0 if the bucket is not configured for replicas).
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

prepend()

prepend(string|array  $ids, mixed  $value, array  $options = array()) : \Couchbase\Document|array

Prepends content to a document.

On the server side it just contatenate existing value to the passed one. Note that this might make the value un-decodable. Consider sub-document API for partial updates of the JSON documents.

Parameters

string|array $ids

one or more IDs

mixed $value

value of the document

array $options

options

  • "cas" last known document CAS, which serves for optimistic locking.
  • "expiry" document expiration time in seconds. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "persist_to" how many nodes the key should be persisted to (including master). If set to 0 then persistence will not be checked. If set to a negative number, will be set to the maximum number of nodes to which persistence is possible (which will always contain at least the master node).
  • "replicate_to" how many nodes the key should be persisted to (excluding master). If set to 0 then replication will not be checked. If set to a negative number, will be set to the maximum number of nodes to which replication is possible (which may be 0 if the bucket is not configured for replicas).
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

remove()

remove(string|array  $ids, array  $options = array()) : \Couchbase\Document|array

Removes the document.

Parameters

string|array $ids

one or more IDs

array $options

options

  • "cas" last known document CAS, which serves for optimistic locking.
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

unlock()

unlock(string|array  $ids, array  $options = array()) : \Couchbase\Document|array

Unlocks previously locked document

Parameters

string|array $ids

one or more IDs

array $options

options

  • "cas" last known document CAS, which has been returned by locking command.
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

touch()

touch(string|array  $ids, integer  $expiry, array  $options = array()) : \Couchbase\Document|array

Updates document's expiration time.

Parameters

string|array $ids

one or more IDs

integer $expiry

time after which the document will not be accessible. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).

array $options

options

  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

counter()

counter(string|array  $ids, integer  $delta = 1, array  $options = array()) : \Couchbase\Document|array

Increments or decrements a key (based on $delta)

Parameters

string|array $ids

one or more IDs

integer $delta

the number whih determines the sign (positive/negative) and the value of the increment

array $options

options

  • "initial" initial value of the counter if it does not exist
  • "expiry" time after which the document will not be accessible. If larger than 30 days (606024*30), it will be interpreted by the server as absolute UNIX time (seconds from epoch 1970-01-01T00:00:00).
  • "groupid" override value for hashing (not recommended to use)

Returns

\Couchbase\Document|array —

document or list of the documents

lookupIn()

lookupIn(string  $id) : \Couchbase\LookupInBuilder

Returns a builder for reading subdocument API.

Parameters

string $id

The ID of the JSON document

Returns

\Couchbase\LookupInBuilder

retrieveIn()

retrieveIn(string  $id, string  $paths) : \Couchbase\DocumentFragment

Retrieves specified paths in JSON document

This is essentially a shortcut for lookupIn($id)->get($paths)->execute().

Parameters

string $id

The ID of the JSON document

string $paths

List of the paths inside JSON documents (see "Path syntax" section of the "Sub-Document Operations" documentation).

Returns

\Couchbase\DocumentFragment

mutateIn()

mutateIn(string  $id, string  $cas) : \Couchbase\MutateInBuilder

Returns a builder for writing subdocument API.

Parameters

string $id

The ID of the JSON document

string $cas

Last known document CAS value for optimisti locking

Returns

\Couchbase\MutateInBuilder

query()

query(\Couchbase\N1qlQuery|\Couchbase\ViewQuery|\Couchbase\SpatialViewQuery|\Couchbase\SearchQuery|\Couchbase\AnalyticsQuery  $query, boolean  $jsonAsArray = false) : object

Performs a query to Couchbase Server

Parameters

\Couchbase\N1qlQuery|\Couchbase\ViewQuery|\Couchbase\SpatialViewQuery|\Couchbase\SearchQuery|\Couchbase\AnalyticsQuery $query
boolean $jsonAsArray

if true, the values in the result rows (or hits) will be represented as PHP arrays, otherwise they will be instances of the stdClass

Returns

object —

Query-specific result object.

mapSize()

mapSize(string  $id) : integer

Returns size of the map

Parameters

string $id

ID of the document

Returns

integer —

number of the key-value pairs

mapAdd()

mapAdd(string  $id, string  $key, mixed  $value) 

Add key to the map

Parameters

string $id

ID of the document

string $key

key

mixed $value

value

mapRemove()

mapRemove(string  $id, string  $key) 

Removes key from the map

Parameters

string $id

ID of the document

string $key

key

mapGet()

mapGet(string  $id, string  $key) : mixed

Get an item from a map

Parameters

string $id

ID of the document

string $key

key

Returns

mixed —

value associated with the key

setSize()

setSize(string  $id) : integer

Returns size of the set

Parameters

string $id

ID of the document

Returns

integer —

number of the elements

setAdd()

setAdd(string  $id, string|integer|float|boolean  $value) 

Add value to the set

Note, that currently only primitive values could be stored in the set (strings, integers and booleans).

Parameters

string $id

ID of the document

string|integer|float|boolean $value

new value

setExists()

setExists(string  $id, string|integer|float|boolean  $value) : boolean

Check if the value exists in the set

Parameters

string $id

ID of the document

string|integer|float|boolean $value

value to check

Returns

boolean —

true if the value exists in the set

setRemove()

setRemove(string  $id, string|integer|float|boolean  $value) 

Remove value from the set

Parameters

string $id

ID of the document

string|integer|float|boolean $value

value to remove

listSize()

listSize(string  $id) : integer

Returns size of the list

Parameters

string $id

ID of the document

Returns

integer —

number of the elements

listPush()

listPush(string  $id, mixed  $value) 

Add an element to the end of the list

Parameters

string $id

ID of the document

mixed $value

new value

listShift()

listShift(string  $id, mixed  $value) 

Add an element to the beginning of the list

Parameters

string $id

ID of the document

mixed $value

new value

listRemove()

listRemove(string  $id, integer  $index) 

Remove an element at the given position

Parameters

string $id

ID of the document

integer $index

index of the element to be removed

listGet()

listGet(string  $id, integer  $index) : mixed

Get an element at the given position

Parameters

string $id

ID of the document

integer $index

index of the element

Returns

mixed —

the value

listSet()

listSet(string  $id, integer  $index, mixed  $value) 

Set an element at the given position

Parameters

string $id

ID of the document

integer $index

index of the element

mixed $value

new value

listExists()

listExists(string  $id, mixed  $value) 

Check if the list contains specified value

Parameters

string $id

ID of the document

mixed $value

value to look for

queueSize()

queueSize(string  $id) : integer

Returns size of the queue

Parameters

string $id

ID of the document

Returns

integer —

number of the elements in the queue

queueExists()

queueExists(string  $id, mixed  $value) : boolean

Checks if the queue contains specified value

Parameters

string $id

ID of the document

mixed $value

value to look for

Returns

boolean —

true if the queue contains the value

queueAdd()

queueAdd(string  $id, mixed  $value) 

Add an element to the beginning of the queue

Parameters

string $id

ID of the document

mixed $value

new value

queueRemove()

queueRemove(string  $id) : mixed

Remove the element at the end of the queue and return it

Parameters

string $id

ID of the document

Returns

mixed —

removed value

ping()

ping(integer  $services, string  $reportId = NULL) : array

Try to reach specified services, and measure network latency.

Parameters

integer $services

bitwise mask of required services (and all services when zero)

string $reportId

custom identifier, which will be appended to "id" property in report

Returns

array —

the report object

diag()

diag(string  $reportId = NULL) : array

Collect and return information about state of internal network connections.

Parameters

string $reportId

custom identifier, which will be appended to "id" property in report

Returns

array —

the report object

encryptFields()

encryptFields(array  $document,   $fieldOptions, string  $prefix = null) : array

Encrypt fields inside specified document.

Parameters

array $document

document structure

$fieldOptions
string $prefix

optional prefix for modified field (when null, the library will use "__crypt")

Returns

array —

where the fields encrypted

decryptFields()

decryptFields(array  $document,   $fieldOptions, string  $prefix = null) : array

Decrypt fields inside specified document.

Parameters

array $document

document structure

$fieldOptions
string $prefix

optional prefix for modified field (when null, the library will use "__crypt")

Returns

array —

where the fields decrypted