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()
insert(string $path, mixed $value, array|boolean $options = array()) : \Couchbase\MutateInBuilder
Insert a fragment provided the last element of the path doesn't exists.
| 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:
|
upsert(string $path, mixed $value, array|boolean $options = array()) : \Couchbase\MutateInBuilder
Insert a fragment, replacing the old value if the path exists
| 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:
|
replace(string $path, mixed $value, array $options = array()) : \Couchbase\MutateInBuilder
Replace an existing value by the given fragment
| 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:
|
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.
| string | $path | the path to remove |
| array | $options | the array with command modificators. Supported values are:
|
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.
| 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:
|
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].
| 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:
|
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.
| 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:
|
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]].
| 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:
|
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]".
| 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:
|
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].
| 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:
|
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).
| 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:
|
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.
| 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:
|
execute() : \Couchbase\DocumentFragment
Perform several mutation operations inside a single existing JSON document.
<?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"
// }