View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Couch
{zone-data}

{zone-data:proposer-list}
[~matthew]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 30 September 2008: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Couch is intended to be a wrapper around the CouchDB REST API. It will provide methods for all API methods, utilizing Zend_Http_Client for communication with the CouchDB server, and Zend_Json for parsing and creating payloads.
{zone-data}

{zone-data:references}
* [CouchDB site|http://couchdb.org/]
* [Phly_Couch implementation|http://github.com/weierophinney/phly/tree/master/Phly_Couch]
{zone-data}

{zone-data:requirements}
* This component *MUST* expose the entire CouchDB API, including:
** Server metadata queries
** Database manipulation: querying metadata, adding and dropping databases
** Document manipulation: saving, retrieving, and deleting documents, including bulk updates/inserts
** View manipulation: creating and querying views, including ad hoc views
* This component *MUST* provide objects for individual documents as well as document sets
** Document objects *MUST* allow arbitrary fields
** Document objects *MUST* provide accessors for document IDs and revisions
** Document Sets *MUST* be iterable
** Document Sets *MUST* be countable
** Document Sets *MUST* allow adding and removing documents
** Document Sets *MUST* allow retrieving documents by ID
* This component *MUST* provide a Result object for API methods that do not return documents or document sets
** The Result object *MUST* provide access to the response
** The Result object *MUST* provide access to any JSON data returned in the response
*** The Result object *SHOULD* provide access to any JSON data returned in the response via overloading
{zone-data}

{zone-data:dependencies}
* Zend_Exception
* Zend_Http_Client
* Zend_Json
{zone-data}

{zone-data:operation}
Users will instantiate Zend_Couch objects, providing connection information, but using sane defaults if none is provided. A default HTTP client may be set statically, attached individually to Zend_Couch instances, or an HTTP client will be instantiated at first request. Connection information may also be provided after instantiation by either calling individual mutators or using the setOptions() or setConfig() methods.

Once the object is instantiated, the user may start communicating with the CouchDB server via API methods. The Server and Database API methods either do not require arguments, or require simple string arguments; in all such cases, these methods will throw an exception on failure, or return a Result object on success. The user may then query the result object for details of the transaction.

To add a document to the database, the developer may either create an associative array of fields representing the document, or, more preferable, use Zend_Couch_Document to do so. The latter will have methods for specifying the document ID and revision, if available, and use overloading to allow specifying arbitrary document fields. The document is then passed to the docSave() method to save it to the database. When using the docBulkSave() method, the developer would attach one or more documents to a Zend_Couch_DocumentSet -- or group them in an array.

When retrieving a single document, a Zend_Couch_Document will be returned.

When retrieving all documents or a subset of documents via a view or query, a Zend_Couch_DocumentSet will be returned. The developer may then iterate over the set.
{zone-data}

{zone-data:milestones}
* Milestone 1: Initial prooposal and prototype code
* Milestone 2: Working code with all tests
* Milestone 3: Documentation
{zone-data}

{zone-data:class-list}
* Zend_Couch
* Zend_Couch_Document
* Zend_Couch_DocumentSet
* Zend_Couch_Exception
* Zend_Couch_Result
{zone-data}

{zone-data:use-cases}
||UC-01||
{code:php}
$couch = new Zend_Couch();

// Get server information
$result = $couch->serverInfo();
echo $result->version;

// Get list of all databases
$result = $couch->allDbs();
var_export($result->toArray());
{code}

||UC-02||
{code:php}
$couch = new Zend_Couch();

try {
$result = $couch->dbCreate('wiki');
} catch (Zend_Couch_Exception $e) {
die('Could not create database');
}

try {
$result = $couch->dbDrop('wiki');
} catch (Zend_Couch_Exception $e) {
die('Could not drop database');
}

$result = $couch->dbInfo('wiki');
echo<<<EOT
Document count: {$result->doc_count}
Database size: {$result->disk_size}
EOT;
{code}

||UC-03||
{code:php}
$couch = new Zend_Coucn('wiki');
$doc = $couch->docOpen('WelcomePage');
foreach ($doc->toArray() as $field => $value) {
echo "$field: " . var_export($value, 1) . "\n";
}
{code}

||UC-04||
{code:php}
$couch = new Zend_Coucn('wiki');
$docs = $couch->allDocs();
foreach ($docs as $document) {
echo $document->getId() . "\n";
}
{code}

||UC-05||
{code:php}
$couch = new Zend_Coucn('wiki');
$document = new Zend_Couch_Document();
$document->id = "NewPage";
$document->title = "New Page";
$document->content = "This is a new wiki page!"
$document->created = date('Y-m-d H:i:s');
$document->tags = array('wiki', 'system');
$couch->docSave($document);
{code}
{zone-data}

{zone-data:skeletons}
Please see my [github repository|http://github.com/weierophinney/phly/tree/master/Phly_Couch] for skeletons.
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>