Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Couch Component Proposal

Proposed Component Name Zend_Couch
Developer Notes
Proposers Matthew Weier O'Phinney
Zend Liaison TBD
Revision 1.0 - 30 September 2008: Initial Draft. (wiki revision: 3)

Table of Contents

1. 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.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • 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

4. Dependencies on Other Framework Components

  • Zend_Exception
  • Zend_Http_Client
  • Zend_Json

5. Theory of 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.

6. Milestones / Tasks

  • Milestone 1: Initial prooposal and prototype code
  • Milestone 2: Working code with all tests
  • Milestone 3: Documentation

7. Class Index

  • Zend_Couch
  • Zend_Couch_Document
  • Zend_Couch_DocumentSet
  • Zend_Couch_Exception
  • Zend_Couch_Result

8. Use Cases


9. Class Skeletons

Please see my github repository for skeletons.



Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Oct 17, 2008

    <p>The overview should perhaps include a brief introduction to CouchDB, and how this might be useful in a ZF setting. Also, there are typos in the use cases (Zend_Coucn instead of Zend_Couch).</p>

    <p>Have you talked anything to Jurrien/norm about Zym_Couch?</p>

    <p>The component looks interesting!</p>

  2. Feb 01, 2009

    <p>Great initiative!</p>

    <p>This would be a good addition to the already excellent ZF.</p>

  3. Feb 01, 2009

    <p>I don't like the "dbCreate", "docSave" method names. While they reflect how things are named in CouchDB I wouldn't stick with them. Why not saveDocument, createDatabase and so on. They are better to read and remember. I mean that's what the Zend_Couch component is for: bringing CouchDB to ZF in a ZF way. Another issue: I would think that Couch would fit into Zend_Db well semantically. While it is not possible to provide the same API for document oriented databases they are still databases.</p>

    1. Feb 01, 2009

      <p>Thanks for the feedback – I'll make a note to update the prototype code and cleanup the names.</p>

      <p>Regarding putting Zend_Couch in the Zend_Db namespace, I respectfully disagree. Zend_Db is aimed at relational databases, and serves as a data abstraction layer for the database adapters under its aegis. CouchDB offers a completely different API, and does not follow any of the paradigms of standard relational databases; it's at heart an arbitrary document store. Putting it under Zend_Db would lead to confusion, since its API would not follow that of any other adapters. As such it either needs its own namespace, or a new namespace for document storage must be created. The latter seems more the ZF way, but there aren't really any other viable document stores available.</p>

      1. Feb 01, 2009

        <p>I totally see the issue with putting it into Zend_Db and I like the idea of creating a seperate namespace for document oriented databases. Nevertheless this is a question with some impact for the future. While the API and usage is completely different to an RDBMS, it is still a database. So we have to decide if for every funky new database type coming up in the future we introduce a new namespace (e.g. object databases getting reborn etc.). But still, if we don't put it in Zend_Db, let's use Zend_DocDb or whatever and not the concrete name of the technology. I think we are too lax in allowing to pollute the top level namespace, Zend_XmlRpc, Zend_Soap and Zend_Rest could easily reside in Zend_Webservice alltogether <ac:emoticon ac:name="smile" /></p>

        1. Feb 02, 2009

          <p>I agree with not putting it as a top-level class/namespace. This component belongs either in a DB or a JS/JSON namespace.</p>

          1. Feb 02, 2009

            <p>It definatly not belongs into JSON, since that can be switched in Couch. The View Engine is Javascript by default but it can be PHP too.</p>

            <p>I think it might work in Zend_Db since that is a toplevel namespace that is empty of classes (seeing the subcomponents as Select, Adapter and Table) and Couch is a database.</p>

        2. Feb 02, 2009

          <p>I like the sound of Zend_DocDb – there <strong>are</strong> other document storage systems starting to appear (the Dojo Foundation's Persevere system is one), and this would be a good start for abstracting the functionality.</p>

          <p>Now, some thoughts on the more general question of "namespace pollution." On the one hand, there are those who want to abstract top-level components, and push specific implementations further down. The problem with this approach is brought up by those on the other side of the fence: it becomes more difficult to quickly and easily find a component when it's more than two levels deep. </p>

          <p>As an example, let's consider Zend_Paginator. Several people felt that this was database specific, and wanted it pushed into Zend_Db. Other parties noted that pagination might be useful for web service or search results – neither of which may have anything to do with databases. As another example, Zend_Layout is basically a specialized view – but if we had pushed it into Zend_View, there were many who claimed they would never find it.</p>

          <p>What's important is that we are fairly consistent in our naming, and that we abstract where it makes sense. Should we go broad and shallow, or narrow and deep? I think there may be a happy medium, but it will take more thought and discussion.</p>

          <p>(All that said, +1 for Zend_DocDb_Adapter_Couch)</p>

          1. Feb 02, 2009

            <p>Zend_DocDb with an adapter for Couch is a good compromise, I guess. I was thinking of writing a wrapper for Oracle Berkeley DB XML, which would also belong in Zend_DocDb. However, I'm not sure that the APIs are compatible enough so that functionality can be abstracted and still be applicable for both Couch and DB XML.</p>

            <p>+1 for Zend_DocDb</p>

            <p>Regarding namespacing:<br />
            Broad and shallow has worked so far, but now we're starting to see a <em>lot</em> of components in the top-level, and I predict the expansion won't slow down just yet. With many classes I find it easier to find what I'm looking for in "narrow and deep" namespacing. This might be off topic, but do you have any thoughts on refactoring namespaces for ZF 2.0?</p>

            1. Feb 02, 2009

              <p>i guess one shouldn't try to streamline both. you loose all the advantages of the adapters.</p>

              <p>I tought it would only be some kind of grouping of Document Databases, not suggesting that their API is exactly the same but that they can be used for almost the same tasks.</p>

              1. Feb 02, 2009

                <p>Let's take a look at Persevere and Berkely DB XML and see if there are enough similarities to warrant an adapter pattern; if not, we can go with a tertiary level namespace only (i.e., Zend_DocDb_Couch vs Zend_DocDb_Adapter_Couch).</p>

  4. Feb 01, 2009

    <p>Another issue came in my mind: I would like to have Zend_Couch::createDocument() instead of directly instanciating Zend_Couch_Document. Yet another level of indirection ...</p>

    1. Feb 01, 2009

      <p>Hello Lars,</p>

      <p>when Matthew made that proposal i cloned his GIT prototype and made a branch that was extended with features, because several other features were missing here in the proposal, for example Views are not included.</p>

      <p>you can see the branches graph here. This was quite some time ago, but i think i renamed the methods.</p>

      <p><a class="external-link" href=""></a></p>

      <p>You can look at the sources there to get some further information about this proposal.</p>

    2. Feb 02, 2009

      <p>I'm not sure I like this idea; using a static method would imply that there is only one couchdb connection in play, and that may not be the case.</p>

      1. Feb 02, 2009

        <p>I didn't meant to advocate a static method, I meant an instance method. So the usecase would look like that:</p>

        <p><code><br />
        $client = new Zend_Couch();<br />
        $document = $client->createDocument();<br />
        ...<br />

        1. Feb 02, 2009

          <p>Ah, okay – the notation you used confused me. The suggestion above makes perfect sense.</p>

  5. Sep 12, 2009

    <p>@Matthew<br />
    Do you know shevron's CouchDB client "Sopha"?
    <a class="external-link" href=""></a></p>

    <p>I think Sopha is better than Phly_Couch...</p>

    <p>(And, What's current status?)</p>

  6. Feb 24, 2010

    <p>Is there any progress for this component? I want to try CouchDB in the near future and was just looking if there is a proposal for it.</p>

    1. Feb 24, 2010

      <p>I've been improving the Phly_Couch gradually in my github repo, including better view support. I'd like to include it in a ZF release, but am trying to determine if this will be part of a larger NoSQL initiative (we have proposals for MongoDB and Cassandra as well), will wait until 2.0, or if we should start sooner.</p>

  7. Mar 18, 2010

    <p>I started using cassandra, i wanted to use it in one of my zf projects, to see what the benefits are compared to mysql ... a "larger nosql initiative", for cassandra, mongo db, couch db and all the other nosql, for zf 2 would be really great, i hope you will be aible to do it and i hope you will get some support from other devs.</p>

    <p>Here is a good article about howto use mongo with zf: <a class="external-link" href=""></a><br />
    here are some benchmarks mysql vs mongo: <a class="external-link" href=""></a><br />
    here is the cassandra discussion: <a class="external-link" href=""></a><br />
    here is the first draft of an early stage cassandra component for zf: <a class="external-link" href=""></a></p>

  8. Feb 07, 2011

    <p>Archiving this proposal, feel free to recover it when you want to work on it again. For more details see <a href="">this email</a>.</p>