HeadCouch - the CouchDB PHP Client

Posted on: June 21, 2014 by Dimitar Ivanov


As a LAMP developer I usе MySQL database for my daily tasks. MySQL is a classic RDBMS that store structured data in tabular format. When my data aren't structured I need a different approach to store and retrieve it. That's one of the cases in which use of NoSQL database (key-value, graph, document store) I consider meaningful.


Apache CouchDB is a database that uses JSON for documents, JavaScript for MapReduce indexes, and regular HTTP for its API.


HeadCouch is an open source CouchDB Client for PHP 5.x that allow you to store your data, access your documents and query your indexes in OOP manner inside your PHP projects.

Let's see how to use the HeadCouch API:

Access the CouchDB server with HeadCouchServer

require_once 'HeadCouch.php';

$transport = HeadCouchCurl::newInstance('', 5984)

$server = HeadCouchServer::newInstance($transport);

// Accessing the root of a CouchDB instance
$result = $server->ping();

// Requests a Universally Unique Identifier from the CouchDB instance
$result = $server->uuid();

// Returns a list of all the databases
$result = $server->allDbs();

// List of running tasks
$result = $server->activeTasks();

// Returns a list of all database events in the CouchDB instance
$result = $server->dbUpdates();

// Gets the CouchDB log
$result = $server->log();

// Restarts the CouchDB instance
$result = $server->restart();

// Returns the statistics for the running server
$result = $server->stats();

Access and manage your databases with HeadCouchDatabase

require_once 'HeadCouch.php';

$transport = HeadCouchCurl::newInstance('', 5984)

$database = HeadCouchDatabase::newInstance($transport, 'db_name');

// Create database
$result = $database->create();

// Delete database
$result = $database->delete();

// Gets information about the specified database
$result = $database->get();

// Returns the HTTP Headers about the specified database
$result = $database->head();

// Creates a new document in the specified database
$result = $database->post(array(
    'key1' => 'val1', 
    'key2' => 'val2'

Access and manage your documents with HeadCouchDocument

require_once 'HeadCouch.php';

$transport = HeadCouchCurl::newInstance('', 5984)

$document = HeadCouchDocument::newInstance($transport, 'db_name', 'doc_name');

// Creates a new document
$result = $document->create(array(
    'key1' => 'val1', 
    'key2' => 'val2'

// Deletes the specified document from the database
$result = $document->delete();

// Returns document
$result = $document->get();

// Returns document's revision token
$result = $document->getRevision();

// Returns the HTTP Headers about the specified document
$result = $document->head();

For more examples and complete API reference see GitHub Repo. Further updates are on their way, so keep listening on twitter @DimitarIvanov

See also
Social sharing

If you have questions about HeadCouch, the CouchDB PHP Client, drop a comment below. And do not be shy to share this article. Thanks so much for reading.


Comments are closed