Enable adding records to the database

Author: lornajane

src/PHPCouchDB/Database.php

@@ -79,4 +79,49 @@ public function getAllDocs($options = []) : array
             }
         }
     }
+
+    /**
+     * Create a new document in the database
+     *
+     * @param array $doc  An array representing the document's keys and values.
+     *  The data can be nested arrays, lists, anything
+     *  - if you include an "id" key, this will become the document ID,
+     *      otherwise it'll be autogenerated
+     * @return PHPCouchDB\Document a document object of your new doc
+     */
+    public function create($doc)
+    {
+        if (!is_array($doc)) {
+            throw new \PHPCouchDB\Exception\DatabaseException('A document is required, in array format');
+        }
+
+        // do we have the ID?
+        if (isset($doc['id']) && !empty($doc['id'])) {
+            // remove the ID from the array, then use it in the URL with PUT
+            $id = $doc['id'];
+            unset($doc['id']);
+            $endpoint = "/" . $this->db_name . "/" . $id;
+            $verb = 'PUT';
+        } else {
+            // no ID, make a POST request to create the record
+            $endpoint = "/" . $this->db_name . "/";
+            $verb = 'POST';
+        }
+
+        try {
+            $response = $this->client->request($verb, $endpoint, ['json' => $doc]);
+            if ($response->getStatusCode() == 201 && $response_data = json_decode($response->getBody(), true)) {
+                $id = $response_data['id'];
+                // all good.  Let's fetch the doc and return it
+                $fetched_data = json_decode($this->client->get('/' . $this->db_name . '/' . $id)->getBody());
+                return new \PHPCouchDB\Document($fetched_data);
+            }
+        } catch (\GuzzleHttp\Exception\ConnectException $e) {
+            throw new \PHPCouchDB\Exception\ServerException(
+                "Could not create record.  Error: " . $e->getMessage(),
+                0,
+                $e
+            );
+        }
+    }
 }

tests/PHPCouchDB/DatabaseTest.php

@@ -62,4 +62,47 @@ public function testGetAllDocsWithNoDocs() {
         $this->assertInternalType('array', $docs);
         $this->assertEmpty($docs);
     }
+
+    public function testCreateWithID() {
+        $egdb1 = '{"db_name":"egdb","update_seq":"0-g1AAAABXeJzLYWBgYMpgTmEQTM4vTc5ISXLIyU9OzMnILy7JAUklMiTV____PyuRAY-iPBYgydAApP5D1GYBAJmvHGw","sizes":{"file":8488,"external":0,"active":0},"purge_seq":0,"other":{"data_size":0},"doc_del_count":0,"doc_count":0,"disk_size":8488,"disk_format_version":6,"data_size":0,"compact_running":false,"instance_start_time":"0"}';
+        $use_response = new Response(200, [], $egdb1);
+        $create = '{"ok":true,"id":"abcde12345","rev":"1-928ec193918889e122e7ad45cfd88e47"}';
+        $create_response = new Response(201, [], $create);
+        $fetch = '{"_id":"abcde12345","_rev":"1-928ec193918889e122e7ad45cfd88e47","noise":"howl"}';
+        $fetch_response = new Response(200, [], $fetch);
+
+		$mock = new MockHandler([ $this->db_response, $use_response, $create_response, $fetch_response ]);
+		$handler = HandlerStack::create($mock);
+		$client = new Client(['handler' => $handler]);
+
+		// userland code starts
+		$server = new \PHPCouchDB\Server(["client" => $client]);
+        $database = $server->useDB(["name" => "egdb"]);
+        $doc = $database->create(["noise" => "howl", "id" => "abcde12345"]);
+
+        $this->assertInstanceOf('PHPCouchDB\Document', $doc);
+        $this->assertObjectHasAttribute('id', $doc);
+        $this->assertEquals("abcde12345", $doc->id);
+    }
+
+    public function testCreateWithoutID() {
+        $egdb1 = '{"db_name":"egdb","update_seq":"0-g1AAAABXeJzLYWBgYMpgTmEQTM4vTc5ISXLIyU9OzMnILy7JAUklMiTV____PyuRAY-iPBYgydAApP5D1GYBAJmvHGw","sizes":{"file":8488,"external":0,"active":0},"purge_seq":0,"other":{"data_size":0},"doc_del_count":0,"doc_count":0,"disk_size":8488,"disk_format_version":6,"data_size":0,"compact_running":false,"instance_start_time":"0"}';
+        $use_response = new Response(200, [], $egdb1);
+        $create = '{"ok":true,"id":"95613816b3a7490727388ebb47002c0f","rev":"1-928ec193918889e122e7ad45cfd88e47"}';
+        $create_response = new Response(201, [], $create);
+        $fetch = '{"_id":"95613816b3a7490727388ebb47002c0f","_rev":"1-928ec193918889e122e7ad45cfd88e47","noise":"howl"}';
+        $fetch_response = new Response(200, [], $fetch);
+
+		$mock = new MockHandler([ $this->db_response, $use_response, $create_response, $fetch_response ]);
+		$handler = HandlerStack::create($mock);
+		$client = new Client(['handler' => $handler]);
+
+		// userland code starts
+		$server = new \PHPCouchDB\Server(["client" => $client]);
+        $database = $server->useDB(["name" => "egdb"]);
+        $doc = $database->create(["noise" => "howl"]);
+
+        $this->assertInstanceOf('PHPCouchDB\Document', $doc);
+        $this->assertObjectHasAttribute('id', $doc);
+    }
 }