The Zend_Cloud_DocumentService_Adapter interface defines methods that each concrete document service adapter implements. The following adapters are shipped with the Simple Cloud API:

To instantiate a document service adapter, use the static method Zend_Cloud_DocumentService_Factory::getAdapter(), which accepts a configuration array or a Zend_Config object. The document_adapter key should specify the concrete adapter class by classname. Adapter-specific keys may also be passed in this configuration parameter.

$adapterClass = 'Zend_Cloud_DocumentService_Adapter_SimpleDb';
$documents = Zend_Cloud_DocumentService_Factory::getAdapter(array(
    Zend_Cloud_DocumentService_Factory::DOCUMENT_ADAPTER_KEY    => $adapterClass,
    Zend_Cloud_DocumentService_Adapter_SimpleDb::AWS_ACCESS_KEY => $amazonKey,
    Zend_Cloud_DocumentService_Adapter_SimpleDb::AWS_SECRET_KEY => $amazonSecret
));

Each document-oriented service and database uses its own terminology and constructs in its API. The SimpleCloud API identifies and abstracts a number of common concepts and operations that are shared among providers.

Document storage consists of a number of collections, which are logical storage units analogous to database tables in the SQL world. Collections contain documents, which are essentially a set of key-value pairs, along with some metadata specific to the storage engine, and are identified by a unique document ID.

Each document has its own structure (set of fields) that does not necessarily have to match the structure of any other document, even in the same collection. In fact, you can change this structure after the document is created.

Documents can be retrieved by ID or by querying a collection.

Documents are represented by the class Zend_Cloud_DocumentService_Document. Note that the document class does not validate the supplied IDs and data, and does not enforce compatibility with each adapter's requirements.

The document fields can be accessed using keys as object properties and as array elements.

The basic interface of Zend_Cloud_DocumentService_Document is as follows:

/**
 * ArrayAccess allows accessing fields by array key:
 *    $doc['fieldname']
 *
 * IteratorAggregate allows iterating over all fields:
 *    foreach ($document as $field => $value) {
 *        echo "$field: $value\n";
 *    }
 *
 * Countable provides a count of all fields:
 *    count($document)
 */
