Database

This section give details on actions on the CouchDB server through PHP on Couch.

Getting started

To use PHP on Couch client, you have to create a couchClient instance, setting the URL to your couchDB server, and the database name.

Example : connect to the couchDB server at http://my.server.com on port 5984 and on database mydb :

$client = new CouchClient("http://my.server.com:5984/","mydb");

If you want to authenticate to the server using a username & password, just set it in the URL.

Example : connect to the couchDB server at http://my.server.com on port 5984 using the username “couchAdmin”, the password “secret” and on database mydb :

$client = new CouchClient("http://couchAdmin:secret@my.server.com:5984/","mydb");

You can also tell couchClient to use cookie based authentification, by passing an additional flag “cookie_auth” set to true in the options array, as the third parameter of the couchClient constructor.

Example : as the previous one, but using cookie based authentification

$client = new CouchClient("http://couchAdmin:secret@my.server.com:5984/","mydb", array("cookie_auth"=>true) );

You can also manually set the session cookie.

Example : manually setting the session cookie :

$client = new CouchClient("http://my.server.com:5984/","mydb");
$client->setSessionCookie("AuthSession=Y291Y2g6NENGNDgzNzY6Gk0NjM-UKxhpX_IyiH-C-9yXY44");

General functions

class PHPOnCouch\CouchClient

PHPOnCouch\CouchClient::__construct($dsn, $dbname, $options = [])
Params string

The complete url to the host. You can enter the credentials directly in it if they don’t required to be encoded.

Params string

The database name to use

Params array

An array of options that can be pass. You can pass the following parameters : username, password, cookie_auth.

You can pass credentials to be encoded correctly. Example:

$client = new CouchClient('http://localhost:5984/','mydb',['username'=>'myuser','password'=>'complicated/*pwd']);

You can also specify to use the cookie authentification by passing the ‘cookie_auth’ key.

Example:

$client = new CouchClient('http://localhost:5984/','mydb',['cookie_auth'=>true]);
$cookie = $client->getSessionCookie();

PHPOnCouch\CouchClient::dsn()
Returns string

The DSN of the server. Database name is not included.

Example :

$client = new CouchClient("http://couch.server.com:5984/","hello");
echo $client->dsn(); // will echo : http://couch.server.com:5984

PHPOnCouch\CouchClient::getSessionCookie()
Returns string

Returns the current session cookie if set.

Example :

$cookie = $client->getSessionCookie();

PHPOnCouch\CouchClient::setSessionCookie($cookie)

This method set the cookie and is chainable.

Params string $cookie

The cookie to set.

Returns CouchClient

Return the current instance.

Example :

$cookie = $client->setSessionCookie("AuthSession=Y291Y2g6NENGNDgzNz")->getSessionCookie();

PHPOnCouch\CouchClient::isValidDatabaseName($name)

Database names on CouchDB have restrictions. Here are the allowed characters:

  • lowercase characters (a-z)

  • digits (0-9)

  • any of the following characters _, $, (, ), +, -, and / are allowed

The name has to start with a lowercase letter (a-z) or an underscore (_).

To test if a given database name is valid, use the static isValidDatabaseName() CouchClient method.

Params string $name

The name to validate.

Returns boolean

True if valid. Otherwise false.

Example :

$my_database = "user311(public)";
if ( CouchClient::isValidDatabaseName($my_database) ) {
    $client = new CouchClient("http://couch.server.com:5984/",$my_database);
} else {
    die("Invalid database name");
}

PHPOnCouch\CouchClient::listDatabases()

The method listDatabases() lists the available databases on the CouchDB server.

Returns array

An array of database names.

Example :

$dbs = $client->listDatabases();
print_r($dbs); // array ('first_database','another_database')

PHPOnCouch\CouchClient::createDatabase()

Create the database according to the name you set when creating couch_client object $client.

Note

If the database already exist, this method will throw an exception.

Example :

$client->createDatabase();

PHPOnCouch\CouchClient::deleteDatabase()

Permanently remove from the server the database according to the name you set when creating couch_client object $client.

Note

If the database does not exist, the method will throw an exception.

Example :

$client->deleteDatabase();

PHPOnCouch\CouchClient::databaseExists()

Test if the database already exist on the server.

Returns boolean

True if it exists. Otherwise false.

Example :

if ( !$client->databaseExists() ) {
    $client->createDatabase();
}

PHPOnCouch\CouchClient::getDatabaseInfos()

Sends back informations about the database. Informations contains the number of documents in the database, the space of the database on disk, the update sequence number, …

Returns array

Returns an arrayf with the database informations.

Example :

