PHP wrapper for Azure Cosmos DB
https://docs.microsoft.com/pt-pt/rest/api/cosmos-db/common-tasks-using-the-cosmosdb-rest-api
Include jupitern/cosmosdb in your project, by adding it to your composer.json file.
{
"require": {
"jupitern/cosmosdb": "2.*"
}
}- adding support for PATCH verb (CosmosDb add-on PATCH API) with Add, Set, Replace, Remove, Increment and Move operations, including "getPatchOp[OP]" helper functions
- 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
- support partitioned queries using new method "setPartitionValue()"
- support creating partitioned collections
- support for nested partition keys
- support for cross partition queries
- selectCollection method removed from all methods for performance improvements
- replaced pear package http_request2 by guzzle
- added method to provide guzzle configuration
- added support for parameterized queries
This package adds additional functionalities to the AzureDocumentDB-PHP package. All other functionality exists in this package as well.
- Use of
limit()ororder()in cross-partition queries is currently not supported. - Multi-document patch using transaction based requests is currently not supported.
$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');$rid = \Jupitern\CosmosDb\QueryBuilder::instance()
->setCollection($collection)
->setPartitionKey('country')
->save([
'id' => '2',
'name' => 'Jane doe',
'age' => 35,
'country' => 'Portugal'
]);$rid = \Jupitern\CosmosDb\QueryBuilder::instance()
->setCollection($collection)
->setPartitionKey('country')
->save([
"_rid" => $rid,
'id' => '2',
'name' => 'Jane Doe Something',
'age' => 36,
'country' => 'Portugal'
]);# 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'
# ]# 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();# 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);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();
}- welcome to discuss a bugs, features and ideas.
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