class Zend_Cloud_DocumentService_Document
    implements ArrayAccess, IteratorAggregate, Countable
{
    const KEY_FIELD = '_id';

    /**
     * $fields may be an array or an object implementing ArrayAccess.
     * If no $id is provided, it will look for a field matching KEY_FIELD to
     * use as the identifier.
     */
    public function __construct($fields, $id = null);

    public function setId($id);
    public function getId();
    public function getFields();
    public function getField($name);
    public function setField($name, $value);

    /**
     * These allow overloading, so you may access fields as if they were
     * native properties of the document
     */
    public function __get($name);
    public function __set($name, $value);

    /**
     * Alternately, you can acces fields as if via native getters and
     * setters:
     *     $document->setFoo($value);    // set "Foo" field to value
     *     $value = $document->getFoo(); // get "Foo" field value
    public function __call($name, $args);
}

$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentId");
$document->otherkey = 'some more data';
echo "key 1: " . $document->key1   . "\n"; // object notation
echo "key 2: " . $document['key2'] . "\n"; // array notation

$document = $documents->fetchDocument("mydata", $id);
echo "Document ID: " . $document->getID() . "\n";
foreach ($document->getFields() as $key => $value) {
    echo "Field $key is $value\n";
}

If some error occurs in the document service, Zend_Cloud_DocumentService_Exception is thrown. If the exception was caused by the underlying service driver, you can use the getClientException() method to retrieve the original exception.

Since different cloud providers implement different sets of services, some drivers do not implement certain features. In this case, the Zend_Cloud_OperationNotAvailableException exception is thrown.

A new collection is created using createCollection().

$documents->createCollection("mydata");

If you call createCollection() with a collection name that already exists, the service will do nothing and leave the existing collection untouched.

A collection is deleted by calling deleteCollection().

$documents->deleteCollection("mydata");

Deleting a collection automatically deletes all documents contained in that collection.

Deleting a non-existent collection will have no effect.

A list of existing collections is returned by listCollections(). This method returns an array of all the names of collections belonging to the account you specified when you created the adapter.

$list = $documents->listCollections();
foreach ($list as $collection) {
    echo "My collection: $collection\n";
}

To insert a document, you need to provide a Zend_Cloud_DocumentService_Document object or associative array of data, as well as the collection in which you are inserting it.

Many providers require that you provide a document ID with your document. If using a Zend_Cloud_DocumentService_Document, you can specify this by passing the identifier to the constructor when you instantiate the object. If using an associative array, the key name will be adapter-specific locations; for example, on Azure, the ID is made up of the PartitionKey and RowKey; on Amazon SimpleDB, the ID is the ItemName; you may also specify the key in the _id field to be more portable.

As such, the easiest and most compatible way to specify the key is to use a Document object.

// Instantiating and creating the document
$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");

// inserting into the "mydata" collection
$documents->insertDocument("mydata", $document);

Replacing a document means removing all document data associated with a particular document key and substituting it with a new set of data. Unlike updating, this operation does not merge old and new data but replaces the document as a whole. The replace operation, like insertDocument(), accepts a Zend_Cloud_DocumentService_Document document or an array of key-value pairs that specify names and values of the new fields, and the collection in which the document exists.

$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");

// Update the document as found in the "mydata" collection
$documents->replaceDocument("mydata", $document);

$docment->key4 = '4th value';

// Update the document as found in the "mydata" collection
$documents->replaceDocument("mydata", $document);

Updating a document changes the key/value pairs in an existing document. This operation does not share the replace semantics; the values of the keys that are not specified in the data set will not be changed. You must provide both a document key and data, either via a Zend_Cloud_DocumentService_Document document or an array, to this method. If the key is null and a document object is provided, the document key is used.

// update one field
$documents->updateDocument("mydata", "DocumentID", array("key2" => "new value"));

// or with document; this could be a document already retrieved from the service
$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");
$documents->updateDocument("mydata", null, $document);

// copy document to another ID
$documents->updateDocument("mydata", "AnotherDocumentID", $document);

Amazon SimpleDB supports multi-value fields, so data updates will be merged with the old key value instead of replacing them. Option merge should contain an array of field names to be merged. The array should be key/value pairs, with the key corresponding to the field key, and the value a boolean value indicating merge status (boolean true would merge; false would not). Any keys not specified in the merge option will be replaced instead of merged.

// key2 is overwritten, key3 is merged
$documents->updateDocument('mydata', 'DocumentID',
    array('key2' => 'new value', 'key3' => 'additional value'),
    array('merge' => array('key3' => true))
);

A document can be deleted by passing its key to deleteDocument(). Deleting a non-existant document has no effect.

$documents->deleteDocument("collectionName", "DocumentID");

You can fetch a specific document by specifying its key. fetchDocument() returns one instance of Zend_Cloud_DocumentService_Document.

$document = $service->fetchDocument('collectionName', 'DocumentID');
echo "Document ID: " . var_export($document->getID(), 1) . "\n";
foreach ($document->getFields() as $key => $value) {
    echo "Field $key is $value\n";
}

To find documents in the collection that meet some criteria, use the query()method. This method accepts either a string which is an adapter-dependent query and is passed as-is to the concrete adapter, or a structured query object instance of Zend_Cloud_DocumentService_Query. The return is a Zend_Cloud_DocumentService_DocumentSet, containing instances of Zend_Cloud_DocumentService_Document that satisfy the query. The DocumentSet object is iterable and countable.

$docs = $documents->query(
    "collectionName",
    "RowKey eq 'rowkey2' or RowKey eq 'rowkey2'"
);

foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

If using a structured query object, typically, you will retrieve it using the select() method. This ensures that the query object is specific to your adapter, which will ensure that it is assembled into a syntax your adapter understands.

$query = $service->select();
$query->from('collectionName')
      ->where('year > ?', array(1945))
      ->limit(3);
$docs = $documents->query('collectionName', $query);

foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

Zend_Cloud_DocumentService_Query classes do not limit which query clauses can be used, but the clause must be supported by the underlying concrete adapter. Currently supported clauses include:

For the user's convenience, the select() method instantiates a query object specific to the adapter, and sets the SELECT clause for it.

$query = $documents->select()
                   ->from('collectionName')
                   ->where('year > ?', array(1945))
                   ->limit(3);
$docs = $documents->query('collectionName', $query);
foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

Sometimes it is necessary to retrieve the concrete adapter for the service that the Document API is working with. This can be achieved by using the getAdapter() method.

// Since SimpleCloud Document API doesn't support batch upload, use concrete adapter
$amazonSdb = $documents->getAdapter();
$amazonSdb->batchPutAttributes($items, 'collectionName');