repo_zf1/documentation/manual/en/module_specs/Zend_Service_WindowsAzure_Table.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.windowsazure.storage.table">
    <title>Zend_Service_WindowsAzure_Storage_Table</title>

    <para>
        The Table service offers structured storage in the form of tables.
    </para>

    <para>
        Table Storage is offered by Windows Azure as a REST <acronym>API</acronym> which is wrapped
        by the <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class in order to
        provide a native <acronym>PHP</acronym> interface to the storage account.
    </para>

    <para>
        This topic lists some examples of using the
        <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class. Other features are
        available in the download package, as well as a detailed <acronym>API</acronym>
        documentation of those features.
    </para>

    <para>
        Note that development table storage (in the Windows Azure <acronym>SDK</acronym>) does not
        support all features provided by the <acronym>API</acronym>. Therefore, the examples listed
        on this page are to be used on Windows Azure production table storage.
    </para>

    <sect2 id="zend.service.windowsazure.storage.table.api">
        <title>Operations on tables</title>

        <para>
            This topic lists some samples of operations that can be executed on tables.
        </para>

        <sect3 id="zend.service.windowsazure.storage.table.api.create">
            <title>Creating a table</title>

            <para>
                Using the following code, a table can be created on Windows Azure production table
                storage.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.create.example">
                <title>Creating a table</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->createTable('testtable');

echo 'New table name is: ' . $result->Name;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.api.list">
            <title>Listing all tables</title>

            <para>
                Using the following code, a list of all tables in Windows Azure production table
                storage can be queried.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.list.example">
                <title>Listing all tables</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->listTables();
