PHPackages                             yay-couch/couch - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. yay-couch/couch

AbandonedArchivedLibrary[Database & ORM](/categories/database)

yay-couch/couch
===============

CouchDB Wrapper for PHP.

2311PHP

Since Feb 4Pushed 9y ago1 watchersCompare

[ Source](https://github.com/yay-couch/couch-php)[ Packagist](https://packagist.org/packages/yay-couch/couch)[ RSS](/packages/yay-couch-couch/feed)WikiDiscussions master Synced 2w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Couch
-----

[](#couch)

Couch is a great library that makes all interactions with your CouchDB server providing a lot of tools for that.

Before beginning;

- Set your autoloader properly or use composer
- Use PHP >= 5.4 (cos it uses traits)
- Handle errors with try/catch blocks
- On README, `dump` means `var_dump`

Notice: See CouchDB's official documents before using this library.

In a Nutshell
-------------

[](#in-a-nutshell)

```
// create a fresh document
$doc = new Couch\Document($db);
$doc->name = 'The Doc!';
$doc->save();

// append an attachment to the same document above
$doc->setAttachment(new Couch\DocumentAttachment($doc, './file.txt'));
$doc->save();
```

Autoload
--------

[](#autoload)

```
// composer
{"require": {"yay-couch/couch": "dev-master"}}

// manual
$autoload = include('./vendor/yay-couch/couch/Couch/Autoload.php');
$autoload->register();
```

Configuration
-------------

[](#configuration)

Configuration is optional but you can provide all these options;

```
/** client **/
// default=localhost
$config['host'] = 'couchdb_host';
// default=5984
$config['port'] = 1234;
// default=NULL
$config['username'] = 'couchdb_user';
// default=NULL
$config['password'] = '************';

/** agent **/
// default=5 (used in sock & curl)
$config['timeout'] = 10;
// default=1 (used in sock)
$config['blocking'] = 0;
```

Objects
-------

[](#objects)

### Couch Object

[](#couch-object)

```
// init couch object
$couch = new Couch\Couch();
$couch->setConfig($config);
// or
$couch = new Couch\Couch(null, $config); // uses sock as http agent
$couch = new Couch\Couch(Couch\Couch::HTTP_AGENT_CURL);
$couch = new Couch\Couch(Couch\Couch::HTTP_AGENT_CURL, $config);
```

### Client Object

[](#client-object)

```
// used in Server and Database objects
$client = new Couch\Client($couch);
```

If you need any direct request for any reason, you can use the methods below.

```
// direct request
$data = $client->request('GET /',
   $uriParams=['group' => true], $body=null, $headers=[])->getData();

// args
$uri       = '/';
$uriParams = ['param_name' => 'param_value'];
$headers   = ['X-Foo' => 'The foo!'];
$body      = null; // array or string etc

// shortcut methods that handle HEAD, GET, POST, PUT, COPY, DELETE
$client->head($uri, $uriParams, $headers);
$client->get($uri, $uriParams, $headers);
$client->copy($uri, $uriParams, $headers);
$client->delete($uri, $uriParams, $headers);
// with body
$client->put($uri, $uriParams, $body, $headers);
$client->post($uri, $uriParams, $body, $headers);

// after request operations
$request  = $client->getRequest();
$response = $client->getResponse();
```

### Server Object

[](#server-object)

```
$server = new Couch\Server($client);

// methods
dump $server->ping();
dump $server->info();
dump $server->version();
dump $server->getActiveTasks();
dump $server->getAllDatabases();
dump $server->getDatabaseUpdates();
dump $server->getLogs();
dump $server->replicate(['source' => 'foo', 'target' => 'foo2', 'create_target' => true]);
dump $server->restart();
dump $server->getStats();
dump $server->getStats('/couchdb/request_time');
dump $server->getUuid(3);
dump $server->getConfig();
dump $server->getConfig('couchdb');
dump $server->getConfig('couchdb', 'uuid');
dump $server->setConfig('couchdb', 'foo', 'the foo!');
dump $server->removeConfig('couchdb', 'foo');
```

### Database Object

[](#database-object)

```
$db = new Couch\Database($client, 'foo');

// db methods
dump $db->ping();
dump $db->info();
dump $db->create();
dump $db->remove();
dump $db->replicate('foo2');
dump $db->getChanges();
dump $db->getChanges(null, ['abc']);
dump $db->compact();
dump $db->ensureFullCommit();
dump $db->viewCleanup();
dump $db->getSecurity();
dump $db->setSecurity(['names' => ['superuser'], 'roles' => ['admins']],
                      ['names' => ['user1', 'user2'], 'roles' => ['developers']]);

dump $db->getRevisionLimit();
dump $db->setRevisionLimit(1000);

/** tmp view method  */
$db->viewTemp('function(doc){ if(doc.name){ emit(doc.name, null); }}');
$db->viewTemp('function(doc){ if(doc.name){ emit(doc.name, null); }}', $reduce='_count');

/** document methods  */

$db->purge('test_3', ['4-abc']);
$db->getMissingRevisions('test_3', ['3-abc', '3-abd']);
$db->getMissingRevisionsDiff('abc', ['4-abc']);

// get a document
dump $db->getDocument('abc');
// get all documents
dump $db->getDocumentAll();
// get all documents by keys
dump $db->getDocumentAll($query=null, ['abc','abd']);

// create a document
$doc = new Couch\Document();
$doc->test = 'the test 20';
// param as Couch\Document
dump $db->createDocument($doc);
// param as array
dump $db->createDocument(['test' => 'test 30']);

// update a document
$doc = new Couch\Document();
$doc->_id = 'abc';
$doc->_rev = '3-abc';
// param as Couch\Document
dump $db->updateDocument($doc);
// param as array
dump $db->updateDocument([
   ['_id'  => 'abc',
    '_rev' => '1-abc',
    'test' => 'test 2 (update)']
]);

// delete a document
$doc = new Couch\Document(null, [
   '_id'  => 'abc',
   '_rev' => '2-abc',
]);
dump $db->deleteDocument($doc);

/** multiple CRUD */

$docs = [];
// all accepted, just fill the doc data
$docs[] = [/* doc data id etc (and rev for updade/delete) */];
$docs[] = new Couch\Document(null, [/* doc data id etc (and rev for updade/delete) */]);
$doc = new Couch\Document(); $doc->foo = ...
$docs[] = $doc;
$doc = new stdClass;         $doc->foo = ...
$docs[] = $doc;

// multiple create
dump $db->createDocumentAll($docs);
// multiple update
dump $db->updateDocumentAll($docs);
// multiple delete
dump $db->deleteDocumentAll($docs);
```

### Document Object

[](#document-object)

```
$doc = new Couch\Document($db);
// set props (so data)
$doc->_id = 'abc';
$doc->_rev = '2-abc';

// checker methods
dump $doc->ping();
dump $doc->isExists();
dump $doc->isNotModified();

// CRUD methods
dump $doc->find();
dump $doc->save(); // create or update
dump $doc->remove();

// copies
dump $doc->copy('test_copy3');
dump $doc->copyFrom('test_copy3_1');
dump $doc->copyTo('test_copy3_1', '1-abc');

// delete
dump $doc->remove();

// find revisions
dump $doc->findRevisions();
dump $doc->findRevisionsExtended();

// find attachments
dump $doc->findAttachments();
dump $doc->findAttachments(true, ['2-abc']);

// add attachments
$doc->_attachments = [['file' => './attc1.txt']];
$doc->_attachments = [['file' => './attc1.txt', 'file_name' => 'attc1']];
// or
$doc->setAttachment(['file' => './attc1.txt', 'file_name' => 'attc1']);
dump $doc->save();

// to json
dump json_encode($doc);
```

### DocumentAttachment Object

[](#documentattachment-object)

```
$attc = new Couch\DocumentAttachment($doc);

// ping attachment
dump $attc->ping();

// find an attachment
$attc->fileName = 'attc_1';
dump $attc->find();

// find an attachment by digest
$attc->fileName = 'attc_1';
$attc->digest   = 'U1p5BLvdnOZVRyR6YrXBoQ==';
dump $attc->find();

// add an attachment to document
$attc->file     = 'attc.txt';
$attc->fileName = 'attc_2';
dump $attc->save();

// remove an attachment from document
$attc->fileName = 'attc_2';
dump $attc->remove();

// to json
dump $attc->toJson();
dump json_encode($attc);
```

### DocumentDesign Object

[](#documentdesign-object)

```
// @todo
```

Uuid
----

[](#uuid)

```
// create uuid
$uuid = new Couch\Uuid('docid'); // set given value
$uuid = new Couch\Uuid(true);    // auto-generate randomly using mcrypt
$uuid = new Couch\Uuid($server); // triggers $server->getUuid() method

// also setValue & getValue methods available
$uuid = new Couch\Uuid();
$uuid->setValue(...);

// print
print $uuid;

// generate method
$uuidValue = Couch\Uuid::generate(
   $method=Couch\Uuid::METHOD_RANDOM, $algo=Couch\Uuid::HASH_ALGO_MD5);

// available methods
METHOD_RANDOM // default
METHOD_TIMESTAMP
METHOD_TIMESTAMP_HEXED

// available algos (also you can provide any valid "hash algo")
HASH_ALGO_MD5 // default
HASH_ALGO_SHA1
HASH_ALGO_CRC32B
```

Query
-----

[](#query)

```
// init query with db
$query = new Couch\Query($db);
// or
$query->setDatabase($db);

// add params
$query->set('conflicts', true)
   ->set('stale', 'ok')
   ->skip(1)
   ->limit(2)
;

// get as string
dump $query; // print
dump $query->toString();

// actually run is only to get documents with given query
dump $query->run();
// as same as
dump $db->getDocumentAll($query);
```

Request / Response
------------------

[](#request--response)

```
// after any http stream (server ping, database ping, document save etc)

// ie.
$client->request('GET /');

// get raw stuffs
dump $client->getRequest()->toString();
dump $client->getResponse()->toString();

/*
GET / HTTP/1.0
Host: localhost:5984
Connection: close
Accept: application/json
Content-Type: application/json
User-Agent: Couch/v1.0.4 (+http://github.com/yay-couch/couch-php)

HTTP/1.0 200 OK
Server: CouchDB/1.5.0 (Erlang OTP/R16B03)
Date: Sun, 01 Nov 2015 18:04:42 GMT
Content-Type: application/json
Content-Length: 127
Cache-Control: must-revalidate

{"couchdb":"Welcome","uuid":"5a660f4695a5fa9ab2cd22722bc01e96", ...
*/

// get response body
dump $client->getResponse()->getBody();

// get response data
dump $client->getResponse()->getData();
dump $client->getResponse()->getData('vendor');
```

Error Handling
--------------

[](#error-handling)

Couch will not throw any server response error, such as `409 Conflict` etc. It only throws library-related errors ie. "timeout" or wrong usages of the library (ie. when `_id` is required for some action but you did not provide it).

```
// create issue
$doc = new Couch\Document($db);
$doc->_id = 'an_existing_docid';

// no error will be thrown
$doc->save();

// but could be so
if (201 != $client->getResponse()->getStatusCode()) {
   print 'nö!';
   // or print response error data
   $data = $client->getResponse()->getData();
   print $data['error'];
   print $data['reason'];
}

// this will throw error ie. timed out
$db = new Couch\Database(
       new Couch\Client(
         new Couch\Couch(null, ['timeout' => 0])), 'foo2');

try {
   $db->ping();
} catch (Couch\Http\Exception $e) {
   print $e->getMessage();
}
```

###  Health Score

22

—

LowBetter than 21% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1508306?v=4)[Kerem Güneş](/maintainers/krmgns)[@krmgns](https://github.com/krmgns)

---

Top Contributors

[![krmgns](https://avatars.githubusercontent.com/u/1508306?v=4)](https://github.com/krmgns "krmgns (493 commits)")

### Embed Badge

![Health badge](/badges/yay-couch-couch/health.svg)

```
[![Health](https://phpackages.com/badges/yay-couch-couch/health.svg)](https://phpackages.com/packages/yay-couch-couch)
```

###  Alternatives

[jdorn/sql-formatter

a PHP SQL highlighting library

3.8k117.8M121](/packages/jdorn-sql-formatter)[backup-manager/backup-manager

A framework agnostic database backup manager with user-definable procedures and support for S3, Dropbox, FTP, SFTP, and more with drivers for popular frameworks.

1.7k1.6M11](/packages/backup-manager-backup-manager)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M88](/packages/propel-propel1)[insolita/yii2-migration-generator

Set of gii tools for generating files for migration by schema of table , phpdoc or table data

108508.0k5](/packages/insolita-yii2-migration-generator)[xpdo/xpdo

A PDO-based Object/Relational Bridge Library

7088.4k4](/packages/xpdo-xpdo)[voku/session2db

A PHP library acting as a wrapper for PHP's default session handling functions which stores data in a MySQL database, providing both better performance and better security and protection against session fixation and session hijacking.

3220.0k](/packages/voku-session2db)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)