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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.flickr">
    <title>Zend_Service_Flickr</title>
    <sect2 id="zend.service.flickr.introduction">
        <title>Introduction</title>
        <para>
            <classname>Zend_Service_Flickr</classname> is a simple <acronym>API</acronym> for using the Flickr REST Web Service. In order to use
            the Flickr web services, you must have an <acronym>API</acronym> key. To obtain a key and for more information about the
            Flickr REST Web Service, please visit the
            <ulink url="http://www.flickr.com/services/api/">Flickr <acronym>API</acronym> Documentation</ulink>.
        </para>
        <para>
            In the following example, we use the <methodname>tagSearch()</methodname> method to search for photos having "php"
            in the tags.
        </para>
        <example id="zend.service.flickr.introduction.example-1">
            <title>Simple Flickr Photo Search</title>
            <programlisting language="php"><![CDATA[
$flickr = new Zend_Service_Flickr('MY_API_KEY');

$results = $flickr->tagSearch("php");

foreach ($results as $result) {
    echo $result->title . '<br />';
}
]]></programlisting>
        </example>
        <note>
            <title>Optional parameter</title>
            <para>
                <methodname>tagSearch()</methodname> accepts an optional second parameter as an array of options.
            </para>
        </note>
    </sect2>
    <sect2 id="zend.service.flickr.finding-users">
        <title>Finding Flickr Users' Photos and Information</title>
        <para>
            <classname>Zend_Service_Flickr</classname> provides several ways to get information about Flickr users:
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    <methodname>userSearch()</methodname>: Accepts a string query of space-delimited tags and an optional second
                    parameter as an array of search options, and returns a set of photos as a
                    <classname>Zend_Service_Flickr_ResultSet</classname> object.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getIdByUsername()</methodname>: Returns a string user ID associated with the given username string.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getIdByEmail()</methodname>: Returns a string user ID associated with the given email address
                    string.
                </para>
            </listitem>
        </itemizedlist>
        <example id="zend.service.flickr.finding-users.example-1">
            <title>Finding a Flickr User's Public Photos by E-Mail Address</title>
            <para>
                In this example, we have a Flickr user's e-mail address, and we search for the user's public photos by
                using the <methodname>userSearch()</methodname> method:
            </para>
            <programlisting language="php"><![CDATA[
$flickr = new Zend_Service_Flickr('MY_API_KEY');

$results = $flickr->userSearch($userEmail);

foreach ($results as $result) {
    echo $result->title . '<br />';
}
]]></programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.flickr.grouppoolgetphotos">
        <title>Finding photos From a Group Pool</title>
        <para>
            <classname>Zend_Service_Flickr</classname> allows to retrieve a group's pool photos based
            on the group ID. Use the <methodname>groupPoolGetPhotos()</methodname> method:
        </para>
        <example id="zend.service.flickr.grouppoolgetphotos.example-1">
            <title>Retrieving a Group's Pool Photos by Group ID</title>
            <programlisting language="php"><![CDATA[
$flickr = new Zend_Service_Flickr('MY_API_KEY');

    $results = $flickr->groupPoolGetPhotos($groupId);

    foreach ($results as $result) {
        echo $result->title . '<br />';
    }
]]></programlisting>
        </example>
        <note>
            <title>Optional parameter</title>
            <para>
                <methodname>groupPoolGetPhotos()</methodname> accepts an optional second parameter as an array of options.
            </para>
        </note>
    </sect2>
    <sect2 id="zend.service.flickr.getimagedetails">
        <title>Retrieving Flickr Image Details</title>
        <para>
            <classname>Zend_Service_Flickr</classname> makes it quick and easy to get an image's details based on a given image
            ID. Just use the <methodname>getImageDetails()</methodname> method, as in the following example:
        </para>
        <example id="zend.service.flickr.getimagedetails.example-1">
            <title>Retrieving Flickr Image Details</title>
            <para>
                Once you have a Flickr image ID, it is a simple matter to fetch information about the image:
            </para>
            <programlisting language="php"><![CDATA[
$flickr = new Zend_Service_Flickr('MY_API_KEY');

$image = $flickr->getImageDetails($imageId);

echo "Image ID $imageId is $image->width x $image->height pixels.<br />\n";
echo "<a href=\"$image->clickUri\">Click for Image</a>\n";
]]></programlisting>
        </example>
    </sect2>
    <sect2 id="zend.service.flickr.classes">
        <title>Zend_Service_Flickr Result Classes</title>
        <para>
            The following classes are all returned by <methodname>tagSearch()</methodname> and <methodname>userSearch()</methodname>:
            <itemizedlist>
                <listitem><para><link linkend="zend.service.flickr.classes.resultset"><classname>Zend_Service_Flickr_ResultSet</classname></link></para></listitem>
                <listitem><para><link linkend="zend.service.flickr.classes.result"><classname>Zend_Service_Flickr_Result</classname></link></para></listitem>
                <listitem><para><link linkend="zend.service.flickr.classes.image"><classname>Zend_Service_Flickr_Image</classname></link></para></listitem>
            </itemizedlist>
        </para>
        <sect3 id="zend.service.flickr.classes.resultset">
            <title>Zend_Service_Flickr_ResultSet</title>
            <para>Represents a set of Results from a Flickr search.</para>
            <note>
                <para>
                    Implements the <classname>SeekableIterator</classname> interface for easy
                    iteration (e.g., using <methodname>foreach()</methodname>), as well as direct
                    access to a specific result using <methodname>seek()</methodname>.
                </para>
            </note>
            <sect4 id="zend.service.flickr.classes.resultset.properties">
                <title>Properties</title>
                <table id="zend.service.flickr.classes.resultset.properties.table-1">
                    <title>Zend_Service_Flickr_ResultSet Properties</title>
                    <tgroup cols="3">
                        <thead>
                            <row>
                                <entry>Name</entry>
                                <entry>Type</entry>
                                <entry>Description</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>totalResultsAvailable</entry>
                                <entry>int</entry>
                                <entry>Total Number of Results available</entry>
                            </row>
                            <row>
                                <entry>totalResultsReturned</entry>
                                <entry>int</entry>
                                <entry>Total Number of Results returned</entry>
                            </row>
                            <row>
                                <entry>firstResultPosition</entry>
                                <entry>int</entry>
                                <entry>The offset in the total result set of this result set</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
            </sect4>
            <sect4 id="zend.service.flickr.classes.resultset.totalResults">
                <title>Zend_Service_Flickr_ResultSet::totalResults()</title>
                <para>
                    <methodsynopsis>
                        <type>int</type>
                        <methodname>totalResults</methodname>
                        <void />
                    </methodsynopsis>
                </para>
                <para>
                    Returns the total number of results in this result set.
                </para>
                <para>
                    <link linkend="zend.service.flickr.classes">Back to Class List</link>
                </para>
            </sect4>
        </sect3>
        <sect3 id="zend.service.flickr.classes.result">
            <title>Zend_Service_Flickr_Result</title>
            <para>
                A single Image result from a Flickr query
            </para>
            <sect4 id="zend.service.flickr.classes.result.properties">
                <title>Properties</title>
                <table id="zend.service.flickr.classes.result.properties.table-1">
                    <title>Zend_Service_Flickr_Result Properties</title>
                    <tgroup cols="3">
                        <thead>
                            <row>
                                <entry>Name</entry>
                                <entry>Type</entry>
                                <entry>Description</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>id</entry>
                                <entry>string</entry>
                                <entry>Image ID</entry>
                            </row>
                            <row>
                                <entry>owner</entry>
                                <entry>string</entry>
                                <entry>The photo owner's <acronym>NSID</acronym>.</entry>
                            </row>
                            <row>
                                <entry>secret</entry>
                                <entry>string</entry>
                                <entry>A key used in url construction.</entry>
                            </row>
                            <row>
                                <entry>server</entry>
                                <entry>string</entry>
                                <entry>The servername to use for <acronym>URL</acronym> construction.</entry>
                            </row>
                            <row>
                                <entry>title</entry>
                                <entry>string</entry>
                                <entry>The photo's title.</entry>
                            </row>
                            <row>
                                <entry>ispublic</entry>
                                <entry>string</entry>
                                <entry>The photo is public.</entry>
                            </row>
                            <row>
                                <entry>isfriend</entry>
                                <entry>string</entry>
                                <entry>The photo is visible to you because you are a friend of the owner.</entry>
                            </row>
                            <row>
                                <entry>isfamily</entry>
                                <entry>string</entry>
                                <entry>The photo is visible to you because you are family of the owner.</entry>
                            </row>
                            <row>
                                <entry>license</entry>
                                <entry>string</entry>
                                <entry>The license the photo is available under.</entry>
                            </row>
                            <row>
                                <entry>dateupload</entry>
                                <entry>string</entry>
                                <entry>The date the photo was uploaded.</entry>
                            </row>
                            <row>
                                <entry>datetaken</entry>
                                <entry>string</entry>
                                <entry>The date the photo was taken.</entry>
                            </row>
                            <row>
                                <entry>ownername</entry>
                                <entry>string</entry>
                                <entry>The screenname of the owner.</entry>
                            </row>
                            <row>
                                <entry>iconserver</entry>
                                <entry>string</entry>
                                <entry>The server used in assembling icon <acronym>URL</acronym>s.</entry>
                            </row>
                            <row>
                                <entry>Square</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>A 75x75 thumbnail of the image.</entry>
                            </row>
                            <row>
                                <entry>Thumbnail</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>A 100 pixel thumbnail of the image.</entry>
                            </row>
                            <row>
                                <entry>Small</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>A 240 pixel version of the image.</entry>
                            </row>
                            <row>
                                <entry>Medium</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>A 500 pixel version of the image.</entry>
                            </row>
                            <row>
                                <entry>Large</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>A 640 pixel version of the image.</entry>
                            </row>
                            <row>
                                <entry>Original</entry>
                                <entry><link linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link></entry>
                                <entry>The original image.</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
                <para>
                    <link linkend="zend.service.flickr.classes">Back to Class List</link>
                </para>
            </sect4>
        </sect3>
        <sect3 id="zend.service.flickr.classes.image">
            <title>Zend_Service_Flickr_Image</title>
            <para>Represents an Image returned by a Flickr search.</para>
            <sect4 id="zend.service.flickr.classes.image.properties">
                <title>Properties</title>
                <table id="zend.service.flickr.classes.image.properties.table-1">
                    <title>Zend_Service_Flickr_Image Properties</title>
                    <tgroup cols="3">
                        <thead>
                            <row>
                                <entry>Name</entry>
                                <entry>Type</entry>
                                <entry>Description</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>uri</entry>
                                <entry>string</entry>
                                <entry>URI for the original image</entry>
                            </row>
                            <row>
                                <entry>clickUri</entry>
                                <entry>string</entry>
                                <entry>Clickable <acronym>URI</acronym> (i.e. the Flickr page) for the image</entry>
                            </row>
                            <row>
                                <entry>width</entry>
                                <entry>int</entry>
                                <entry>Width of the Image</entry>
                            </row>
                            <row>
                                <entry>height</entry>
                                <entry>int</entry>
                                <entry>Height of the Image</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
                <para>
                    <link linkend="zend.service.flickr.classes">Back to Class List</link>
                </para>
            </sect4>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->