PHP Classes

File: site/lib/DB/couch/doc/couch_document.md

Recommend this page to a friend!
  Classes of Muhammad Mengrani   PHP CouchDB Product CRUD   site/lib/DB/couch/doc/couch_document.md   Download  
File: site/lib/DB/couch/doc/couch_document.md
Role: Auxiliary data
Content type: text/plain
Description: Auxiliary data
Class: PHP CouchDB Product CRUD
Manage products stored in a CouchDB database
Author: By
Last change: Update of site/lib/DB/couch/doc/couch_document.md
Date: 5 months ago
Size: 9,699 bytes
 

Contents

Class file image Download
This section give details on using couchDocument data mapper couchDocuments to simplify the code =================================== CouchDB embed a simple JSON/REST HTTP API. You can simplify even more your PHP code using couch documents. Couch Documents take care of revision numbers, and automatically propagate updates on database. The basics ========== Creating a new document ======================= To create an empty couchDocument, simply instanciate the **couchDocument** class, passing the couchClient object as the constructor argument. Example : $client = new couchClient('http://localhost:5984/','myDB'); $doc = new couchDocument($client); If I set a property on $doc, it'll be registered in the database. If the property is not _id, the unique identifier will be automatically created by CouchDB, and available in the couchDocument object. Example : $doc->type="contact"; echo $doc->id(); // 1961f10823408cc9e1cccc145d35d10d However if you specify _id, that one will of course be used. Example : $doc = new couchDocument($client); $doc->_id = "some_doc"; echo $doc->id(); // some_doc Setting properties ================== Setting one property at a time ------------------------------ As we just saw, just set the property on the $doc object and it'll be recorded in the database Example : $doc = new couchDocument($client); $doc->_id = "some_doc"; $doc->type = "page"; $doc->title = "Introduction"; Setting a bunch of properties ----------------------------- It's always possible to set several properties in one query using the **set()** method Example using an array : $doc = new couchDocument($client); $doc->set ( array( '_id' => 'some_doc', 'type' => "page", 'title' => "Introduction" ) ); Example using an object $prop = new stdClass(); $prop->_id = "some_doc"; $prop->type = "page"; $prop->title = "Introduction"; $doc = new couchDocument($client); $doc->set ( $prop ); Disabling auto-commit feature ----------------------------- If, for some reason, you need to disable the auto-commit feature, use the **setAutocommit()** method. In this case, you'll have to explicitely call the **record()** method to store your changes on the database. Example : $doc = new couchDocument($client); $doc->setAutocommit(false); $doc->_id = "some_doc"; $doc->type = "page"; $doc->title = "Introduction"; $doc->record(); To know if the auto-commit feature is activated, use the **getAutocommit()** method : it returns a boolean. Unsetting a property -------------------- To unset a property, just use the **unset** PHP function, as you'll do for a PHP object. Example : $prop = new stdClass(); $prop->_id = "some_doc"; $prop->type = "page"; $prop->title = "Introduction"; $doc = new couchDocument($client); $doc->set ( $prop ); unset($doc->title); echo $doc->title ; // won't echo anything Fetching a couchDocument from the database ========================================== The static method **getInstance()** returns a couchDocument when the specified id exists : Example : $doc = couchDocument::getInstance($client,'some_doc'); echo $doc->_rev."\n"; echo $doc->type; Getting a document URI ====================== The method **getUri()** sends back a string giving the current document URI. Example : echo $doc->getUri(); /* db.example.com:5984/testdb/dome_doc_id */ Getting back classic PHP object =============================== To get the couch document fields from a couchDocument object, use the **getFields()** method Example : $doc = couchDocument::getInstance($client,'some_doc'); print_r($doc->getFields()); /* stdClass object { "_id" => "some_doc", "_rev" => "3-234234255677684536", "type" => "page", "title"=> "Introduction" } */ Add/Update an attachment ======================== When the attachment is a file on-disk ------------------------------------- The method **storeAttachment()** adds a new attachment, or update the attachment if it already exists. The attachment contents is located on a file. Example - Store the file /path/to/some/file.txt as an attachment of document id "some_doc" : $doc = couchDocument::getInstance($client,'some_doc'); try { $doc->storeAttachment("/path/to/some/file.txt","text/plain"); } catch (Exception $e) { echo "Error: attachment storage failed : ".$e->getMessage().' ('.$e->getCode().')'; } When the attachment is the content of a PHP variable ---------------------------------------------------- The method **storeAsAttachment()** adds a new attachment, or update the attachment if it already exists. The attachment contents is contained in a PHP variable. Example - Store "Hello world !\nAnother Line" as an attachment named "file.txt" on document "some_doc" : $doc = couchDocument::getInstance($client,'some_doc'); try { $doc->storeAsAttachment("Hello world !\nAnother Line", "file.txt" , "text/plain"); } catch (Exception $e) { echo "Error: attachment storage failed : ".$e->getMessage().' ('.$e->getCode().')'; } Delete an attachment ==================== The method **deleteAttachment()** permanently removes an attachment from a document. Example - Deletes the attachment "file.txt" of document "some_doc" : $doc = couchDocument::getInstance($client,'some_doc'); try { $doc->deleteAttachment("file.txt"); } catch (Exception $e) { echo "Error: attachment removal failed : ".$e->getMessage().' ('.$e->getCode().')'; } Getting the URI of an attachment ================================ The method **getAttachmentUri()** returns the URI of an attachment. Example : $doc = couchDocument::getInstance($client,'some_doc'); if ( $doc->_attachments ) { foreach ( $doc->_attachments as $name => $infos ) { echo $name.' '.$doc->getAttachmentURI($name); // should say something like "file.txt http://localhost:5984/dbname/some_doc/file.txt" } } try { $doc->deleteAttachment("file.txt"); } catch (Exception $e) { echo "Error: attachment removal failed : ".$e->getMessage().' ('.$e->getCode().')'; } couchDocuments replication ========================== The couchDocuments instance provides an easy way to replicate a document to, or from, another database. Think about replication like a copy-paste operation of the document to CouchDB databases. For those methods to work, you should have included the couchReplicator class file lib/couchReplicator.php . Replicating a document to another CouchDB database -------------------------------------------------- Use the **replicateTo()** method to replicate a couchDocument to another couchDB database. Example : $client = new couchClient("http://couch.server.com:5984/","mydb"); // load an existing document $doc = couchDocument::getInstance($client,"some_doc_id"); // replicate document to another database $doc->replicateTo("http://another.server.com:5984/mydb/"); The replicateTo can have another argument, a boolean one. If true, the database will be created on the destination server if it doesn't exist. Replicating a document from another CouchDB database -------------------------------------------------- Use the **replicateFrom()** method to replicate a couchDocument from another couchDB database, and then load it into the couchDocument instance. Example : $client = new couchClient("http://couch.server.com:5984/","mydb"); // load an existing document $doc = new couchDocument($client); // replicate document from another database, and then load it into $doc $doc->replicateFrom("some_doc_id","http://another.server.com:5984/mydb/"); echo $doc->_id ; (should return "some_doc_id") $doc->type="foo"; // doc is recorded on "http://couch.server.com:5984/mydb" // then replicate $doc back to http://another.server.com:5984/mydb/ $doc->replicateTo("http://another.server.com:5984/mydb/"); The replicateFrom can have another argument, a boolean one. If true, the database will be created on the destination server if it doesn't exist. Formating Documents with show functions ======================================= The **show($id,$name,$additionnal_parameters)** method parses the current document through a CouchDB show function. Example : the database contains the following design document : { "_id": "_design/clean", "shows": { "html": "function (doc, req) { send('<p>ID: '+doc._id+', rev: '+doc._rev+'</p>'); }" } } and another document that got the id "some_doc". We load the "some_doc" document as a couchDocument object: $doc = couchDocument::getInstance($client,"some_doc"); We can then request couchDB to parse this document through a show function : $html = $doc->show("clean","html"); // html should contain "<p>ID: some_doc, rev: 3-2342342346</p>" The show method is a proxy method to the **getShow()** method of **couchClient**. Updating a document using update handlers ========================================= The **update($id,$name,$additionnal_params)** method allows to use the CouchDB [update handlers](http://wiki.apache.org/couchdb/Document_Update_Handlers) feature to update an existing document. The couchDocument object shouldd have an id for this to work ! Please see **couchClient** *updateDoc* method for more infos.