PHPackages                             nano-php/nano-php - 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. nano-php/nano-php

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

nano-php/nano-php
=================

Minimalistic couchdb driver for PHP >5.3

0.1.1(13y ago)4552MITPHPPHP >=5.3.0

Since Nov 19Pushed 12y ago4 watchersCompare

[ Source](https://github.com/alrik11es/nano-php)[ Packagist](https://packagist.org/packages/nano-php/nano-php)[ Docs](http://github.com/alrik11es/nano-php)[ RSS](/packages/nano-php-nano-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

nano-php
========

[](#nano-php)

v0.1

[![Build Status](https://camo.githubusercontent.com/a389742d66bbeff7dffe607634fa6de891ad9f509d6a809ac3aa267f92e91559/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f616c72696b313165732f6e616e6f2d7068702e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/alrik11es/nano-php)

minimalistic couchdb driver for PHP >5.3 it's intended to be exactly the same as  but in PHP (I'm avoiding the use of callbacks because I think PHP people don't really need to mess with that).

`nano-php` features:

- **minimalistic** - there is only a minimum of abstraction between you and couchdb
- **errors** - errors are proxied directly from couchdb: if you know couchdb you already know `nano-php`

Remember that this is a stable preview version not all options are ready to go.

Things that should work:

- Create DB
- Delete DB
- DB list command
- Use a DB to create a Document
- Inserting a document
- List documents in DB
- Show a view

There's still a lot of work to be done here.

installation
------------

[](#installation)

### Composer way \[HIGHLY RECOMMENDED\]

[](#composer-way-highly-recommended)

1. install [Composer](http://getcomposer.org/)
2. create a file called composer.json in your project folder add {} inside
3. `composer require`
4. `nano-php`
5. select desired version then push intro
6. Include or require autoloader.php in your project
7. Enjoy

### Uncompress way

[](#uncompress-way)

1. Clone or download this repo
2. Copy the src folder where you want or call as you wish.
3. Include or require Nano.php
4. You need the Guzzle library
5. Enjoy

Are any of this installation methods bad? Add an issue if you encounter any problems.

getting started
---------------

[](#getting-started)

to use `nano-php` you need to connect it to your couchdb install, to do that:

```
$nano = new Nano('http://localhost:5984');
```

to create a new database:

```
$nano->db->create('alice');
```

and to use it:

```
$alice = $nano->db->use('alice');
```

in this examples we didn't specify a `result` from the returning value, the absence of a result means *"do this, ignore what happens"*. in `nano-php` the returning value is a stdClass directly from the couchDB JSON result

a simple but complete example is:

```
$nano = new Nano('http://localhost:5984');

// clean up the database we created previously
$nano->db->destroy('alice');

// create a new database
$nano->db->create('alice');

// specify the database we are going to use
$alice = $nano->use('alice');

// and insert a document in it
$rabbit = new stdClass(); // This is the standard empty class could be one of your own classes
$rabbit->crazy = true;
$result = $alice->insert($rabbit, 'rabbit');

if(!isset($result->error)){
  echo 'you have inserted the rabbit.';
  echo $result->body;
}
```

if you run this example(after starting couchdb) you will see:

```
you have inserted the rabbit.
{ ok: true,
  id: 'rabbit',
  rev: '1-6e4cb465d49c0368ac3946506d26335d' }

```

you can also see your document in [futon](http://localhost:5984/_utils).

configuration
-------------

[](#configuration)

configuring nano to use your database server is as simple as:

```
$server = new Nano('http://localhost:5984');
$server->use('foo');
```

to specify further configuration options:

```
```

please check \[request\] for more information on the defaults. they support features like cookie jar, proxies, ssl, etc.

### pool size

[](#pool-size)

a very important configuration parameter if you have a high traffic website and are using nano is setting up the `pool.size`. by default the node.js http agent (client) has a certain size of active connections that can run simultaneously, while others are kept in a queue.

you can increase the size using `request_options` if this is problematic, and refer to the \[request\] documentation and examples for further clarification

database functions
------------------

[](#database-functions)

### $nano->db->create(name);

[](#nano-db-createname)

creates a couchdb database with the given `name`.

```
$result = $nano->db->create('alice');
if (!$result->error) {
  echo ('database alice created!');
}
```

### $nano->db->get(name);

[](#nano-db-getname)

get informations about `name`.

```
$result = $nano->db->get('alice');
if (!$result->error) {
  echo ($result->body);
}
```

### $nano->db->destroy(name);

[](#nano-db-destroyname)

destroys `name`.

```
$nano->db->destroy('alice');
```

even though this examples looks sync it is an async function.

### $nano->db->list();

[](#nano-db-list)

lists all the databases in couchdb

```
$result = $nano->db->list();
```

### $nano->db->compact(name, \[designname\]);

[](#nano-db-compactname-designname)

compacts `name`, if `designname` is specified also compacts its views.

### $nano->db->replicate(source, target, \[opts\]);

[](#nano-db-replicatesource-target-opts)

replicates `source` on `target` with options `opts`. `target`has to exist, add `create_target:true` to `opts` to create it prior to replication.

```
$result = $nano->db->replicate('alice', 'http://admin:password@otherhost.com:5984/alice',
     array("create_target"=>true));
});
```

### $nano->db->changes(name, \[params\])

[](#nano-db-changesname-params)

asks for the changes feed of `name`, `params` contains additions to the query string.

```
$result = nano->db->changes('alice');
```

### $nano->db->follow(name, \[params\], \[callback\]);

[](#nano-db-followname-params-callback)

uses \[follow\] to create a solid changes feed. please consult follow documentation for more information as this is a very complete api on it's own

```
var feed = db.follow({since: "now"});
feed.on('change', function (change) {
  console.log("change: ", change);
});
feed.follow();
process.nextTick(function () {
  db.insert({"bar": "baz"}, "bar");
});
```

### $nano->use(name);

[](#nano-usename)

creates a scope where you operate inside `name`.

```
$alice = $nano->use('alice');
$alice->insert(array("crazy"=>true), 'rabbit');
```

### $nano->db->use(name);

[](#nano-db-usename)

alias for `$nano->use`

### nano.db.scope(name);

[](#nanodbscopename)

alias for `$nano->use`

### $nano->scope(name);

[](#nano-scopename)

alias for `$nano->use`

### $nano->request(opts);

[](#nano-requestopts)

makes a request to couchdb, the available `opts` are:

- `opts.db` – the database name
- `opts.method` – the http method, defaults to `get`
- `opts.path` – the full path of the request, overrides `opts.doc` and `opts.att`
- `opts.doc` – the document name
- `opts.att` – the attachment name
- `opts.content_type` – the content type of the request, default to `json`
- `opts.headers` – additional http headers, overrides existing ones
- `opts.body` – the document or attachment body
- `opts.encoding` – the encoding for attachments

### $nano->relax(opts);

[](#nano-relaxopts)

alias for `$nano->request`

### $nano->dinosaur(opts);

[](#nano-dinosauropts)

alias for `$nano->request`

```
                _
              / '_)  WAT U SAY!
     _.----._/  /
    /          /
  _/  (   | ( |
 /__.-|_|--|_l

```

### $nano->config;

[](#nano-config)

method containing the nano configurations, possible keys are:

- `url` - the couchdb url
- `db` - the database name

document functions
------------------

[](#document-functions)

### $db->insert(doc, \[params\]);

[](#db-insertdoc-params)

inserts `doc` in the database with optional `params`. if params is a string, its assumed as the intended document name. if params is an object, its passed as query string parameters and `doc_name` is checked for defining the document name.

```
$alice = $nano->use('alice');
$alice->insert(array('crazy'=>true), 'rabbit');
```

### $db->destroy(docname, rev);

[](#db-destroydocname-rev)

removes revision `rev` of `docname` from couchdb.

```
alice.destroy('alice', '3-66c01cdf99e84c83a9b3fe65b88db8c0', function(err, body) {
  if (!err)
    console.log(body);
});
```

### db.get(docname, \[params\], \[callback\])

[](#dbgetdocname-params-callback)

gets `docname` from the database with optional query string additions `params`.

```
alice.get('rabbit', { revs_info: true }, function(err, body) {
  if (!err)
    console.log(body);
});
```

### db.head(docname, \[callback\])

[](#dbheaddocname-callback)

same as `get` but lightweight version that returns headers only.

```
alice.head('rabbit', function(err, _, headers) {
  if (!err)
    console.log(headers);
});
```

### db.copy(src\_doc, dest\_doc, opts, \[callback\])

[](#dbcopysrc_doc-dest_doc-opts-callback)

`copy` the contents (and attachments) of a document to a new document, or overwrite an existing target document

```
alice.copy('rabbit', 'rabbit2', { overwrite: true }, function(err, _, headers) {
  if (!err)
    console.log(headers);
});
```

### db.bulk(docs, \[params\], \[callback\])

[](#dbbulkdocs-params-callback)

bulk operations(update/delete/insert) on the database, refer to the [couchdb doc](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API).

### db.list(\[params\], \[callback\])

[](#dblistparams-callback)

list all the docs in the database with optional query string additions `params`.

```
alice.list(function(err, body) {
  if (!err) {
    body.rows.forEach(function(doc) {
      console.log(doc);
    });
  }
});
```

### db.fetch(docnames, \[params\], \[callback\])

[](#dbfetchdocnames-params-callback)

bulk fetch of the database documents, `docnames` are specified as per [couchdb doc](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API). additional query string `params` can be specified, `include_doc` is always set to `true`.

views and design functions
--------------------------

[](#views-and-design-functions)

### db.view(designname, viewname, \[params\], \[callback\])

[](#dbviewdesignname-viewname-params-callback)

calls a view of the specified design with optional query string additions `params`. if you're looking to filter the view results by key(s) pass an array of keys, e.g `{ keys: ['key1', 'key2', 'keyN'] }`, as `params`.

```
alice.view('characters', 'crazy_ones', function(err, body) {
  if (!err) {
    body.rows.forEach(function(doc) {
      console.log(doc.value);
    });
  }
});
```

### db.show(designname, showname, docId, \[params\], \[callback\])

[](#dbshowdesignname-showname-docid-params-callback)

calls a show function of the specified design for the document specified by docId with optional query string additions `params`.

```
alice.show('characters', 'formatDoc', '3621898430' function(err, doc) {
  if (!err) {
    console.log(doc);
  }
});
```

take a look at the [couchdb wiki](http://wiki.apache.org/couchdb/Formatting_with_Show_and_List#Showing_Documents)for possible query paramaters and more information on show functions.

### db.atomic(designname, updatename, docname, \[body\], \[callback\])

[](#dbatomicdesignname-updatename-docname-body-callback)

calls the design's update function with the specified doc in input.

```
db.atomic("update", "inplace", "foobar",
{field: "foo", value: "bar"}, function (error, response) {
  assert.equal(error, undefined, "failed to update");
  assert.equal(response.foo, "bar", "update worked");
});
```

check out the tests for a fully functioning example.

using cookie authentication
---------------------------

[](#using-cookie-authentication)

nano supports making requests using couchdb's [cookie authentication](http://guide.couchdb.org/editions/1/en/security.html#cookies) functionality. there's a [step-by-step guide here](http://mahoney.eu/2012/05/23/couchdb-cookie-authentication-nodejs-nano/), but essentially you just:

```
var nano     = require('nano')('http://localhost:5984')
  , username = 'user'
  , userpass = 'pass'
  , callback = console.log // this would normally be some callback
  , cookies  = {} // store cookies, normally redis or something
  ;

nano.auth(username, userpass, function (err, body, headers) {
  if (err) {
    return callback(err);
  }

  if (headers && headers['set-cookie']) {
    cookies[user] = headers['set-cookie'];
  }

  callback(null, "It worked");
});
```

reusing a cookie:

```
var auth = "some stored cookie"
  , callback = console.log // this would normally be some callback
  , alice = require('nano')(
    { url : 'http://localhost:5984/alice', cookie: 'AuthSession=' + auth });
  ;

alice.insert(doc, function (err, body, headers) {
  if (err) {
    return callback(err);
  }

  // change the cookie if couchdb tells us too
  if (headers && headers['set-cookie']) {
    auth = headers['set-cookie'];
  }

  callback(null, "It worked");
});
```

tutorials & screencasts
---------------------------

[](#tutorials--screencasts)

- [Using Composer with FuelPHP 1.x](http://tomschlick.com/2012/11/01/composer-with-fuelphp/)

roadmap
-------

[](#roadmap)

check [issues](http://github.com/alrik11es/nano-php/issues)

tests
-----

[](#tests)

to run (and configure) the test suite simply:

```
cd nano-php
composer install
phpunit
```

after adding a new test you can run it individually (with verbose output) using:

meta
----

[](#meta)

```
                _
              / _) roar! i'm a vegan!
       .-^^^-/ /
    __/       /
   /__.|_|-|_|     cannes est superb

```

- code: `git clone git://github.com/alrik11es/nano-php.git`
- home:
- bugs:

> > > > > > > Dev

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.1% 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

4928d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/960a0578562aecc8b789ec3175dbcc166faadc0d5baa66e87b19720cd62d9d88?d=identicon)[alrik11es](/maintainers/alrik11es)

---

Top Contributors

[![alrik11es](https://avatars.githubusercontent.com/u/249844?v=4)](https://github.com/alrik11es "alrik11es (52 commits)")[![crodas](https://avatars.githubusercontent.com/u/36463?v=4)](https://github.com/crodas "crodas (1 commits)")

---

Tags

couchdbdriverminimalistic

### Embed Badge

![Health badge](/badges/nano-php-nano-php/health.svg)

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

###  Alternatives

[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[phpfastcache/phpfastcache

PHP Abstract Cache Class - Reduce your database call using cache system. Phpfastcache handles a lot of drivers such as Apc(u), Cassandra, CouchBase, Couchdb, Dynamodb, Firestore, Mongodb, Files, (P)redis, Leveldb, Memcache(d), Ravendb, Ssdb, Sqlite, Wincache, Xcache, Zend Data Cache.

2.4k5.0M130](/packages/phpfastcache-phpfastcache)[php-on-couch/php-on-couch

CouchDB NoSQL database access in PHP

103190.3k3](/packages/php-on-couch-php-on-couch)[datastax/php-driver

DataStax PHP Driver for Apache Cassandra

437521.5k19](/packages/datastax-php-driver)[danielmewes/php-rql

A PHP client driver for the RethinkDB query language (ReQL)

339183.6k14](/packages/danielmewes-php-rql)[mongodb/mongodb-extension

MongoDB driver extension

91919.8k](/packages/mongodb-mongodb-extension)

PHPackages © 2026

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