Merge pull request #30 from jupitern/development

Development
jupitern · Jun 29, 2022 · a5b83a8 · a5b83a8
2 parents af88a9b + 30e63b0
commit a5b83a8
Show file tree

Hide file tree

Showing 7 changed files with 428 additions and 463 deletions.
diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 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.
@@ -16,102 +18,91 @@ Include jupitern/cosmosdb in your project, by adding it to your composer.json fi
 
 ## Changelog
 
-### v2.5.0
+### 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](https://github.com/cocteau666/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.
 
 ## Usage
 
 ### Connecting
 
 ```php
-$conn = new \Jupitern\CosmosDb\CosmosDb('hostName', 'primaryKey');
-$conn->setHttpClientOptions(['verify' => false]); # optional: set guzzle client options.
-$db = $conn->selectDB('dbName');
-$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 \Jupitern\CosmosDb\CosmosDb('hostName', 'primaryKey');
+$conn = new \Jupitern\CosmosDb\CosmosDb('https://localhost:8081', 'primaryKey');
 $conn->setHttpClientOptions(['verify' => false]); # optional: set guzzle client options.
-$db = $conn->selectDB('dbName');
-$collection = $db->selectCollection('collectionName', 'myPartitionKey');
+$db = $conn->selectDB('testdb');
+
+# create a new collection
+$collection = $db->createCollection('Users', 'country');
+
+# select existing collection
+$collection = $db->selectCollection('Users');
 ```
 
 ### Inserting Records
 
 ```php
-
-# consider a existing collection called "Users" with a partition key "country"
-
-# insert a record
 $rid = \Jupitern\CosmosDb\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
-# note: this follows the same string format as is used when creating
-# a collection with a partition key via the Azure Portal
-$rid = \Jupitern\CosmosDb\QueryBuilder::instance()
-    ->setCollection($collection)
-    ->setPartitionKey('/form/person/country')
-    ->save(['id' => '2', 'name' => 'Jane doe', 'age' => 35, 'country' => 'Portugal']);
+    ->save([
+        'id' => '2', 
+        'name' => 'Jane doe', 
+        'age' => 35, 
+        'country' => 'Portugal'
+    ]);
 ```
 
 ### Updating Records
 
 ```php
-# update a record
 $rid = \Jupitern\CosmosDb\QueryBuilder::instance()
     ->setCollection($collection)
     ->setPartitionKey('country')
-    ->save(["_rid" => $rid, 'id' => '2', 'name' => 'Jane Doe Something', 'age' => 36, 'country' => 'Portugal']);
+    ->save([
+        "_rid" => $rid, 
+        'id' => '2', 
+        'name' => 'Jane Doe Something', 
+        'age' => 36, 
+        'country' => 'Portugal'
+    ]);
 ```
 
 ### Querying Records
 
 ```php
-# query a document and return it as an array
+# 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' => 30, '@country' => 'Portugal'])
+    ->params(['@age' => 10, '@country' => 'Portugal'])
     ->find(true) # pass true if is cross partition query
     ->toArray();
 
-# query a document using a known partition value,
+# 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
@@ -120,29 +111,30 @@ $res = \Jupitern\CosmosDb\QueryBuilder::instance()
     ->setCollection($collection)
     ->setPartitionValue('Portugal')
     ->select("c.id, c.name")
-    ->where("c.age > @age and c.country = @country")
-    ->params(['@age' => 30, '@country' => 'Portugal'])
+    ->where("c.age > @age")
+    ->params(['@age' => 10])
     ->find()
     ->toArray();
 
-# query the top 5 documents as an array, with the
+# 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.username")
+    ->select("c.id, c.name")
     ->where("c.age > @age and c.country = @country")
     ->params(['@age' => 10, '@country' => 'Portugal'])
     ->limit(5)
-    ->findAll() # cannot limit cross-partition queries
+    ->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 > 30")
+    ->where("TestColl.age > @age")
+    ->params(['@age' => 10])
     ->findAll(true) # pass true if is cross partition query
     ->toArray();
 ```
@@ -154,7 +146,7 @@ $res = \Jupitern\CosmosDb\QueryBuilder::instance()
 $res = \Jupitern\CosmosDb\QueryBuilder::instance()
     ->setCollection($collection)
     ->setPartitionKey('country')
-    ->where("c.age > 30 and c.country = 'Portugal'")
+    ->where("c.age > 20 and c.country = 'Portugal'")
     ->delete();
 
 # delete all documents that match criteria (cross partition)
@@ -164,3 +156,30 @@ $res = \Jupitern\CosmosDb\QueryBuilder::instance()
     ->where("c.age > 20")
     ->deleteAll(true);
 ```
+
+### Error handling
+
+```php
+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
diff --git a/composer.json b/composer.json
@@ -8,8 +8,9 @@
     "source": "https://github.com/jupitern/cosmosdb",
     "issues": "https://github.com/jupitern/cosmosdb/issues"
   },
-  "require" :{
-    "php":">=7.0",
+  "require": {
+    "php": ">=8.0",
+    "ext-curl": "*",
     "guzzlehttp/guzzle": "^7.4"
   },
   "autoload": {