Login   Register  
PHP Classes
elePHPant
Icontem

File: site/lib/DB/couch/doc/couch_client-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_client-document.md  >  Download  
File: site/lib/DB/couch/doc/couch_client-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: 17,060 bytes
 

Contents

Class file image Download
This section details the available methods to work with documents

Getting all documents
=====================

The method **getAllDocs()** retrieve all documents from the database. In fact it only retrieve document IDs, unless you specify the server to include the documents using the [View query parameters syntax](http://github.com/dready92/PHP-on-Couch/blob/master/doc/couch_client-view.md).

Example :
    
    $all_docs = $client->getAllDocs();
    echo "Database got ".$all_docs->total_rows." documents.<BR>\n";
    foreach ( $all_docs->rows as $row ) {
        echo "Document ".$row->id."<BR>\n";
    }

Getting a document by ID
========================

The method **getDoc($id)** gives back the document that got ID $id, if it exists. Note that if the document does not exist, the method will throw an error.

The document is sent back as an HTTP object of class [stdClass](http://fr3.php.net/manual/en/reserved.classes.php).

Example :

    try {
        $doc = $client->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
	        }
        exit(1);
    }
    echo $doc->_id.' revision '.$doc->_rev;

Chainable methods to use with getDoc()
======================================

Getting a particular revision of the document
---------------------------------------------

The chainable **rev($value)** method specify the document revision to fetch.

Example :

    try {
        $doc = $client->rev("1-849aff6ad4a38b1225c80a2119dc31cb")->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id or revision 1-849aff6ad4a38b1225c80a2119dc31cb does not exist !";
        }
        exit(1);
    }
    echo $doc->_rev ; // should echo 1-849aff6ad4a38b1225c80a2119dc31cb


Getting a document as a couchDocument object
--------------------------------------------

The **getDoc($id)** method returns a PHP stdClass object. You can however get back the document as a couchDocument object by calling the **asCouchDocuments()** method before the **getDoc($id)** method.

Example :

    try {
        $doc = $client->asCouchDocuments()->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
        }
        exit(1);
    }
    echo get_class($doc); // should echo "couchDocument"


Adding conflicts informations (if any)
--------------------------------------

The chainable method **conflicts()** asks CouchDB to add to the document a property *_conflicts* containing conflicting revisions on an object.

Example :

    try {
        $doc = $client->conflicts()->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
        }
        exit(1);
    }
    if ( $doc->_conflicts ) {
        print_r($doc->_conflicts);
    }
    

Adding revisions list
--------------------------------------

The chainable method **revs()** asks CouchDB to add to the document a property *_revisions* containing the list of revisions for an object.

Example :

    try {
        $doc = $client->revs()->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
        }
        exit(1);
    }
    print_r($doc->_revisions);

Adding revisions informations
--------------------------------------

The chainable method **revs_info()** asks CouchDB to add to the document a property *_revs_info* containing the avaibility of revisions for an object.

Example :

    try {
        $doc = $client->revs_info()->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
        }
        exit(1);
    }
    print_r($doc->_revs_info);


Fetching Several revisions of a document
========================================

Using the **open_revs( $value )** method, CouchDB returns an array of objects.

**$value** should be an array of revision ids or the special keyword all (to fetch all revisions of a document)

Example :

    try {
        $doc = $client->open_revs( array("1-fbd8a6da4d669ae4b909fcdb42bb2bfd", "2-5bc3c6319edf62d4c624277fdd0ae191") )->getDoc("some_doc_id");
    } catch ( Exception $e ) {
        if ( $e->getCode() == 404 ) {
           echo "Document some_doc_id does not exist !";
        }
        exit(1);
    }
    print_r($doc->_revs_info);

Which should return something similar to :

    array (
        stdClass(
            "missing" => "1-fbd8a6da4d669ae4b909fcdb42bb2bfd"
        ),
        stdClass(
            "ok" => stdClass(
                "_id"  => "some_doc_id",
                "_rev" => "2-5bc3c6319edf62d4c624277fdd0ae191",
                "hello"=> "foo"
            )
        )
    )

Storing a document
==================

The method **storeDoc($doc)** store a document on the CouchDB server. $doc should be an object. If the property $doc->_rev is set, the method understand that it's an update, and as so requires the property $doc->\_id to be set. If the property $doc->\_rev is not set, the method checks for the existance of property $doc->\_id and initiate the appropriate request.

The response of this method is the CouchDB server response. In other words if the request ends successfully the returned object should be :

    stdClass ( "ok" => true, "id" => "some_doc_id" , "rev" => "3-23423423476" )

Example : creating a document without specifying id

    $new_doc = new stdClass();
    $new_doc->title = "Some content";
    try {
        $response = $client->storeDoc($new_doc);
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }
    echo "Doc recorded. id = ".$response->id." and revision = ".$response->rev."<br>\n";
    // Doc recorded. id = 0162ff06747761f6d868c05b7aa8500f and revision = 1-249007504

