README

Azure Cosmos DB 的 PHP 封装

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

安装

通过将 jupitern/cosmosdb 添加到您的 composer.json 文件中，将其包含到您的项目中。

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

变更日志

v2.7.0

• 添加对 PATCH 动词的支持（CosmosDb 扩展 PATCH API），包括添加、设置、替换、删除、递增和移动操作，以及 "getPatchOp[OP]" 辅助函数

v2.6.0

• 代码重构。支持的最低 PHP 版本现在为 8.0
• selectCollection 不再创建不存在的集合。请使用 createCollection 进行此操作
• 错误修复

v2.5.0

• 支持使用新方法 "setPartitionValue()" 进行分区查询
• 支持创建分区集合
• 支持嵌套分区键

v2.0.0

• 支持跨分区查询
• 从所有方法中删除了 selectCollection 方法，以改善性能

v1.4.4

• 用 guzzle 替换了 pear 包 http_request2
• 添加了提供 guzzle 配置的方法

v1.3.0

• 添加了对参数化查询的支持

注意

此包为 AzureDocumentDB-PHP 包添加了额外的功能。所有其他功能也包含在此包中。

限制

• 目前不支持在跨分区查询中使用 limit() 或 order()。
• 目前不支持基于事务请求的多文档修补。

用法

连接

$conn = new \Jupitern\CosmosDb\CosmosDb('https://: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();
}

贡献

• 欢迎讨论错误、功能和想法。

许可

jupitern/cosmosdb 在 MIT 许可下发布。

您可以自由使用、修改和分发此软件，只要保留版权头信息即可