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:
<?php
/**
* 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);
}
Windows Azure Document Identifiers
Windows Azure technically requires a combination of two fields to uniquely
identify documents: the PartitionKey and
RowKey, and as such, keys are fully qualified by the structure
array(PartitionKey, RowKey) -- which makes them non-portable. In most
situations, the PartitionKey will not differ for documents in a
single collection -- and potentially not even across your entire table instance. As
such, the DocumentService provides several options for specifying keys:
Array keys will always work as expected.
-
If a string key is provided:
If the
default_partition_keysetting was provided to the constructor, or passed to thesetDefaultPartitionKey()method, that value will be used for thePartitionKey.Otherwise, the name of the collection on which you are operating will be used.
The takeaway is that you can utilize string keys if you wish to maximize portability
of your application. Just be aware that your record will contain a few extra fields
to denote the key (PartitionKey, RowKey, and
the previously undiscussed Timestamp) should you ever migrate
your data to another service.
Example 70. Creating a document
<?php
$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
Example 71. Exploring the document data
<?php
$document = $documents->fetchDocument("mydata", $id);
echo "Document ID: " . $document->getID() . "\n";
foreach ($document->getFields() as $key => $value) {
echo "Field $key is $value\n";
}