Support updating documents, and handling errors when we do that

Author: lornajane

src/PHPCouchDB/Database.php

@@ -32,6 +32,34 @@ public function __construct(\GuzzleHttp\ClientInterface $client, string $db_name
         $this->db_name = $db_name;
     }
 
+    /**
+     * Get the name of the database
+     */
+    public function getName() : string
+    {
+        return $this->db_name;
+    }
+
+    /**
+     * If you need to make a request that isn't supported by this library,
+     * use this method to get the client to use.  Aimed at more advanced
+     * users/requirements
+     */
+    public function getClient() : \GuzzleHttp\ClientInterface
+    {
+        return $this->client;
+    }
+
+    /**
+     * Format object for var_dump(), removing large properties
+     */
+    public function __debugInfo()
+    {
+        $result = get_object_vars($this);
+        unset($result['client']);
+        return $result;
+    }
+
     /**
      * Fetch all the documents from the database
      *

src/PHPCouchDB/Document.php

@@ -53,4 +53,42 @@ public function __debugInfo()
         unset($result['database']);
         return $result;
     }
+
+    /**
+     * Saves the current state of the document, returning a NEW object to
+     * represent the new document revision.  If the doc is outdated, the update
+     * fails.
+     *
+     * @return Document The updated doc
+     * @throws \PHPCouchDB\Exception\DocumentConflictException if the update
+     *  fails because we don't have the (correct) revision number
+     * @throws \PHPCouchDB\Exception\DatabaseExecption if something else goes
+     *  wrong, with the previous exception included
+     */
+    public function update()
+    {
+        $endpoint = "/" . $this->database->getName() . "/" . $this->id;
+
+        // take a copy and drop out the internal values before sending
+        $doc = get_object_vars($this);
+        $doc['_rev'] = $doc['rev'];
+        unset($doc['client']);
+        unset($doc['id']);
+        unset($doc['rev']);
+        unset($doc['database']);
+
+        try {
+            $response = $this->client->request('PUT', $endpoint, ["json" => $doc]);
+            // get a brand new version and return it as a brand new object
+            $newrev = $this->database->getDocById($this->id);
+            return $newrev;
+        } catch (\GuzzleHTTP\Exception\ClientException $e) {
+            // is it a conflict?  Or something else?
+            if($e->getResponse()->getStatusCode() == 409) {
+                throw new Exception\DocumentConflictException('Conflict. Outdated or missing revision information');
+            } else {
+                throw new Exception\DatabseException('The update failed', 0, $e);
+            }
+        }
+    }
 }

src/PHPCouchDB/Exception/DocumentConflictException.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace PHPCouchDB\Exception;
+
+class DocumentConflictException extends \Exception
+{
+}
+