Example : creating a document specifying the id

    $new_doc = new stdClass();
    $new_doc->title = "Some content";
    $new_doc->_id = "BlogPost6576";
    try {
        $response = $client->storeDoc($new_doc);
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }
    echo "Doc recorded. id = ".$response->id." and revision = ".$response->rev."<br>\n";
    // Doc recorded. id = BlogPost6576 and revision = 1-249004576

Example : updating an existing document :

    // get the document
    try {
        $doc = $client->getDoc('BlogPost6576');
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }

    // make changes
    $doc->title = 'Some smart content';
    $doc->tags = array('twitter','facebook','msn');

    // update the document on CouchDB server
    try {
        $response = $client->storeDoc($doc);
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }
    echo "Doc recorded. id = ".$response->id." and revision = ".$response->rev."<br>\n";
    // Doc recorded. id = BlogPost6576 and revision = 2-456769086

Updating a document
===================

Using CouchDB [Update handlers](http://wiki.apache.org/couchdb/Document_Update_Handlers), you can easily update any document part without having to send back the whole document.

Basic API
---------

The method **updateDoc( $ddoc_id, $handler_name, $params, $doc_id = null )** will try to update document according to the code defined in the update handler *$handler_name* of th design document *_design/$ddoc_id*.

Example : incrementing a document counter

Let's say we have a design document _design/myapp containing :

    "updates": {
        "bump-counter" : "function(doc, req) {
            if ( !doc ) return [null, {\"code\": 404, \"body\": \"Document not found / not specified\"}]
            if (!doc.counter) doc.counter = 0;
            doc.counter += 1;
            var message = \"<h1>bumped it!</h1>\";
            return [doc, message];
        }",
    }

To bump the counter of the document "some_doc" , use :

    $client->updateDoc("myapp","bump-counter",array(),"some_doc");


Full API
--------

The method **updateDocFullAPI($ddoc_id, $handler_name, $options)** will try to update document according to the code defined in the update handler *$handler_name* of th design document *_design/$ddoc_id*.

$options is an array of optionnal query modifiers :
"params" : array|object of variable to pass in the URL ( /?foo=bar )
"data"   : string|array|object data to set in the body of the request. If data is an array or an object it will be urlencoded using PHP http_build_query function and the request Content-Type header will be set to "application/x-www-form-urlencoded".
"Content-Type": string the Content-Type HTTP header to send to the couch server


Example :
---------

    $client->updateDocFullAPI("myapp","bump-counter",array( "data" => array("Something"=>"is set") ) );



Deleting a document
===================

The method **deleteDoc ( $doc )** permanently removes $doc from the CouchDB server. $doc should be an object containing at least \_id and \_rev properties.

Example :

    // get the document
    try {
        $doc = $client->getDoc('BlogPost6576');
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }
    // permanently remove the document
    try {
        $client->deleteDoc($doc);
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }


Copying a document
==================

The **copyDoc($id,$new_id)** method provides an handy way to copy a document. $id is the id of the document to copy. $new_id is the id of the new document.

Upon success, this method returns the CouchDB server response, which has the main form than a document storage :

    stdClass ( "ok" => true, "id" => "new_id" , "rev" => "1-23423423476" )

Example :

    try {
        $response = $client->copyDoc('BlogPost6576','CopyOfBlogPost6576');
    } catch (Exception $e) {
        echo "ERROR: ".$e->getMessage()." (".$e->getCode().")<br>\n";
    }

Attaching a file to a document
==============================

There is two methods handling attachments, it depends whether the file to send as attachment is on the harddrive, or if it's contained in a PHP variable. The first one should be more reliable for large attachments.

On-disk files to attachments
----------------------------

The method **storeAttachment($doc,$file,$content_type = 'application/octet-stream',$filename = null) ** handles the process of storing an attachment on a CouchDB document.

* **$doc** is a PHP object containing at least the properties \_id and \_rev
* **$file** is the complete path to the file on disk
* **$content_type** is the file's [content-type](http://en.wikipedia.org/wiki/MIME)
* **$filename** is the name of the attachment on CouchDB document, if the name is not the name of the file in $file

Example :

    $doc = $client->getDoc('BlogPost5676');
    $ok = $client->storeAttachment($doc,'/etc/resolv.conf','text/plain', 'my-resolv.conf');
    print_r($ok);
    // stdClass ( "ok" => true, "id" => "BlogPost5676" , "rev" => "5-2342345476" )

PHP data to attachments
----------------------------

The method **storeAsAttachment($doc,$data,$filename,$content_type = 'application/octet-stream')** records as a CouchDB document's attachment the content of a PHP variable.

* **$doc** is a PHP object containing at least the properties \_id and \_rev
* **$data** is the data (the content of the attachment)
* **$filename** is the name of the attachment on CouchDB document
* **$content_type** is the file's [content-type](http://en.wikipedia.org/wiki/MIME)

Example :

    $doc = $client->getDoc('BlogPost5676');
    $google_home=file_get_contents('http://www.google.com/');
    $ok = $client->storeAsAttachment($doc,$google_home,'text/html', 'GoogleHomepage.html');
    print_r($ok);
    // stdClass ( "ok" => true, "id" => "BlogPost5676" , "rev" => "5-2342345476" )

Delete a document attachment
============================

the method **deleteAttachment($doc,$attachment_name )** delete an attachment from a CouchDB document. $doc is an object with, at least, \_id and \_rev properties, and $attachment_name is the name of the attachment to delete.

Example :

    $doc = $client->getDoc('BlogPost5676');
    $ok = $client->deleteAttachment($doc,'GoogleHomepage.html');

Request a show view on a document
=================================

The method **getShow($design_id, $name, $doc_id = null, $additionnal_parameters = array() )** request a show formatting of document *$doc_id* with show method *$name* stored in design document *design_id*.

Example :

    $output = $client->getShow('blogs','html','BlogPost5676');

More infos on CouchDB show formatting [here](http://wiki.apache.org/couchdb/Formatting_with_Show_and_List)

Bulk operations
===============

A bulk operation is a unique query performing actions on several documents. CouchDB Bulk operations API are described in [this wiki page](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API).

Bulk documents retrieval
------------------------

To retrieve several documents in one go, knowing their IDs, select documents using the **keys($ids)** coupled with the method **getAllDocs()**. $ids is an array of documents IDs. This function acts like a view, so the output is the view output of CouchDB, and you should use "include_docs(TRUE)" to have documents contents.

Example :

    $view = $client->include_docs(true)->keys->( array('BlogPost5676','BlogComments5676') )->getAllDocs();
    foreach ( $view->rows as $row ) {
      echo "doc id :".$row->doc->_id."\n";
    }

Bulk documents storage
------------------------

To store several documents in one go, use the method **storeDocs($docs,$all_or_nothing)**. $docs is an array containing the documents to store (as couchDocuments, PHP [stdClass](http://fr3.php.net/manual/en/reserved.classes.php) or PHP arrays). $all_or_nothing is related to the updates on the database : if set to false (which is the default), all documents are saved one by one, which means that, in case of a power failure on the database, we could have some documents stored and some not stored. When set to true, couchDB will commit all documents in one go : in case of a power failure, no document will be stored, or all documents will be stored.

Example :
    $docs = array (
        array('type'=>'blogpost','title'=>'post'),
        array('type'=>'blogcomment','blogpost'=>'post','depth'=>1),
        array('type'=>'blogcomment','blogpost'=>'post','depth'=>2)
    );
    $response = $client->storeDocs( $docs );
    print_r($response);

which should give you something like :

    Array
    (
        [0] => stdClass Object
            (
                [id] => 8d7bebddc9828ed2edd052773968826b
                [rev] => 1-3988163576
            )
    
        [1] => stdClass Object
            (
                [id] => 37bcfd7d9e94c67617982527c67efe44
                [rev] => 1-1750264873
            )
    
        [2] => stdClass Object
            (
                [id] => 704a51a0b6448326152f8ffb8c3ea6be
                [rev] => 1-2477909627
            )
    
    )

This method also works to update documents.

Bulk documents removal
----------------------

To delete several documents in a single HTTP request, use the method **deleteDocs($docs,$all_or_nothing)**. $docs is an array containing the documents to store (as couchDocuments, PHP [stdClass](http://fr3.php.net/manual/en/reserved.classes.php) or PHP arrays). $all_or_nothing is related to the updates on the database : if set to false (which is the default), all documents are saved one by one, which means that, in case of a power failure on the database, we could have some documents deleted and some not deleted. When set to true, couchDB will commit all documents in one go : in case of a power failure, no document will be deleted, or all documents will be deleted.


Choosing couchClient output format
==================================

When converting a JSON object to PHP, we can choose the type of the value returned from a couchClient query.

Take for example the following JSON object :
    { 'blog' : true, 'comments' : { 'title' : 'cool' } }

This can be converted into a PHP object :

    stdClass Object
    (
        [blog] => true
        [comments] => stdClass Object
            (
                [title] => "cool"
            )
    )


OR into a PHP array :

    Array
    (
        [blog] => true
        [comments] => Array
            (
                [title] => "cool"
            )
    )


Using the defaults, JSON objects are mapped to PHP objects. The **asArray()** method can be used to map JSON objects to PHP arrays.

Example:

    $doc = $client->asArray()->getDoc('BlogPost5676');
    print_r($doc);

should print :

    Array (
        [id] => "BlogPost5676"
    )