\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()
upsert()
replace()
remove()
arrayPrepend()
arrayPrependAll()
arrayAppend()
arrayAppendAll()
arrayInsert()
arrayInsertAll()
arrayAddUnique()
counter()
execute()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Methods

insert()

insert(string  $path, mixed  $value, boolean  $createParents = false) : \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.

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

upsert()

upsert(string  $path, mixed  $value, boolean  $createParents = false) : \Couchbase\MutateInBuilder

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

Parameters

string $path

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

mixed $value

the new dictionary value to be applied.

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

replace()

replace(string  $path, mixed  $value) : \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

Returns

\Couchbase\MutateInBuilder

remove()

remove(string  $path) : \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

Returns

\Couchbase\MutateInBuilder

arrayPrepend()

arrayPrepend(string  $path, mixed  $value, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

arrayPrependAll()

arrayPrependAll(string  $path, array  $values, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

arrayAppend()

arrayAppend(string  $path, mixed  $value, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

arrayAppendAll()

arrayAppendAll(string  $path, array  $values, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

arrayInsert()

arrayInsert(string  $path, mixed  $value) : \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

Returns

\Couchbase\MutateInBuilder

arrayInsertAll()

arrayInsertAll(string  $path, array  $values) : \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.

Returns

\Couchbase\MutateInBuilder

arrayAddUnique()

arrayAddUnique(string  $path, mixed  $value, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

Returns

\Couchbase\MutateInBuilder

counter()

counter(string  $path, integer  $delta, boolean  $createParents = false) : \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

boolean $createParents

true to create missing intermediary nodes

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"
//   }