Login   Register  
PHP Classes
elePHPant
Icontem

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

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  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:
Date: 1 year 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.