print_r($client->getDatabaseInfos());
/*
array("db_name" => "testdb",
      "doc_count" => 2,
      "doc_del_count" => 0,
      "update_seq" => 6,
      "purge_seq" => 0,
      "compact_running" => false,
      "disk_size" => 277707,
      "instance_start_time" => "1246277543362647"
 )
 */

PHPOnCouch\CouchClient::getDatabaseUri()

The method getDatabaseUri() sends back a string giving the HTTP connection URL to the database server.

Example :

echo $client->getDatabaseUri();
/*
http://db.example.com:5984/testdb
*/

PHPOnCouch\CouchClient::getUuids($count = 1)

Sends back an array of universally unique identifiers (that is, big strings that can be used as document ids)

Params int $count

The number of id to returns.

Returns array

An array of identifiers

Example :

print_r($client->getUuids(5));
/*
    array ( 0 => "65a8f6d272b3e5e62ee9de8eacc083a5",
            1 => "e43b04e44233d72b353c1cd8915b886d",
            2 => "7498fb296f19ebc2554a4812f3d9ae12",
            3 => "f3f855a15eb90e9fcdbda5e017b9f2cd",
            4 => "9d9a8214762d06cdf0158d7f6697cac9" )
*/

PHPOnCouch\CouchClient::useDatabase($dbName)

The method useDatabase($dbname) changes the working database on the CouchDB server.

Params string $dbName

The name of the database to use.

Example :

$client = new CouchClient("http://localhost:5984", "db1");
$all_docs_db1 = $client->getAllDocs(); //retrieve all docs of database db1
$client->useDatabase("db2");           //switch to "db2" database
$all_docs_db2 = $client->getAllDocs(); //retrieve all docs of database db2

PHPOnCouch\CouchClient::getMembership()

With the new Cluster infrastructure in CouchDB 2.0, you now have to configure each nodes. To do so, you need to get the information about them. The _membership endpoint allow you to get all the nodes that the current nodes knows and all the nodes that are in the same cluster. The method getMembership() returns an object like this :

{
  "all_nodes": [],
  "cluster_nodes": []
}

PHPOnCouch\CouchClient::getConfig($nodeName[, $section[, $key]])

Warning

The configurations methods are implemented for PHP-on-Couch 2.0 only. Note that the configuration is per-node only.

To configure, you need to use getConfig($nodeName [, $section [, $key ]]). If you don’t know the nodeName, you can use the getMembership() method.

Params string $nodeName

The name of the node to use.

Params string $section

The section value to return.

Params string $key

The section key-value to return.

Examples :

getConfig(“couchdb@localhost”)*

Returns a JSON object with the whole configuration

{
    "attachments":{

    },
    "couchdb":{

    }
}

getConfig(“couchdb@localhost”,”httpd”)

Note

It will return a CouchNotFoundException is the section is not present.

Returns a JSON object that represent the desired section

{
    "allow_jsonp": "false",
    "authentication_handlers": "{couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
    "bind_address": "127.0.0.1",
    "default_handler": "{couch_httpd_db, handle_request}",
    "enable_cors": "false",
    "log_max_chunk_size": "1000000",
    "port": "5984",
    "secure_rewrites": "true",
    "vhost_global_handlers": "_utils, _uuids, _session, _oauth, _users"
}

getConfig(“couchdb@localhost”,”log”,”level”)

Returns either text-plain of JSON value of the section/key.

Note

It will return a CouchNotFoundException is the section or key are not present*.

"debug"

PHPOnCouch\CouchClient::setConfig($nodeName, $section, $key, $value)

Warning

The configurations methods are implemented for PHP-on-Couch 2.0 only. Note that the configuration is per-node only*

The method setConfig($nodeName, $section, $key, $value) let you configure your installation. It can throws CouchNotAuthorizedException or CouchNotFoundException depending on the parameters supplied.

Example :

$val = $client->setConfig("couchdb@localhost","log","level","info");
echo $val;
/*
"debug"
*/

PHPOnCouch\CouchClient::deleteConfig($nodeName, $section, $key)

Warning

The configurations methods are implemented for PHP-on-Couch 2.0 only. Note that the configuration is per-node only

The method deleteConfig($nodeName, $section, $key) let you delete a configuration key from your node. It will returns the JSON value of the parameter before its deletion. Not that the method can throw a CouchNotFoundException or a CouchUnauthorizedException regarding of the section/key and permissions.

Example:

$oldValue = $client->deleteConfig("couchdb@localhost","log","level");
echo $oldValue;
/*
"info"
*/

Changes

CouchDB implements database changes feedback and polling. You’ll find more infos here . For any event in the database, CouchDB increments a sequence counter.

PHPOnCouch\CouchClient::getChanges()