foreach ($result as $table) {
    echo 'Table name is: ' . $table->Name . "\r\n";
}
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.table.entities">
        <title>Operations on entities</title>

        <para>
            Tables store data as collections of entities. Entities are similar to rows. An entity
            has a primary key and a set of properties. A property is a named, typed-value pair,
            similar to a column.
        </para>

        <para>
            The Table service does not enforce any schema for tables, so two entities in the same
            table may have different sets of properties. Developers may choose to enforce a schema
            on the client side. A table may contain any number of entities.
        </para>

        <para>
            <classname>Zend_Service_WindowsAzure_Storage_Table</classname> provides 2 ways of
            working with entities:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Enforced schema
                </para>
            </listitem>

            <listitem>
                <para>
                    No enforced schema
                </para>
            </listitem>
        </itemizedlist>

        <para>
            All examples will make use of the following enforced schema class.
        </para>

        <example id="zend.service.windowsazure.storage.table.entities.schema">
            <title>Enforced schema used in samples</title>

            <programlisting language="php"><![CDATA[
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
    /**
    * @azure Name
    */
    public $Name;

    /**
    * @azure Age Edm.Int64
    */
    public $Age;

    /**
    * @azure Visible Edm.Boolean
    */
    public $Visible = false;
}
]]></programlisting>
        </example>

        <para>
            Note that if no schema class is passed into table storage methods,
            <classname>Zend_Service_WindowsAzure_Storage_Table</classname> automatically works with
            <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname>.
        </para>

        <sect3 id="zend.service.windowsazure.storage.table.entities.enforced">
            <title>Enforced schema entities</title>

            <para>
                To enforce a schema on the client side using the
                <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class, you can create
                a class which inherits
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname>. This class
                provides some basic functionality for the
                <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class to work with a
                client-side schema.
            </para>

            <para>
                Base properties provided by
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        PartitionKey (exposed through <methodname>getPartitionKey()</methodname> and
                        <methodname>setPartitionKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        RowKey (exposed through <methodname>getRowKey()</methodname> and
                        <methodname>setRowKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Timestamp (exposed through <methodname>getTimestamp()</methodname> and
                        <methodname>setTimestamp()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Etag value (exposed through <methodname>getEtag()</methodname> and
                        <methodname>setEtag()</methodname>)
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Here's a sample class inheriting
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname>:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.enforced.schema">
                <title>Sample enforced schema class</title>

                <programlisting language="php"><![CDATA[
class SampleEntity extends Zend_Service_WindowsAzure_Storage_TableEntity
{
    /**
     * @azure Name
     */
    public $Name;

    /**
     * @azure Age Edm.Int64
     */
    public $Age;

    /**
     * @azure Visible Edm.Boolean
     */
    public $Visible = false;
}
]]></programlisting>
            </example>

            <para>
                The <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class will map
                any class inherited from
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> to Windows
                Azure table storage entities with the correct data type and property name. All there
                is to storing a property in Windows Azure is adding a docblock comment to a public
                property or public getter/setter, in the following format:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.enforced.schema-property">
                <title>Enforced property</title>

                <programlisting language="php"><![CDATA[
/**
 * @azure <property name in Windows Azure> <optional property type>
 */
public $<property name in PHP>;
]]></programlisting>
            </example>

            <para>
                Let's see how to define a propety "Age" as an integer on Windows Azure table
                storage:
            </para>

            <example
                id="zend.service.windowsazure.storage.table.entities.enforced.schema-property-sample">
                <title>Sample enforced property</title>

                <programlisting language="php"><![CDATA[
/**
 * @azure Age Edm.Int64
 */
public $Age;
]]></programlisting>
            </example>

            <para>
                Note that a property does not necessarily have to be named the same on Windows Azure
                table storage. The Windows Azure table storage property name can be defined as well
                as the type.
            </para>

            <para>
                The following data types are supported:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Edm.Binary</constant> - An array of bytes up to 64 KB in size.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Boolean</constant> - A boolean value.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.DateTime</constant> - A 64-bit value expressed as Coordinated
                        Universal Time (UTC). The supported DateTime range begins from 12:00
                        midnight, January 1, 1601 A.D. (C.E.), Coordinated Universal Time (UTC). The
                        range ends at December 31st, 9999.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Double</constant> - A 64-bit floating point value.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Guid</constant> - A 128-bit globally unique identifier.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Int32</constant> - A 32-bit integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.Int64</constant> - A 64-bit integer.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>Edm.String</constant> - A UTF-16-encoded value. String values may
                        be up to 64 KB in size.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.dynamic">
            <title>No enforced schema entities (a.k.a. DynamicEntity)</title>

            <para>
                To use the <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class
                without defining a schema, you can make use of the
                <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname> class.
                This class inherits
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> like an
                enforced schema class does, but contains additional logic to make it dynamic and not
                bound to a schema.
            </para>

            <para>
                Base properties provided by
                <classname>Zend_Service_WindowsAzure_Storage_DynamicTableEntity</classname> are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        PartitionKey (exposed through <methodname>getPartitionKey()</methodname> and
                        <methodname>setPartitionKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        RowKey (exposed through <methodname>getRowKey()</methodname> and
                        <methodname>setRowKey()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Timestamp (exposed through <methodname>getTimestamp()</methodname> and
                        <methodname>setTimestamp()</methodname>)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Etag value (exposed through <methodname>getEtag()</methodname> and
                        <methodname>setEtag()</methodname>)
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Other properties can be added on the fly. Their Windows Azure table storage type
                will be determined on-the-fly:
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.dynamic.schema">
                <title>
                    Dynamicaly adding properties to
                    Zend_Service_WindowsAzure_Storage_DynamicTableEntity
                </title>

                <programlisting language="php"><![CDATA[
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
    'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age  = 25;     // Will add property "Age" of type "Edm.Int32"
]]></programlisting>
            </example>

            <para>
                Optionally, a property type can be enforced:
            </para>

            <example
                id="zend.service.windowsazure.storage.table.entities.dynamic.schema-forcedproperties">
                <title>
                    Forcing property types on Zend_Service_WindowsAzure_Storage_DynamicTableEntity
                </title>

                <programlisting language="php"><![CDATA[
$target = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity(
    'partition1', '000001'
);
$target->Name = 'Name'; // Will add property "Name" of type "Edm.String"
$target->Age  = 25;     // Will add property "Age" of type "Edm.Int32"

// Change type of property "Age" to "Edm.Int32":
$target->setAzurePropertyType('Age', 'Edm.Int64');
]]></programlisting>
            </example>

            <para>
                The <classname>Zend_Service_WindowsAzure_Storage_Table</classname> class
                automatically works with
                <classname>Zend_Service_WindowsAzure_Storage_TableEntity</classname> if no specific
                class is passed into Table Storage methods.
            </para>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.api">
            <title>Entities API examples</title>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.insert">
                <title>Inserting an entity</title>

                <para>
                    Using the following code, an entity can be inserted into a table named
                    "testtable". Note that the table has already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.api.entities.insert.example">
                    <title>Inserting an entity</title>

                    <programlisting language="php"><![CDATA[
$entity = new SampleEntity ('partition1', 'row1');
$entity->FullName = "Maarten";
$entity->Age = 25;
$entity->Visible = true;

$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$result = $storageClient->insertEntity('testtable', $entity);

// Check the timestamp and etag of the newly inserted entity
echo 'Timestamp: ' . $result->getTimestamp() . "\n";
echo 'Etag: ' . $result->getEtag() . "\n";
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.retrieve-by-id">
                <title>Retrieving an entity by partition key and row key</title>

                <para>
                    Using the following code, an entity can be retrieved by partition key and row
                    key. Note that the table and entity have already been created before.
                </para>

                <example
                    id="zend.service.windowsazure.storage.table.entities.api.retrieve-by-id.example">
                    <title>Retrieving an entity by partition key and row key</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity= $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.updating">
                <title>Updating an entity</title>

                <para>
                    Using the following code, an entity can be updated. Note that the table and
                    entity have already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.api.entities.updating.example">
                    <title>Updating an entity</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);

$entity->Name = 'New name';
$result = $storageClient->updateEntity('testtable', $entity);
]]></programlisting>
                </example>

                <para>
                    If you want to make sure the entity has not been updated before, you can make
                    sure the <acronym>Etag</acronym> of the entity is checked. If the entity already
                    has had an update, the update will fail to make sure you do not overwrite any
                    newer data.
                </para>

                <example
                    id="zend.service.windowsazure.storage.table.entities.api.updating.example-etag">
                    <title>Updating an entity (with Etag check)</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);

$entity->Name = 'New name';

// last parameter instructs the Etag check:
$result = $storageClient->updateEntity('testtable', $entity, true);
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="zend.service.windowsazure.storage.table.entities.api.delete">
                <title>Deleting an entity</title>

                <para>
                    Using the following code, an entity can be deleted. Note that the table and
                    entity have already been created before.
                </para>

                <example id="zend.service.windowsazure.storage.table.entities.api.delete.example">
                    <title>Deleting an entity</title>

                    <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entity = $storageClient->retrieveEntityById(
    'testtable', 'partition1', 'row1', 'SampleEntity'
);
$result = $storageClient->deleteEntity('testtable', $entity);
]]></programlisting>
                </example>
            </sect4>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.querying">
            <title>Performing queries</title>

            <para>
                Queries in <classname>Zend_Service_WindowsAzure_Storage_Table</classname> table
                storage can be performed in two ways:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        By manually creating a filter condition (involving learning a new query
                        language)
                    </para>
                </listitem>

                <listitem>
                    <para>
                        By using the fluent interface provided by the
                        <classname>Zend_Service_WindowsAzure_Storage_Table</classname>
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Using the following code, a table can be queried using a filter condition. Note
                that the table and entities have already been created before.
            </para>

            <example id="zend.service.windowsazure.storage.table.entities.querying.query-filter">
                <title>Performing queries using a filter condition</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
    'testtable',
    'Name eq \'Maarten\' and PartitionKey eq \'partition1\'',
    'SampleEntity'
);

