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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.nirvanix">
    <title>Zend_Service_Nirvanix</title>

    <sect2 id="zend.service.nirvanix.introduction">
        <title>Introduction</title>

        <para>
            Nirvanix provides an Internet Media File System (IMFS), an
            Internet storage service that allows applications to upload, store and
            organize files and subsequently access them using a standard Web
            Services interface. An IMFS is distributed clustered file system,
            accessed over the Internet, and optimized for dealing with media files
            (audio, video, etc). The goal of an IMFS is to provide massive
            scalability to deal with the challenges of media storage growth, with
            guaranteed access and availability regardless of time and location.
            Finally, an IMFS gives applications the ability to access data
            securely, without the large fixed costs associated with acquiring and
            maintaining physical storage assets.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.registering">
        <title>Registering with Nirvanix</title>

        <para>
            Before you can get started with <classname>Zend_Service_Nirvanix</classname>, you must
            first register for an account. Please see the
            <ulink url="http://www.nirvanix.com/gettingStarted.aspx">Getting Started</ulink>
            page on the Nirvanix website for more information.
        </para>

        <para>
            After registering, you will receive a Username, Password, and Application Key.
            All three are required to use <classname>Zend_Service_Nirvanix</classname>.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.apiDocumentation">
        <title>API Documentation</title>

        <para>
            Access to the Nirvanix IMFS is available through both <acronym>SOAP</acronym> and a
            faster REST service. <classname>Zend_Service_Nirvanix</classname> provides a
            relatively thin <acronym>PHP</acronym> 5 wrapper around the REST service.
        </para>

        <para>
            <classname>Zend_Service_Nirvanix</classname> aims to make using the Nirvanix REST
            service easier but understanding the service itself is still essential to be successful
            with Nirvanix.
        </para>

        <para>
            The <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix
            <acronym>API</acronym> Documentation</ulink> provides an overview as well as detailed
            information using the service. Please familiarize yourself with this document and refer
            back to it as you use <classname>Zend_Service_Nirvanix</classname>.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.features">
        <title>Features</title>

        <para>
            Nirvanix's REST service can be used effectively with <acronym>PHP</acronym> using the
            <ulink url="http://www.php.net/simplexml">SimpleXML</ulink>
            extension and <classname>Zend_Http_Client</classname> alone. However, using it this way
            is somewhat inconvenient due to repetitive operations like passing the
            session token on every request and repeatedly checking the response body for
            error codes.
        </para>

        <para>
            <classname>Zend_Service_Nirvanix</classname> provides the following functionality:

            <itemizedlist>
                <listitem>
                    <para>
                        A single point for configuring your Nirvanix authentication
                        credentials that can be used across the Nirvanix namespaces.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        A proxy object that is more convenient to use than an
                        <acronym>HTTP</acronym> client alone, mostly removing the need to manually
                        construct <acronym>HTTP</acronym> POST requests to access the REST service.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        A response wrapper that parses each response body and throws an
                        exception if an error occurred, alleviating the need to repeatedly
                        check the success of many commands.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Additional convenience methods for some of the more common operations.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.storing-your-first">
        <title>Getting Started</title>

        <para>
            Once you have registered with Nirvanix, you're ready to store your first
            file on the IMFS. The most common operations that you will need to do
            on the IMFS are creating a new file, downloading an existing file, and
            deleting a file. <classname>Zend_Service_Nirvanix</classname> provides convenience
            methods for these three operations.
        </para>

        <programlisting language="php"><![CDATA[
$auth = array('username' => 'your-username',
              'password' => 'your-password',
              'appKey'   => 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix->getService('IMFS');

$imfs->putContents('/foo.txt', 'contents to store');

echo $imfs->getContents('/foo.txt');

$imfs->unlink('/foo.txt');
]]></programlisting>

        <para>
            The first step to using <classname>Zend_Service_Nirvanix</classname> is always
            to authenticate against the service. This is done by passing your
            credentials to the <classname>Zend_Service_Nirvanix</classname> constructor
            above. The associative array is passed directly to Nirvanix as POST
            parameters.
        </para>

        <para>
            Nirvanix divides its web services into <ulink
                url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999879">namespaces</ulink>.
            Each namespace encapsulates a group of related operations. After getting
            an instance of <classname>Zend_Service_Nirvanix</classname>, call the
            <methodname>getService()</methodname> method to create a proxy for the namespace
            you want to use. Above, a proxy for the <constant>IMFS</constant> namespace is created.
        </para>

        <para>
            After you have a proxy for the namespace you want to use, call methods on it. The
            proxy will allow you to use any command available on the REST <acronym>API</acronym>.
            The proxy may also make convenience methods available, which wrap web service
            commands. The example above shows using the IMFS convenience methods to create a
            new file, retrieve and display that file, and finally delete the file.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.understanding-proxy">
        <title>Understanding the Proxy</title>

        <para>
            In the previous example, we used the <methodname>getService()</methodname> method to
            return a proxy object to the <constant>IMFS</constant> namespace. The proxy object
            allows you to use the Nirvanix REST service in a way that's closer to making a normal
            <acronym>PHP</acronym> method call, as opposed to constructing your own
            <acronym>HTTP</acronym> request objects.
        </para>

        <para>
            A proxy object may provide convenience methods. These are methods that the
            <classname>Zend_Service_Nirvanix</classname> provides to simplify the use of
            the Nirvanix web services. In the previous example, the methods
            <methodname>putContents()</methodname>, <methodname>getContents()</methodname>, and
            <methodname>unlink()</methodname> do not have direct equivalents in the REST
            <acronym>API</acronym>. They are convenience methods provided by
            <classname>Zend_Service_Nirvanix</classname> that abstract more complicated operations
            on the REST <acronym>API</acronym>.
        </para>

        <para>
            For all other method calls to the proxy object, the proxy will dynamically convert the
            method call to the equivalent <acronym>HTTP</acronym> POST request to the REST
            <acronym>API</acronym>. It does this by using the method name as the
            <acronym>API</acronym> command, and an associative array in the first argument as the
            POST parameters.
        </para>

        <para>
            Let's say you want to call the REST <acronym>API</acronym> method <ulink
                url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999923">RenameFile</ulink>,
            which does not have a convenience method in
            <classname>Zend_Service_Nirvanix</classname>:
        </para>

        <programlisting language="php"><![CDATA[
$auth = array('username' => 'your-username',
              'password' => 'your-password',
              'appKey'   => 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix->getService('IMFS');

$result = $imfs->renameFile(array('filePath' => '/path/to/foo.txt',
                                  'newFileName' => 'bar.txt'));
]]></programlisting>

        <para>
            Above, a proxy for the <constant>IMFS</constant> namespace is created. A method,
            <methodname>renameFile()</methodname>, is then called on the proxy. This method does not
            exist as a convenience method in the <acronym>PHP</acronym> code, so it is trapped by
            <methodname>__call()</methodname> and converted into a POST request to the REST
            <acronym>API</acronym> where the associative array is used as the POST parameters.
        </para>

        <para>
            Notice in the Nirvanix <acronym>API</acronym> documentation that
            <code>sessionToken</code> is required for this method but we did not give it to the
            proxy object. It is added automatically for your convenience.
        </para>

        <para>
            The result of this operation will either be a
            <classname>Zend_Service_Nirvanix_Response</classname> object wrapping the
            <acronym>XML</acronym> returned by Nirvanix, or a
            <classname>Zend_Service_Nirvanix_Exception</classname> if an error occurred.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.examining-results">
        <title>Examining Results</title>

        <para>
            The Nirvanix REST <acronym>API</acronym> always returns its results in
            <acronym>XML</acronym>. <classname>Zend_Service_Nirvanix</classname> parses this
            <acronym>XML</acronym> with the <code>SimpleXML</code> extension and then decorates the
            resulting <code>SimpleXMLElement</code> with a
            <classname>Zend_Service_Nirvanix_Response</classname> object.
        </para>

        <para>
            The simplest way to examine a result from the service is to use the
            built-in <acronym>PHP</acronym> functions like <methodname>print_r()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
<?php
$auth = array('username' => 'your-username',
              'password' => 'your-password',
              'appKey'   => 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix->getService('IMFS');

$result = $imfs->putContents('/foo.txt', 'fourteen bytes');
print_r($result);
?>

Zend_Service_Nirvanix_Response Object
(
    [_sxml:protected] => SimpleXMLElement Object
        (
            [ResponseCode] => 0
            [FilesUploaded] => 1
            [BytesUploaded] => 14
        )
)
]]></programlisting>

        <para>
            You can access any property or method of the decorated <code>SimpleXMLElement</code>.
            In the above example, <code>$result->BytesUploaded</code> could be used to see the
            number of bytes received. Should you want to access the <code>SimpleXMLElement</code>
            directly, just use <code>$result->getSxml()</code>.
        </para>

        <para>
            The most common response from Nirvanix is success (<code>ResponseCode</code> of zero).
            It is not normally necessary to check <code>ResponseCode</code> because any non-zero
            result will throw a <classname>Zend_Service_Nirvanix_Exception</classname>. See the next
            section on handling errors.
        </para>
    </sect2>

    <sect2 id="zend.service.nirvanix.handling-errors">
        <title>Handling Errors</title>

        <para>
            When using Nirvanix, it's important to anticipate errors that can be returned
            by the service and handle them appropriately.
        </para>

        <para>
            All operations against the REST service result in an <acronym>XML</acronym> return
            payload that contains a <code>ResponseCode</code> element, such as the following
            example:
        </para>

        <programlisting language="xml"><![CDATA[
<Response>
   <ResponseCode>0</ResponseCode>
</Response>
]]></programlisting>

        <para>
            When the <code>ResponseCode</code> is zero such as in the example
            above, the operation was successful. When the operation is not
            successful, the <code>ResponseCode</code> is non-zero and an
            <code>ErrorMessage</code> element should be present.
        </para>

        <para>
            To alleviate the need to repeatedly check if the <code>ResponseCode</code>
            is non-zero, <classname>Zend_Service_Nirvanix</classname> automatically checks each
            response returned by Nirvanix. If the <code>ResponseCode</code> indicates an
            error, a <classname>Zend_Service_Nirvanix_Exception</classname> will be thrown.
        </para>

        <programlisting language="xml"><![CDATA[
$auth = array('username' => 'your-username',
              'password' => 'your-password',
              'appKey'   => 'your-app-key');
$nirvanix = new Zend_Service_Nirvanix($auth);

try {

  $imfs = $nirvanix->getService('IMFS');
  $imfs->unlink('/a-nonexistant-path');

} catch (Zend_Service_Nirvanix_Exception $e) {
  echo $e->getMessage() . "\n";
  echo $e->getCode();
}
]]></programlisting>

        <para>
            In the example above, <methodname>unlink()</methodname> is a convenience method that
            wraps the <code>DeleteFiles</code> command on the REST <acronym>API</acronym>. The
            <code>filePath</code> parameter required by the <ulink
                url="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999918">DeleteFiles</ulink>
            command contains a path that does not exist. This will result in a
            <classname>Zend_Service_Nirvanix</classname> exception being thrown with the message
            "Invalid path" and code 70005.
        </para>

        <para>
            The <ulink url="http://developer.nirvanix.com/sitefiles/1000/API.html">Nirvanix
            <acronym>API</acronym> Documentation</ulink> describes the errors associated with each
            command. Depending on your needs, you may wrap each command in a <code>try</code> block
            or wrap many commands in the same <code>try</code> block for convenience.
        </para>
    </sect2>
</sect1>