marcoalexpinheiro / php-on-couch Goto Github PK

#IMPORTANT!

For the most updated version of PHP-on-Couch, please use this repository instead : https://github.com/PHP-on-Couch/PHP-on-Couch

This organization is will be more official and I will be maintening it as well.

Thank you all!

##Tests and coverage

##Dev status

##Table of content

• Introduction
• What's new
• Changes
• Installation and testing
• Components and documentation
  • Couch class
  • CouchClient class
    • Database functionnalities
    • Documents functionnalities
    • Views functionnalities
  • CouchDocument class
  • CouchReplicator class
  • CouchAdmin class
• Quick-start guide
• Example
• Feedback

##Introduction

PHP On Couch tries to provide an easy way to work with your CouchDB documents with PHP.

##What's new

Due to the lack of support on the last repository, I forked it and I will make sure it's kept active. Feel free to post any issue or feature request. I'm open for further developments but I don't have a lot of time.

With the new release of 2.0, the master branch will support only this version and the next one.

###Devlopments If you want to get involved, feel free to fork this branch and make a pull request. We can discuss of the new feature together and split the works. Simply create an issue and we will discuss on it.

To access PHP-on-Couch for CouchDB 1.6.1, please visit this link.

##Changes

Since I forked the origin branch, I updated the library a bit. We are now using Namespaces for the whole library. It's cleaner to use it with an autoloader. Please take a look to the updated examples for more details.

####[2.0] #####Added

• CouchClient
  • getMemberShip()
  • getConfig($nodeName[,$section,$key])
  • setConfig($nodeName,$section,$key,$value)
  • deleteConfig($nodeName,$section,$key)
• Composer installation now available

####Updated

• CouchAdmin($client,$options)
• Updated few tests cases

##Installation and testing

Install the library using composer : composer require popojargo/php-on-couch. You can find more detailed informations about installation here

Test instructions to be determined.

##Components and documentation

This library has four main classes and a custom Exception class.

###Couch class This is the most basic of the three classes, and is responsible for the low level dialog between PHP and the CouchDB server. There should be no need of using it directly.

###CouchClient class

This class maps all the actions the application can do on the CouchDB server. Documentation is split in three main topics :

• List databases
• Create and delete a database
• Retrieve database informations
• Test whether a database exists
• Get uuids
• Get databases changes

• Fetching documents
• Storing documents
• Copy a document
• Store attachments
• Delete document attachments
• Get all documents

• Calling a view with query options : key, startkey, endkey, limit, stale, ...

###CouchDocument class

Easing the manipulation of documents, the CouchDocument class uses PHP magic getters and setters. Documentation available here.

###CouchReplicator class

A dedicated class to manage replications over different instances of CouchDB databases. Documentation available here.

###CouchAdmin class

A class to manage users and database/users associations. Documentation available here.

##Quick-start guide

1. Import those classes whenever you need to access CouchDB server :

use PHPOnCouch\Couch, 
    PHPOnCouch\CouchAdmin, 
    PHPOnCouch\CouchClient; 

If you need to use replication features, also use the couchReplicator definition :

    use PHPOnCouch\CouchReplicator;

2. Create a client object. You have to tell it the Data source name (dsn) of your CouchDB server, as well as the name of the database you want to work on. The DSN is the URL of your CouchDB server, for example http://localhost:5984.

    $client = new CouchClient($couchdb_server_dsn, $couchdb_database_name);
   

3. Use it !

    try {
        $client->createDatabase();
    } catch (Exception $e) {
        echo "Unable to create database : ".$e->getMessage();
    }
    
    $doc = new CouchDocument($client);
    $doc->set( array('_id'=>'some_doc_id', 'type'=>'story','title'=>"First story") );
    
    $view = $client->limit(10)->descending(TRUE)->getView('some_design_doc','viewname');
   

##Example

Some code first :

At first, you need to import the main components through their namespace. If you use composer, I suggest you to use their autoload wich is easy to setup. Otherwise, you can use your own autoload function or a basic require with some namespace escaping.

use PHPOnCouch\Couch, //The core of PHP-on-Couch
    PHPOnCouch\CouchAdmin, //The object to handle admins
    PHPOnCouch\CouchClient; //The CouchDB client object

Here's an example for basic operations

// Set a new connector to the CouchDB server
$client = new CouchClient('http://my.couch.server.com:5984', 'my_database');

// document fetching by ID
$doc = $client->getDoc('some_doc_id');
// updating document
$doc->newproperty = array("hello !", "world");
try {
    $client->storeDoc($doc);
} catch (Exception $e) {
    echo "Document storage failed : " . $e->getMessage() . "<BR>\n";
}

Here's a quick example of how to fetch a view

// view fetching, using the view option limit
try {
    $view = $client->limit(100)->getView('orders', 'by-date');
} catch (Exception $e) {
    echo "something weird happened: " . $e->getMessage() . "<BR>\n";
}

Finally, how to use the CouchDocument class.

//using couch_document class :
$doc = new CouchDocument($client);
$doc->set(array('_id' => 'JohnSmith', 'name' => 'Smith', 'firstname' => 'John')); //create a document and store it in the database
echo $doc->name; // should echo "Smith"
$doc->name = "Brown"; // set document property "name" to "Brown" and store the updated document in the database

##Feedback

Don't hesitate to submit feedback, bugs and feature requests ! My contact address is [email protected]