<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.cloud.storageservice">
    <title>StorageService Introduction</title>

    <para>
        The storage service in the Simple Cloud API implements a basic interface for file storage on
        the cloud. The files have no internal structure as far as the service is concerned, and are
        identified by a string key that is analogous to a filepath on a filesystem.
    </para>

    <sect2 id="zend.cloud.storageservice.adapters">
        <title>StorageService Adapters</title>

        <para>
            The interface <classname>Zend_Cloud_StorageService_Adapter</classname> defines methods
            that each concrete storage service adapter must implement.  The following adapters are
            shipped with the Simple Cloud API:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <ulink
                        url="http://aws.amazon.com/s3/"><classname>Zend_Cloud_StorageService_Adapter_S3</classname></ulink>
                </para>
            </listitem>

            <listitem>
                <para>
                    <ulink
                        url="http://msdn.microsoft.com/en-us/library/dd179423.aspx"><classname>Zend_Cloud_StorageService_Adapter_WindowsAzure</classname></ulink>
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Cloud_StorageService_Adapter_FileSystem</classname>
                </para>
            </listitem>
        </itemizedlist>

        <para>
            To create the service object, call the static method
            <methodname>Zend_Cloud_StorageService_Factory::getAdapter()</methodname>, which accepts
            either an array or a <classname>Zend_Config</classname> object.  The key named
            <varname>storage_adapter</varname> should specify the concrete adapter class.
            Adapter-specific keys may also be passed in this configuration parameter.
        </para>

        <example id="zend.cloud.storageservice.factory.example">
            <title>Using the StorageService Factory</title>

            <programlisting language="php"><![CDATA[
$storage = Zend_Cloud_StorageService_Factory::getAdapter(array(
    Zend_Cloud_StorageService_Factory::STORAGE_ADAPTER_KEY => 'Zend_Cloud_StorageService_Adapter_S3',
    Zend_Cloud_StorageService_Adapter_S3::AWS_ACCESS_KEY   => $amazonKey,
    Zend_Cloud_StorageService_Adapter_S3::AWS_SECRET_KEY   => $amazonSecret,
));
]]></programlisting>
        </example>

        <sect3 id="zend.cloud.storageservice.adapters.options">
            <title>StorageService Adapter Options</title>

            <table frame='all' id="zend.cloud.storageservice.options.s3">
                <title>Zend_Cloud_StorageService_Adapter_S3 options</title>

                <tgroup cols="5">
                    <thead>
                        <row>
                            <entry>Option key</entry>
                            <entry>Description</entry>
                            <entry>Used in</entry>
                            <entry>Required</entry>
                            <entry>Default</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>aws_accesskey</entry>
                            <entry>Amazon AWS access key</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>aws_secretkey</entry>
                            <entry>Amazon AWS secret key</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>bucket_name</entry>
                            <entry>The name of the S3 bucket for this item</entry>
                            <entry>
                                Used in the constructor to set the default bucket for the
                                instantiated service. This option can also be specified in any of
                                the item access operations.
                            </entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>bucket_as_domain</entry>
                            <entry>
                                Indicates that the bucket name is part of the domain name
                            </entry>
                            <entry>
                                Used in constructor to set the default behavior for the instantiated
                                service. This option can also be specified in any of the item access
                                operations.
                            </entry>
                            <entry>No</entry>
                            <entry>False</entry>
                        </row>

                        <row>
                            <entry>metadata</entry>
                            <entry>Array of metadata to associate with the item</entry>
                            <entry><methodname>storeItem()</methodname></entry>
                            <entry>No</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>fetch_stream</entry>
                            <entry>
                                Indicates whether the response is stream, and not a string
                                <note>
                                    <para>
                                        See the <classname>Zend_Service_Amazon_S3</classname>
                                        documentation for more about handling streamed responses)
                                    </para>
                                </note>
                            </entry>
                            <entry><methodname>fetchItem()</methodname></entry>
                            <entry>No</entry>
                            <entry>False</entry>
                        </row>

                        <row>
                            <entry>http_adapter</entry>
                            <entry>HTTP adapter to use in all access operations</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry><classname>Zend_Http_Client_Adapter_Socket</classname></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <table frame='all' id="zend.cloud.storageservice.options.azure">
                <title>Zend_Cloud_StorageService_Adapter_WindowsAzure options</title>
                <tgroup cols="5">
                    <thead>
                        <row>
                            <entry>Option key</entry>
                            <entry>Description</entry>
                            <entry>Used in</entry>
                            <entry>Required</entry>
                            <entry>Default</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>storage_accountname</entry>
                            <entry>Windows Azure account name</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>storage_accountkey</entry>
                            <entry>Windows Azure account key</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>storage_container</entry>
                            <entry>Container to use for this storage object</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>storage_host</entry>
                            <entry>Windows Azure access host</entry>
                            <entry>Constructor</entry>
                            <entry>Yes</entry>
                            <entry><varname>blob.core.windows.net</varname></entry>
                        </row>

                        <row>
                            <entry>storage_proxy_host</entry>
                            <entry>Proxy hostname</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>storage_proxy_port</entry>
                            <entry>Proxy port</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry>8080</entry>
                        </row>

                        <row>
                            <entry>storage_proxy_credentials</entry>
                            <entry>Proxy credentials</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry>None</entry>
                        </row>

                        <row>
                            <entry>http_adapter</entry>
                            <entry>HTTP adapter to use in all access operations</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry><classname>Zend_Http_Client_Adapter_Socket</classname></entry>
                        </row>

                        <row>
                            <entry>returntype</entry>
                            <entry>
                                How to return the results.
                                <itemizedlist>
                                    <listitem>
                                        <para>For <methodname>fetchItem()</methodname>:</para>

                                        <variablelist>
                                            <varlistentry>
                                                <term><constant>RETURN_STRING</constant></term>

                                                <listitem><para>
                                                        Return the data as strings.
                                                </para></listitem>
                                            </varlistentry>

                                            <varlistentry>
                                                <term><constant>RETURN_PATH</constant></term>

                                                <listitem>
                                                    <para>
                                                        save data on disk in temp file, return path
                                                        name
                                                    </para>
                                                </listitem>
                                            </varlistentry>

                                            <varlistentry>
                                                <term><constant>RETURN_STREAM</constant></term>

                                                <listitem>
                                                    <para>Default: Return the data as stream</para>
                                                </listitem>
                                            </varlistentry>
                                        </variablelist>
                                    </listitem>

                                    <listitem>
                                        <para>For <methodname>listItems()</methodname>:</para>

                                        <variablelist>
                                            <varlistentry>
                                                <term><constant>RETURN_NAMES</constant></term>

                                                <listitem>
                                                    <para>return the list of item names (default)</para>
                                                </listitem>
                                            </varlistentry>

                                            <varlistentry>
                                                <term><constant>RETURN_LIST</constant></term>

                                                <listitem>
                                                    <para>return the list of WindowsAzure objects</para>
                                                </listitem>
                                            </varlistentry>
                                        </variablelist>
                                    </listitem>
                                </itemizedlist>
                            </entry>
                            <entry>
                                <methodname>fetchItem()</methodname>,
                                <methodname>listItems()</methodname>
                            </entry>
                            <entry>No</entry>
                            <entry>
                                <constant>RETURN_STREAM</constant> for
                                <methodname>fetchItem()</methodname>;
                                <constant>RETURN_NAMES</constant> for
                                <methodname>listItems()</methodname>
                            </entry>
                        </row>

                        <row>
                            <entry>return_path</entry>
                            <entry>
                                Return path. This is the URL that can be used to access the item
                                after it has been uploaded.
                            </entry>
                            <entry><methodname>fetchItem()</methodname></entry>
                            <entry>No</entry>
                            <entry>System tmp directory</entry>
                        </row>

                        <row>
                            <entry>return_openmode</entry>
                            <entry>
                                <methodname>fopen()</methodname> mode used to open the file for
                                saving data
                            </entry>
                            <entry><methodname>fetchItem()</methodname></entry>
                            <entry>No</entry>
                            <entry>'r'</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <table frame='all' id="zend.cloud.storageservice.options.filesystem">
                <title>Zend_Cloud_StorageService_Adapter_Filesystem options</title>

                <tgroup cols="5">
                    <thead>
                        <row>
                            <entry>Option key</entry>
                            <entry>Description</entry>
                            <entry>Used in</entry>
                            <entry>Required</entry>
                            <entry>Default</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>local_directory</entry>
                            <entry>Local directory where the files will be stored</entry>
                            <entry>Constructor</entry>
                            <entry>No</entry>
                            <entry>System tmp directory</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>

    <sect2 id="zend.cloud.storageservice.concepts">
        <title>Basic concepts</title>

        <para>
            Different cloud storage services use their own unique terminology to refer to document
            storage concepts. The SimpleCloud API defines a number of common concepts that are
            shared among all major providers.
        </para>

        <para>
            The storage service identifies files by string keys, which may be URL paths or another
            service-specific identifier. The items can be stored and retrieved using this key. Each
            item can have <emphasis>metadata</emphasis> associated with it. These metadata carry
            service-specific information about the item, such as size, type, permissions, etc. as
            defined in the adapter for that provider.
        </para>
    </sect2>

    <sect2 id="zend.cloud.storageservice.exceptions">
        <title>Exceptions</title>

        <para>
            If some error occurs inside the storage service, a
            <classname>Zend_Cloud_StorageService_Exception</classname> is thrown. If the exception
            was caused by underlying service driver, you can use the
            <methodname>getClientException()</methodname> method to retrieve the original exception.
        </para>

        <para>
            Since different cloud providers implement different sets of services, some adapters do
            not implement certain features. In this case, the
            <classname>Zend_Cloud_OperationNotAvailableException</classname> exception is thrown.
        </para>
    </sect2>

    <sect2 id="zend.cloud.storageservice.store">
        <title>Store an item</title>

        <para>
            <methodname>storeItem()</methodname> method is used to upload or otherwise add files to
            the storage provider.
        </para>

        <example id="zend.cloud.storageservice.store.example">
            <title>Storing an item</title>

            <programlisting language="php"><![CDATA[
$data = file_get_contents('/my/local/dir/picture.jpg');
$returnedData = $storage->storeItem('/my/remote/path/picture.jpg', $data);
]]></programlisting>
        </example>

        <para>
            An optional third parameter describes service-specific options.
        </para>

        <example id="zend.cloud.storageservice.store-options.example">
            <title>Storing an item with options</title>

            <programlisting language="php"><![CDATA[
$data = file_get_contents("/my/local/dir/picture.jpg");

// Use S3 bucket: myBucket
// Make this item publicly readable
$returnedData = $storage->storeItem(
    '/my/remote/path/picture.jpg',
    $data,
    array(
        Zend_Cloud_StorageService_Adapter_S3::BUCKET_NAME => "myBucket",
        Zend_Cloud_StorageService_Adapter_S3::METADATA    => array(
            Zend_Service_Amazon_S3::S3_ACL_HEADER => Zend_Service_Amazon_S3::S3_ACL_PUBLIC_READ,
        )
    )
);
]]></programlisting>
        </example>

        <para>
            For service adapters that support streaming, data can also be a PHP stream (i.e. opened
            file).
        </para>
    </sect2>

    <sect2 id="zend.cloud.storageservice.fetch">
        <title>Fetch an item</title>

        <para>
            The <methodname>fetchItem()</methodname> operation retrieves an item from the storage.
        </para>

        <example id="zend.cloud.storageservice.fetch.example">
            <title>Fetching an item</title>

            <programlisting language="php"><![CDATA[
$returnedData = $storage->fetchItem("/my/remote/path/picture.jpg");
file_put_contents($localFilePath, $returnedData);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.delete">
        <title>Delete an item</title>

        <para>
            The <methodname>deleteItem()</methodname> operation removes an item from the storage
            service.
        </para>

        <example id="zend.cloud.storageservice.delete.example">
            <title>Deleting an item</title>

            <programlisting language="php"><![CDATA[
$storage->deleteItem("/my/remote/path/picture.jpg");
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.copy">
        <title>Copy an item</title>

        <para>
            The <methodname>copyItem()</methodname> operation creates a copy of the item in the
            storage.
        </para>

        <note>
            <para>
                Not all services support copying natively. If this is the case, the adapter will
                simulate the operation, fetching the item and storing it under the target path.
            </para>
        </note>

        <example id="zend.cloud.storageservice.copy.example">
            <title>Copying an item</title>
            <programlisting language="php"><![CDATA[
$storage->copyItem(
    '/my/remote/path/picture.jpg',
    '/anothor/remote/dir/picturecopy.jpg'
);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.move">
        <title>Move an item</title>

        <para>
            The <methodname>moveItem()</methodname> operation moves an item from one key (or
            directory) to another.
        </para>

        <note>
            <para>
                Not all services support moving natively. If this is the case the adapter will
                simulate the operation, fetching the item, storing it under the target path, then
                deleting the original file.
            </para>
        </note>

        <example id="zend.cloud.storageservice.move.example">
            <title>Moving an item</title>
            <programlisting language="php"><![CDATA[
$storage->moveItem(
    '/my/remote/path/picture.jpg',
    '/anothor/remote/dir/newpicture.jpg'
);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.rename">
        <title>Rename an item</title>

        <para>
            The <methodname>renameItem()</methodname> operation changes the item name. For some
            services, this operation may be equivalent to moving to its original directory with a
            new name.
        </para>

        <example id="zend.cloud.storageservice.rename.example">
            <title>Renaming an item</title>

            <programlisting language="php"><![CDATA[
$storage->renameItem('/my/remote/path/picture.jpg', 'newpicture.jpg');
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.list">
        <title>List items</title>

        <para>
            To list the items stored in the specified path, use the
            <methodname>listItems()</methodname> method. The method returns a list of names
            identifying matching remote items.
        </para>

        <example id="zend.cloud.storageservice.list.example">
            <title>List items</title>
            <programlisting language="php"><![CDATA[
$objects = $storage->listItems('/my/remote/path/');
foreach ($objects as $objname) {
    echo "Found: $objname\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.fetch-metadata">
        <title>Fetching metadata</title>

        <para>
            Some services store a set of key-value pairs along with the item as metadata.  Use the
            <methodname>fetchMetadata()</methodname> method to retrieve an item's metadata.
        </para>

        <example id="zend.cloud.storageservice.fetch-metadata.example">
            <title>Fetching metadata</title>

            <programlisting language="php"><![CDATA[
$data = $storage->fetchMetadata('/my/remote/path/picture.jpg');
foreach ($data as $key => $value) {
    echo "Metadata $key: $value\n";
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.store-metadata">
        <title>Store metadata</title>

        <para>
            Depending on the service, metadata can be supplied either when storing the item or with
            a separate request. In the latter case, use <methodname>storeMetadata()</methodname> to
            add or update this metadata.
        </para>

        <example id="zend.cloud.storageservice.store-metadata.example">
            <title>Storing metadata</title>

            <programlisting language="php"><![CDATA[
$data = $storage->storeMetadata('/my/remote/path/picture.jpg', array(
    'type'     => 'JPEG',
    'category' => 'Portrait',
));
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.delete-metadata">
        <title>Delete metadata</title>

        <para>
            The <methodname>deleteMetadata()</methodname> method removes all user-supplied metadata
            from an item.
        </para>

        <note>
            <para>
                Not all services support removing metadata.
            </para>
        </note>

        <example id="zend.cloud.storageservice.delete-metadata.example">
            <title>Deleting metadata</title>

            <programlisting language="php"><![CDATA[
$storage->deleteMetadata("/my/remote/path/picture.jpg");
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.cloud.storageservice.adapter">
        <title>Accessing concrete adapters</title>

        <para>
            Sometimes it is necessary to retrieve the concrete adapter for the service that the
            Storage API is working with. This can be achieved by using the
            <methodname>getAdapter()</methodname> method.
        </para>

        <note>
            <para>
                Accessing the underlying adapter breaks portability among services, so it should be
                reserved for exceptional circumstances only.
            </para>
        </note>

        <example id="zend.cloud.storageservice.adapter.example">
            <title>Using a concrete adapter</title>

            <programlisting language="php"><![CDATA[
// the Simple Cloud Storage API doesn't support "clean bucket" operation
// the concrete adapter can be used to access this feature
$s3 = $storage->getClient();
$s3->cleanBucket("oldBucket");
]]></programlisting>
        </example>
    </sect2>
</sect1>