Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A simple but powerful PHP library for talking to CouchDB.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



Version 0.1.0

Sag is a simple PHP library for working with CouchDB. It is designed to not
force any particular programming method on its users - you just pass PHP
objects, and get StdClass objects and Exceptions back. This makes it trivial to
incorporate Sag into your application, build different functionality on top of
it, and expand Sag to incorporate new CouchDB functionality.


Sag is tested against CouchDB 0.10.x and 0.11.x. 

Error Handling

Sag's paradigm of simplicity is carried into its error handling by allowing you
to send data to CouchDB that will result in errors (ex., malformed JSON). This
is because CouchDB knows when there's an error better than Sag, and it would be
disingenuous for Sag to try and detect errors for CouchDB. Therefore, Sag will
only look for interface problems and issues that are native to PHP (ex.,
passing an int instead of a StdClass).

All errors are floated back to your application with exceptions. Sag does not
catch any errors itself, allowing your application to care about them or not.

There are two types of exceptions: 

SagException            For errors that happen within Sag, such as an invalid
                        type being passed to a function or being unable to open
                        a socket to the server.

SagCouchException       For errors generated by CouchDB (ex., if you pass it
                        invalid JSON). The CouchDB error message will be put
                        into the exception's message (ie., $e->getMessage())
                        and the HTTP status code will be the exception's code
                        (ie., $e->getCode()).

You can catch these two types of exceptions explicitly, allowing you to split
your error handling depending on where the error occurred, or implicitly by
simply catching the Exception class.


Sag uses sockets, so there is no dependency on other libraries such as cURL. If
you want to monitor your application's activity on the server side (ex., if you
are proxying requests to CouchDB through a web server), then examine the HTTP
User-Agent header.


When you've told Sag to decode CouchDB's responses, they are stored in an
object, breaking out the HTTP header lines and data. For example, running
`print_r($sag->get('/1'));` (where '/1' is the location of a document) would
give you something like:

stdClass Object
    [headers] => stdClass Object
            [_HTTP] => stdClass Object
                    [raw] => HTTP/1.0 200 OK
                    [version] => 1.0
                    [status] => 200

            [Server] =>  CouchDB/0.10.0 (Erlang OTP/R13B)
            [Etag] =>  "1-4c6114c65e295552ab1019e2b046b10e"
            [Date] =>  Mon, 12 Apr 2010 23:01:39 GMT
            [Content-Type] =>  text/plain;charset=utf-8
            [Content-Length] =>  68
            [Cache-Control] =>  must-revalidate

    [body] => stdClass Object
            [_id] => 1
            [_rev] => 1-4c6114c65e295552ab1019e2b046b10e
            [foo] => bar


HTTP protocol information is stored in $result->headers, its headers broken out
as entries in the headers array - the "_HTTP" array element holds the basic
HTTP information in raw form ($result->headers->_HTTP->raw), and then broken
out into HTTP version number ($result->headers->_HTTP->version) and status code

The $result->body property holds the raw data from CouchDB, which you can have
Sag automatically decode into PHP objects with json_decode().

If you've told Sag to not decode CouchDB's responses, then it'll only return
the resulting JSON from CouchDB as a string (what would have been in the body
property if you had set decode to true).


More complete function information is available at

FUNCTION                                        DESCRIPTION

Sag($host = "", $port = "5984")        Specify the address and port in
                                                the constructor.

login($user, $pass, $type = Sag::$AUTH_BASIC)   Set the username and password to
                                                use for all subsequent 
                                                transactions to the server
                                                (null them out to "logout").

decode($bool)                                   Whether or not to decode the 
                                                JSON from CouchDB with PHP's

get($url)                                       Get the specified URL. Ex.,
                                                get("/1") gets a doc with an
                                                _id of 1.

delete($id, $rev)                               Delete a document.

put($id, $data)                                 PUT's a document - $data will
                                                need a $_rev property.

post($data)                                     POST's a document.

bulk($array)                                    Does a bulk transaction, using
                                                the specified array.

copy($srcID, $dstID, $dstRev = null)            Copy a document, optionally to
                                                an existing document.

createDatabase($name)                           Creates the database.

deleteDatabase($name)                           Deletes the database.

setDatabase($name)                              Specifies which database to
                                                work with.

getAllDocs($includeDocs = false,                Runs /_all_docs with the
            $limit = null,                      provided parameters. $keys is 
            $startKey = null,                   an array of specific keys that
            $endKey = null,                     you want returned.
            $keys = null

getAllDatabases()                               Runs /_all_dbs.

generateIDs($num = 10)                          Generates a specified number of
                                                IDs with /_uuids.

replicate($src, $target, $continuous = false)   Replicate between two 
                                                databases, optionally

compact($viewName = null)                       Compacts the currently selected
                                                database (no argument), or the
                                                provided view.


Sag is released under the Apache License, version 2.0. See the file named
LICENSE for more information.


See for more detailed information, bug reporting,
planned features, etc.

Something went wrong with that request. Please try again.