README

PHP wrapper for Azure Cosmos DB

https://docs.microsoft.com/pt-pt/rest/api/cosmos-db/common-tasks-using-the-cosmosdb-rest-api

Installation

Include jupitern/cosmosdb in your project, by adding it to your composer.json file.

{
    "require": {
        "jupitern/cosmosdb": "2.*"
    }
}

Changelog

v2.7.0

adding support for PATCH verb (CosmosDb add-on PATCH API) with Add, Set, Replace, Remove, Increment and Move operations, including "getPatchOp[OP]" helper functions

v2.6.0

code refactor. min PHP verion supported is now 8.0
selectCollection no longer creates a colletion if not exist. use createCollection for that
bug fixes

v2.5.0

support partitioned queries using new method "setPartitionValue()"
support creating partitioned collections
support for nested partition keys

v2.0.0

support for cross partition queries
selectCollection method removed from all methods for performance improvements

v1.4.4

replaced pear package http_request2 by guzzle
added method to provide guzzle configuration

v1.3.0

added support for parameterized queries

Note

This package adds additional functionalities to the AzureDocumentDB-PHP package. All other functionality exists in this package as well.

Limitations

Use of limit() or order() in cross-partition queries is currently not supported.
Multi-document patch using transaction based requests is currently not supported.

Usage

Connecting

$conn = new \Jupitern\CosmosDb\CosmosDb('https://localhost:8081', 'primaryKey');
$conn->setHttpClientOptions(['verify' => false]); # optional: set guzzle client options.
$db = $conn->selectDB('testdb');

# create a new collection
$collection = $db->createCollection('Users', 'country');

# select existing collection
$collection = $db->selectCollection('Users');

Inserting Records

$rid = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->save([
        'id' => '2', 
        'name' => 'Jane doe', 
        'age' => 35, 
        'country' => 'Portugal'
    ]);

Updating Records

$rid = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->save([
        "_rid" => $rid, 
        'id' => '2', 
        'name' => 'Jane Doe Something', 
        'age' => 36, 
        'country' => 'Portugal'
    ]);

Patching Records

# Patch operations: ADD | SET | REPLACE | REMOVE | INCR | MOVE
# https://learn.microsoft.com/en-us/azure/cosmos-db/partial-document-update#similarities-and-differences

# Where a PartitionKey is in use, the PartitionValue should be set on the QueryBuilder instance
# prior to making any PATCH operations, as by the nature of PATCH, there is no document body to find the value in, 
# and the value is taken from the class property when the request is made. $rid_doc is also required because PATCH is an item-level operation.

# Example starting document (as array)

# [
# 	"_rid" => $rid, 
# 	'id' => '2', 
# 	'name' => 'Jane Doe Something', 
# 	'age' => 36, 
# 	'country' => 'Portugal'
# ]

$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->setPartitionValue('Portugal');

# Patch operations can be batched, so the $operations argument is an array of arrays
# Batch patch operations are limited to 10 operations per request
$operations[] = $res->getPatchOpSet('/age', 38);
$operations[] = $res->getPatchOpAdd('/region' 'Algarve');

$rid_doc = $res->patch($rid_doc, $operations);

# Example patched document (as array)

# [
# 	"_rid" => $rid, 
# 	'id' => '2', 
# 	'name' => 'Jane Doe Something', 
# 	'age' => 38, 
# 	'country' => 'Portugal'
#	'region' => 'Algarve'
# ]

Querying Records

# cross partition query to get a single document and return it as an array
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("c.id, c.name")
    ->where("c.age > @age and c.country = @country")
    ->params(['@age' => 10, '@country' => 'Portugal'])
    ->find(true) # pass true if is cross partition query
    ->toArray();

# query a document using a known partition value
# and return as an array. note: setting a known
# partition value will result in a more efficient
# query against your database as it will not rely
# on cross-partition querying
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionValue('Portugal')
    ->select("c.id, c.name")
    ->where("c.age > @age")
    ->params(['@age' => 10])
    ->find()
    ->toArray();

# query to get the top 5 documents as an array, with the
# document ID as the array key.
# note: refer to limitations section
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("c.id, c.name")
    ->where("c.age > @age and c.country = @country")
    ->params(['@age' => 10, '@country' => 'Portugal'])
    ->limit(5)
    ->findAll()
    ->toArray('id');

# query a document using a collection alias and cross partition query
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("TestColl.id, TestColl.name")
    ->from("TestColl")
    ->where("TestColl.age > @age")
    ->params(['@age' => 10])
    ->findAll(true) # pass true if is cross partition query
    ->toArray();

Deleting Records

# delete one document that matches criteria (single partition)
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->where("c.age > 20 and c.country = 'Portugal'")
    ->delete();

# delete all documents that match criteria (cross partition)
$res = \Jupitern\CosmosDb\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->where("c.age > 20")
    ->deleteAll(true);

Error handling

try {
    $res = QueryBuilder::instance()
        ->setCollection($collection)
        ->deleteAll(true);
        
} catch (\GuzzleHttp\Exception\ClientException $e) {
    $response = json_decode($e->getResponse()->getBody());
    echo "ERROR: ".$response->code ." => ". $response->message .PHP_EOL.PHP_EOL;

    echo $e->getTraceAsString();
}

Contributing

welcome to discuss a bugs, features and ideas.

License

jupitern/cosmosdb is release under the MIT license.

You are free to use, modify and distribute this software, as long as the copyright header is left intact

jupitern / cosmosdb

Maintainers

Details