The method getChanges() sends back a CouchDB changes object.

Example :

print_r($client->getChanges());
/*
    stdClass Object
    (
        [results] => Array
            (
                [0] => stdClass Object
                    (
                        [seq] => 'example-last-update-sequence'
                        [id] => 482fa0bed0473fd651239597d1080f03
                        [changes] => Array
                            (
                                [0] => stdClass Object
                                    (
                                        [rev] => 3-58cae2758cea3e82105e1090d81a9e02
                                    )

                            )

                        [deleted] => 1
                    )

                [1] => stdClass Object
                    (
                        [seq] => 'example-last-update-sequence'
                        [id] => 2f3f913f34d60e473fad4334c13a24ed
                        [changes] => Array
                            (
                                [0] => stdClass Object
                                    (
                                        [rev] => 1-4c6114c65e295552ab1019e2b046b10e
                                    )

                            )

                    )

            )

        [last_seq] => 4
    )
*/

Chainable methods to use before getChanges()

The following methods allow a fine grained control on the changes request to issue.

PHPOnCouch\CouchClient::since(string $value)

Retrieve changes that happened after sequence number $value

Params string $value

The minimal sequence number

PHPOnCouch\CouchClient::heartbeat(integer $value)
Params integer $value

Number of milliseconds between each heartbeat line (an ampty line) one logpoll and continuous feeds

PHPOnCouch\CouchClient::feed(string $value, $callback)

Feed type to use. In case of “continuous” feed type, $callback should be set and should be a PHP callable object (so is_callable($callback) should be true)

The callable function or method will receive two arguments : the JSON object decoded as a PHP object, and a cloned CouchClient instance, allowing developers to issue CouchDB queries from inside the callback.

Params string $value

The feed value.

Params callable $callback

The callback function to execute for each document received.

PHPOnCouch\CouchClient::filter(string $value, array $additional_query_options)

Apply the changes filter $value. Add additional headers if any

Params string $value

The filter to use.

Params array $additional_query_options

The additional query options to pass to the filter.

PHPOnCouch\CouchClient::style(string $value)

Changes display style, use “all_docs” to switch to verbose

Params string $value

The style to value to apply

Example :

// fetching changes since sequence 'example-last-update-sequence' using filter "messages/incoming"
$changes = $client->since('example-last-update-sequence')->filter("messages/incoming")->getChanges();

Example - Continuous changes with a callback function

function index_doc($change,$couch) {
    if( $change->deleted == true ) {
        // won't index a deleted file
        return ;
    }
    echo "indexing ".$change->id."\n";
    $doc = $couch->getDoc($change->id);
    unset($doc->_rev);
    $id = $doc->_id;
    unset($doc->_id);
    my_super_fulltext_search_appliance::index($id, $doc);
}

$client->feed('continuous','index_doc')->getChanges();
// will return when index_doc returns false or on socket error

PHPOnCouch\CouchClient::ensureFullCommit()

The method ensureFullCommit() tells couchDB to commit any recent changes to the database file on disk.

Example :

$response = $client->ensureFullCommit();
print_r($response);
/* should print something like :
 stdClass Object
    (
        [ok] => 1,
        [instance_start_time] => "1288186189373361"
    )
*/

Maintenance

Three main maintenance tasks can be performed on a CouchDB database : compaction, view compaction, and view cleanup.

PHPOnCouch\CouchClient::compactDatabase()

CouchDB database file is an append only : during any modification on database documents (add, remove, or update), the modification is recorded at the end of the database file. The compact operation removes old versions of database documents, thus reducing database file size and improving performances. To initiate a compact operation, use the compactDatabase() method.

Example :

// asking the server to start a database compact operation
$response = $client->compactDatabase(); // should return stdClass ( "ok" => true )

PHPOnCouch\CouchClient::compactAllViews()

Just as documents files, view files are also append-only files. To compact all view files of all design documents, use the compactAllViews() method.

Example :

// asking the server to start a view compact operation on all design documents
$response = $client->compactAllViews(); // return nothing

PHPOnCouch\CouchClient::compactViews($id)

To compact only views from a specific design document, use the compactViews( $id ) method.

Params string $id

The id of the design document to compact.

Example :

// asking the server to start a database compact operation on the design document _design/example
$response = $client->compactViews( "example" ); // should return stdClass ( "ok" => true )

PHPOnCouch\CouchClient::cleanupDatabaseViews()

This operation will delete all unused view files. Use the cleanupDatabaseViews() method to initiate a cleanup operation on old view files

Example :

// asking the server to start a database view files cleanup operation
$response = $client->cleanupDatabaseViews(); // should return stdClass ( "ok" => true )