phuze/php-cosmos

PHP wrapper for Azure Cosmos DB using SQL rest api

3.0.4 2024-02-06 15:53 UTC

Requires

• php: >=7.0
• ext-curl: *
• guzzlehttp/guzzle: >=6.0

MIT

• nosql
• sql
• rest
• api
• azure
• cosmosdb

README

PHP wrapper for Azure Cosmos DB

Installation

Install phuze/php-cosmos in your project:

composer require phuze/php-cosmos

Changelog

v3.0.4

• bug fixes and other minor changes

v3.0.0

• restore support for PHP 7.x -- this library can be used with both 7.x and 8.x
• improved how nested partition keys are handled
• improved how partition values are matched
• fixed an issue which prevented document deletion when a container used a nested partition key
• fixed an issue with partitionkeyrangeid headers, when a cross-partition query needs to be retried with PK ranges

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

Notes

• Currently uses Microsoft API version 2018-12-31
• Based on AzureDocumentDB-PHP and CosmosDb.
• Planned updates include:
  • support for new PATCH api operations
  • enhanced debug and logging support

Usage

Connecting

$conn = new \Phuze\PhpCosmos\CosmosDb('host', 'key');
$conn->setHttpClientOptions(['verify' => false]); # optional: set guzzle client options.
$db = $conn->selectDB('databaseName');
$collection = $db->selectCollection('collectionName');

# if a collection does not exist, it will be created when you
# attempt to select the collection. however, if you have created
# your database with shared throughput, then all collections require a partition key.
# selectCollection() supports a second parameter for this purpose.
$conn = new \Phuze\PhpCosmos\CosmosDb('host', 'key');
$conn->setHttpClientOptions(['verify' => false]); # optional: set guzzle client options.
$db = $conn->selectDB('dbName');
$collection = $db->selectCollection('collectionName', 'myPartitionKey');

Inserting Records

# consider a existing collection called "Users" with a partition key "country"

# insert a record
$rid = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->save(['id' => '1', 'name' => 'John Doe', 'age' => 22, 'country' => 'Portugal']);

# insert a record against a collection with a nested partition key
$rid = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('billing.country')
    ->save([
        'id' => '2',
        'name' => 'Jane Doe',
        'age' => 35,
        'billing' => ['country' => 'Portugal']
    ]);

Updating Records

# update a record
$rid = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->save([
        '_rid'    => $rid, // existing document _rid
        'id'      => '2',
        'name'    => 'Jane Doe',
        'age'     => 36,
        'country' => 'Portugal'
    ]);

Querying Records

# query a document and return it as an array
$res = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("c.id, c.name")
    ->where("c.age > @age and c.country = @country")
    ->params(['@age' => 30, '@country' => 'Portugal'])
    ->find(true)
    ->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 = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->setPartitionKey('country')
    ->setPartitionValue('Portugal')
    ->select("c.id, c.name")
    ->where("c.age > @age and c.country = @country")
    ->params(['@age' => 30, '@country' => 'Portugal'])
    ->find()
    ->toArray();

# query the top 5 documents as an array, with the
# document ID as the array key.
$res = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("c.id, c.username")
    ->where("c.age > @age and c.country = @country")
    ->params(['@age' => 10, '@country' => 'Portugal'])
    ->limit(5)
    ->findAll(true)
    ->toArray('id');

# query a document using a collection alias and cross partition query
$res = \Phuze\PhpCosmos\QueryBuilder::instance()
    ->setCollection($collection)
    ->select("HelloWorld.id, HelloWorld.name")
    ->from("HelloWorld")
    ->where("HelloWorld.age > 30")
    ->findAll(true)
    ->toArray();

Deleting Records

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

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