foreach ($entities as $entity) {
    echo 'Name: ' . $entity->Name . "\n";
}
]]></programlisting>
            </example>

            <para>
                Using the following code, a table can be queried using a fluent interface. Note
                that the table and entities have already been created before.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.entities.query-fluent">
                <title>Performing queries using a fluent interface</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);
$entities = $storageClient->storageClient->retrieveEntities(
    'testtable',
    $storageClient->select()
                  ->from($tableName)
                  ->where('Name eq ?', 'Maarten')
                  ->andWhere('PartitionKey eq ?', 'partition1'),
    'SampleEntity'
);

foreach ($entities as $entity) {
    echo 'Name: ' . $entity->Name . "\n";
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.service.windowsazure.storage.table.entities.batch">
            <title>Batch operations</title>

            <para>
                This topic demonstrates how to use the table entity group transaction features
                provided by Windows Azure table storage. Windows Azure table storage supports batch
                transactions on entities that are in the same table and belong to the same partition
                group. A transaction can include at most 100 entities.
            </para>

            <para>
                The following example uses a batch operation (transaction) to insert a set of
                entities into the "testtable" table. Note that the table has already been created
                before.
            </para>

            <example id="zend.service.windowsazure.storage.table.api.batch">
                <title>Executing a batch operation</title>

                <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

// Start batch
$batch = $storageClient->startBatch();

// Insert entities in batch
$entities = generateEntities();
foreach ($entities as $entity) {
    $storageClient->insertEntity($tableName, $entity);
}

// Commit
$batch->commit();
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.service.windowsazure.storage.table.sessionhandler">
        <title>Table storage session handler</title>

        <para>
            When running a <acronym>PHP</acronym> application on the Windows Azure platform in a
            load-balanced mode (running 2 Web Role instances or more), it is important that
            <acronym>PHP</acronym> session data can be shared between multiple Web Role instances.
            The Windows Azure <acronym>SDK</acronym> for <acronym>PHP</acronym> provides the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> class, which uses
            Windows Azure Table Storage as a session handler for <acronym>PHP</acronym>
            applications.
        </para>

        <para>
            To use the <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session
            handler, it should be registered as the default session handler for your
            <acronym>PHP</acronym> application:
        </para>

        <example id="zend.service.windowsazure.storage.table.api.sessionhandler-register">
            <title>Registering table storage session handler</title>

            <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

$sessionHandler = new Zend_Service_WindowsAzure_SessionHandler(
    $storageClient , 'sessionstable'
);
$sessionHandler->register();
]]></programlisting>
        </example>

        <para>
            The above classname registers the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler and will
            store sessions in a table called "sessionstable".
        </para>

        <para>
            After registration of the
            <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler,
            sessions can be started and used in the same way as a normal <acronym>PHP</acronym>
            session:
        </para>

        <example id="zend.service.windowsazure.storage.table.api.sessionhandler-usage">
            <title>Using table storage session handler</title>

            <programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Table(
    'table.core.windows.net', 'myaccount', 'myauthkey'
);

$sessionHandler = new Zend_Service_WindowsAzure_SessionHandler(
    $storageClient , 'sessionstable'
);
$sessionHandler->register();

session_start();

if (!isset($_SESSION['firstVisit'])) {
    $_SESSION['firstVisit'] = time();
}

// ...
]]></programlisting>
        </example>

        <warning>
            <para>
                The <classname>Zend_Service_WindowsAzure_SessionHandler</classname> session handler
                should be registered before a call to <methodname>session_start()</methodname>
                is made!
            </para>
        </warning>
    </sect2>
</sect1>