Document

class PHPOnCouch\CouchClient

PHPOnCouch\CouchClient::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.

Returns

An object with the total_rows number, the rows returned and other informations.

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";
}

PHPOnCouch\CouchClient::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.

Params string $id

The id of the document to fetch

Returns

The document if found. Otherwise, a CouchNotFoundException is throw.

The document is sent back as an HTTP object of class stdClass.

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()

PHPOnCouch\CouchClient::rev($value)

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

Params mixed $value

The specific revision to fetch of a document.

Returns

The CouchClient instance.

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

PHPOnCouch\CouchClient::asCouchDocuments()

When the getDoc function will be called, it will return a CouchDocument. You can however get back the document as a CouchDocument object by calling the asCouchDocuments() method before the getDoc($id) method.

Returns

The CouchClient instance.

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"

PHPOnCouch\CouchClient::conflicts()

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

Returns

The CouchClient instance.

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);
}

PHPOnCouch\CouchClient::revs()

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

Returns

The CouchClient instance.

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);

PHPOnCouch\CouchClient::revs_info()

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

Returns

The CouchClient instance.

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);

PHPOnCouch\CouchClient::open_revs($value)

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

Params array|string $value

Should be an array of revision ids or the special keyword all (to fetch all revisions of a document)

Returns

The CouchClient instance.

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"
        )
    )
)

PHPOnCouch\CouchClient::storeDoc($doc)

Store a document on the CouchDB server.

Params stdClass $doc

$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.

Returns

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 , you can easily update any document part without having to send back the whole document.

PHPOnCouch\CouchClient::updateDoc($ddoc_id, $handler_name, $params, $doc_id = null)

Update document according to the code defined in the update handler.

Params string $ddoc_id

The desing document id (suffix of _design/)

Params string $handler_name

The update handler name

Params array $params

to complete…

Params string $doc_id

The document id to udpate

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");

PHPOnCouch\CouchClient::updateDocFullAPI($ddoc_id, $handler_name, $options)

Update document according to the code defined in the update handler.

params string $ddoc_id

The id of the design document (suffix of _design/)

params string $handler_name

Update handler name

params array $options

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") ) );

PHPOnCouch\CouchClient::deleteDoc($doc)

Permanently removes $doc from the CouchDB server.

params stdClass $doc

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";
}

PHPOnCouch\CouchClient::copyDoc($id, $new_id)

Provides an handy way to copy a document.

params string $id

The id of the document to copy.

params string $new_id

The id of the new document.

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";
}

Attachments

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.

PHPOnCouch\CouchClient::storeAttachment($doc, $file, $content_type = 'application/octet-stream', $filename = null)

Handles the process of storing an attachment on a CouchDB document.

params stdClass $doc

A PHP object containing at least the properties _id and _rev

params string $file

The complete path to the file on disk

params string $content_type

The file’s content-type

params string $filename

The name of the attachment on CouchDB document, if the name is not the name of the file in $file

returns stdClass

An HTTP response object like this :

stdClass ( "ok" => true, "id" => "BlogPost5676" , "rev" => "5-2342345476" )

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" )

PHPOnCouch\CouchClient::storeAsAttachment($doc, $data, $filename, $content_type = 'application/octet-stream')

Records as a CouchDB document’s attachment the content of a PHP variable.

params stdClass $doc

A PHP object containing at least the properties _id and _rev

params mixed $data

The data (the content of the attachment

params string $filename

The name of the attachment on CouchDB document

params string $content_type

The file’s content-type

returns

The HTTP response object.

Example :

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

PHPOnCouch\CouchClient::deleteAttachment($doc, $attachment_name)

Delete an attachment from a CouchDB document.

params stdClass $doc

An object with, at least, _id and _rev properties,

params $attachment_name

the name of the attachment to delete.

returns

An stdClass representing the HTTP response.

Example :

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

PHPOnCouch\CouchClient::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 .

Bulk operations

A bulk operation is a unique query performing actions on several documents. CouchDB Bulk operations API are described in this wiki page .

PHPOnCouch\CouchClient::keys($ids)->getAllDocs()

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";
}

PHPOnCouch\CouchClient::storeDocs($docs, $new_edits)

To store several documents in one go, use the method storeDocs($docs, $new_edits). $docs is an array containing the documents to store (as CouchDocuments, PHP stdClass or PHP arrays). $new_edits is related to the updates of the revision. If set to true (which is the default), assign new revision id for each update. When set to false, it prevents the database from assigning them new reivision IDS.

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.

PHPOnCouch\CouchClient::deleteDocs($docs, $new_edits)

To delete several documents in a single HTTP request, use the method deleteDocs($docs, $new_edits). $docs is an array containing the documents to store (as couchDocuments, PHP stdClass or PHP arrays). $new_edits is related to the updates of the revision. If set to true (which is the default), assign new revision id for each update. When set to false, it prevents the database from assigning them new reivision IDS.

PHPOnCouch\CouchClient::asArray()

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"
)