\CouchbaseMutateInBuilder

A builder for subdocument mutations. In order to perform the final set of operations, use the execute() method.

Instances of this builder should be obtained through \Couchbase\Bucket->mutateIn()

Summary

Methods
Properties
Constants
insert()
modeDocument()
upsert()
replace()
remove()
arrayPrepend()
arrayPrependAll()
arrayAppend()
arrayAppendAll()
arrayInsert()
arrayInsertAll()
arrayAddUnique()
counter()
withExpiry()
execute()
No public properties found
FULLDOC_REPLACE
FULLDOC_UPSERT
FULLDOC_INSERT
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Constants

FULLDOC_REPLACE

FULLDOC_REPLACE

FULLDOC_UPSERT

FULLDOC_UPSERT

FULLDOC_INSERT

FULLDOC_INSERT

Methods

insert()

insert(string  $path, mixed  $value, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Insert a fragment provided the last element of the path doesn't exists.

Parameters

string $path

the path where to insert a new dictionary value.

mixed $value

the new dictionary value to insert.

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

modeDocument()

modeDocument(integer  $mode) 

Select mode for new full-document operations.

It defines behaviour of MutateInBuilder#upsert() method. The $mode could take one of three modes:

  • FULLDOC_REPLACE: complain when document does not exist
  • FULLDOC_INSERT: complain when document does exist
  • FULLDOC_UPSERT: unconditionally set value for the document

Parameters

integer $mode

operation mode

upsert()

upsert(string  $path, mixed  $value, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Insert a fragment, replacing the old value if the path exists.

When only one argument supplied, the library will handle it as full-document upsert, and treat this argument as value. See MutateInBuilder#modeDocument()

Parameters

string $path

the path where to insert (or replace) a dictionary value

mixed $value

the new dictionary value to be applied.

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

replace()

replace(string  $path, mixed  $value, array  $options = array()) : \Couchbase\MutateInBuilder

Replace an existing value by the given fragment

Parameters

string $path

the path where the value to replace is

mixed $value

the new value

array $options

the array with command modificators. Supported values are:

  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

remove()

remove(string  $path, array  $options = array()) : \Couchbase\MutateInBuilder

Remove an entry in a JSON document.

Scalar, array element, dictionary entry, whole array or dictionary, depending on the path.

Parameters

string $path

the path to remove

array $options

the array with command modificators. Supported values are:

  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayPrepend()

arrayPrepend(string  $path, mixed  $value, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Prepend to an existing array, pushing the value to the front/first position in the array.

Parameters

string $path

the path of the array

mixed $value

the value to insert at the front of the array

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayPrependAll()

arrayPrependAll(string  $path, array  $values, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Prepend multiple values at once in an existing array.

Push all values in the collection's iteration order to the front/start of the array. For example given an array [A, B, C], prepending the values X and Y yields [X, Y, A, B, C] and not [[X, Y], A, B, C].

Parameters

string $path

the path of the array

array $values

the values to insert at the front of the array as individual elements

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayAppend()

arrayAppend(string  $path, mixed  $value, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Append to an existing array, pushing the value to the back/last position in the array.

Parameters

string $path

the path of the array

mixed $value

the value to insert at the back of the array

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayAppendAll()

arrayAppendAll(string  $path, array  $values, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Append multiple values at once in an existing array.

Push all values in the collection's iteration order to the back/end of the array. For example given an array [A, B, C], appending the values X and Y yields [A, B, C, X, Y] and not [A, B, C, [X, Y]].

Parameters

string $path

the path of the array

array $values

the values to individually insert at the back of the array

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayInsert()

arrayInsert(string  $path, mixed  $value, array  $options = array()) : \Couchbase\MutateInBuilder

Insert into an existing array at a specific position

Position denoted in the path, eg. "sub.array[2]".

Parameters

string $path

the path (including array position) where to insert the value

mixed $value

the value to insert in the array

array $options

the array with command modificators. Supported values are:

  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayInsertAll()

arrayInsertAll(string  $path, array  $values, array  $options = array()) : \Couchbase\MutateInBuilder

Insert multiple values at once in an existing array at a specified position.

Position denoted in the path, eg. "sub.array[2]"), inserting all values in the collection's iteration order at the given position and shifting existing values beyond the position by the number of elements in the collection.

For example given an array [A, B, C], inserting the values X and Y at position 1 yields [A, B, X, Y, C] and not [A, B, [X, Y], C].

Parameters

string $path

the path of the array

array $values

the values to insert at the specified position of the array, each value becoming an entry at or after the insert position.

array $options

the array with command modificators. Supported values are:

  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

arrayAddUnique()

arrayAddUnique(string  $path, mixed  $value, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Insert a value in an existing array only if the value isn't already contained in the array (by way of string comparison).

Parameters

string $path

the path to mutate in the JSON

mixed $value

the value to insert

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

counter()

counter(string  $path, integer  $delta, array|boolean  $options = array()) : \Couchbase\MutateInBuilder

Increment/decrement a numerical fragment in a JSON document.

If the value (last element of the path) doesn't exist the counter is created and takes the value of the delta.

Parameters

string $path

the path to the counter (must be containing a number).

integer $delta

the value to increment or decrement the counter by

array|boolean $options

the array with command modificators. The boolean value, controls "createPath" option. Supported values are:

  • "createPath" (default: false) true to create missing intermediary nodes.
  • "xattr" (default: false) if true, the path refers to a location within the document's extended attributes, not the document body.

Returns

\Couchbase\MutateInBuilder

withExpiry()

withExpiry(  $expiry) : \Couchbase\MutateInBuilder

Change the expiry of the enclosing document as part of the mutation.

Parameters

$expiry

Returns

\Couchbase\MutateInBuilder

execute()

execute() : \Couchbase\DocumentFragment

Perform several mutation operations inside a single existing JSON document.

Returns

\Couchbase\DocumentFragment

Examples

<?php
$cluster = new \Couchbase\Cluster("couchbase://localhost");
$cluster = new \Couchbase\Cluster("couchbase://192.168.1.194");
$bucket = $cluster->openBucket('default');

$bucket->upsert('bar', [
    'field1' => 'value1',
    'field2' => 'value2',
    'array' =>  [1, 2, 3],
]);

$result = $bucket->mutateIn('bar')
        ->replace('field1', ['foo' => 'bar'])
        ->remove('array')
        ->replace('missing', "hello world")
        ->execute();

var_dump($result->error->getCode()); //=> int(73)   COUCHBASE_SUBDOC_MULTI_FAILURE
var_dump(count($result->value));     //=> int(1)
var_dump($result->value[2]['code']); //=> int(63)   COUCHBASE_SUBDOC_PATH_ENOENT

// the document is not modified
var_dump($bucket->get('bar')->value);
//=> object(stdClass)#6 (3) {
//     ["field1"]=>
//     string(6) "value1"
//     ["field2"]=>
//     string(6) "value2"
//     ["array"]=>
//     array(3) {
//       [0]=>
//       int(1)
//       [1]=>
//       int(2)
//       [2]=>
//       int(3)
//     }
//   }

$result = $bucket->mutateIn('bar')
        ->replace('field1', ['foo' => 'bar'])
        ->remove('array')
        ->execute();
var_dump($bucket->get('bar')->value);
//=> object(stdClass)#6 (2) {
//     ["field1"]=>
//     object(stdClass)#5 (1) {
//       ["foo"]=>
//       string(3) "bar"
//     }
//     ["field2"]=>
//     string(6) "value2"
//   }