ibm-watson-data-lab / php-couchdb

PHP Library for PHP 7 and CouchDB 2

PHP CouchDB

⚠️ This project is under early and active development. Comments, experimentation and feedback all gratefully received.

A lightweight library to make it very easy to work with CouchDB from PHP. Uses Guzzle, requires PHP 7+.

Installation

It's recommended to install this library using Composer:

composer require ibm-watson-data-lab/php-couchdb

Usage

Here's the tl;dr of how to begin. For more detailed examples, see the wiki and/or generate the API docs with composer docs

<?php

require "vendor/autoload.php";

// connect to CouchDB (does make a call to check we can connect)
$server = new \PHPCouchDB\Server(["url" => "http://localhost:5984"]);

// get a list of databases; each one is a \PHPCouchDB\Database object
$databases = $server->getAllDbs();

// work with the "test" database (also a \PHPCouchDB\Database object)
$test_db = $server->useDb(["name" => "test", "create_if_not_exists" => true]);

// add a document - you may specify the "id" here if you like
$doc = $test_db->create(["name" => "Alice", "interests" => ["eating", "wondering"]]);

// inspect the document
print_r($doc);

// update the document - a NEW document is returned by this operation, showing the server representation of the document
$doc->friends[] = "Cheshire Cat";
$updated_doc = $doc->update();

// done?  Delete the doc
$updated_doc->delete();

For more examples, conflict handling and really everything else, see more detailed documentation on the wiki.

For Developers

Contributions and issues are all very welcome on this project - and of course we'd love to hear how you're using the library in your own projects.

For information about working with the project locally or opening pull requests, see [[CONTRIBUTING]].

php-couchdb's Issues

Sort out whitespace

The phpcs setup doesn't seem to check tabs vs spaces and the codebase is currently very inconsistent

Objects returned have id/rev instead of _id/_rev

When I create or update an object with the library, it uses id and rev (instead of the actual _id and _rev) which freaks out a CouchDB user like me.

e.g.

(
    [id] => 2eb88e34d027a3f25e9bc26c5b06d615
    [rev] => 2-e605ccbf468cf32c53ffe3b0991996be
    [name] => Alice
    [interests] => Array
        (
            [0] => eating
            [1] => wondering
        )

    [friends] => Array
        (
            [0] => Cheshire Cat
        )

)

it clearly works but by hogging id and rev you are preventing users from using those keys for themselves.

PHP 8 compatibility

I created a PR to support compatibility with PHP 8.1
#14

Add a User-Agent header

So we know what's making the requests, set a user agent. For example, the Java one uses java-cloudant/2.9.0/IBM Java 8/Linux/x64, so aim for library/version/maybe some platform info/OS

database class : editing security settings

i'm going to use CouchDB 2.2.0, Fauxton (/_utils) and the chrome debugger to build functionality into the php-couchdb database class that allows you to set security settings on databases, over the next few days/weeks.

the thing is, i read about how unit tests are required for a merge, and i could use some tips on how to quickly write the proper unit tests, and how to submit the changes..

actually, i'd rather not spend days reading manuals about this and that to become an expert on your particular source-code version control and unit testing code stacks..

can i simply submit the changed php-couchdb code to someone by email or adding them into this issue report even, along with example code that would get put into my https://gitlab.com/seductiveapps/seductiveapps/blob/master/seductiveapps/siteData/reInit.php ?
pretty please? :)

Allow setting DB URL manually

In case there's a proxy or some other URL-altering rule

Show examples with other types of auth

From @bradley-holt: "I'm assuming that this only supports HTTP basic access authentication at the moment. It might be good to mention how someone would authenticate with a CouchDB server."

Make more understandable message for getView

When it is impossible to get data because of exception: "error":"query_parse_error","reason":"Reduce is invalid for map-only views."

Create document makes unnecessary GET request

IF I create a new document with:

$test_db->create(["name" => "Alice", "interests" => ["eating", "wondering"]]);

the library does a

• POST /db/ API call to create the document
• GET /db/id API call to fetch it back

The second API call could be removed without affecting the functionality with something like

$doc['_id'] = $response_data['id'];
$doc['_rev'] = $response_data['rev'];
return $doc;

i.e. return the document body with the _id and _rev appended to it (without having to fetch it from the server).

Doing a quick POST + GET can expose eventual consistency problems in a distributed system i.e. you create a document in one part of the cluster and fail to GET it back before it has propagated to the other side.

Add TravisCI badges to README

Publish API Docs

The API docs are generated with Travis but they need to be put somewhere that people can refer to them without having to generate them locally.