PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Basic concepts

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 ArrayAccessIteratorAggregateCountable
{
    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_key setting was provided to the constructor, or passed to the setDefaultPartitionKey() method, that value will be used for the PartitionKey.

    • 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 71. 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 72. 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";
}

Zend Framework