documentation/manual/en/module_specs/Zend_Service_Flickr.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.flickr">
   4     <title>Zend_Service_Flickr</title>
   5
   6     <sect2 id="zend.service.flickr.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Flickr</classname> is a simple <acronym>API</acronym> for using
  11             the Flickr REST Web Service. In order to use the Flickr web services, you must have an
  12             <acronym>API</acronym> key. To obtain a key and for more information about the Flickr
  13             REST Web Service, please visit the <ulink
  14                 url="http://www.flickr.com/services/api/">Flickr <acronym>API</acronym>
  15                 Documentation</ulink>.
  16         </para>
  17
  18         <para>
  19             In the following example, we use the <methodname>tagSearch()</methodname> method to
  20             search for photos having "php" in the tags.
  21         </para>
  22
  23         <example id="zend.service.flickr.introduction.example-1">
  24             <title>Simple Flickr Photo Search</title>
  25
  26             <programlisting language="php"><![CDATA[
  27 $flickr = new Zend_Service_Flickr('MY_API_KEY');
  28
  29 $results = $flickr->tagSearch("php");
  30
  31 foreach ($results as $result) {
  32     echo $result->title . '<br />';
  33 }
  34 ]]></programlisting>
  35         </example>
  36
  37         <note>
  38             <title>Optional parameter</title>
  39
  40             <para>
  41                 <methodname>tagSearch()</methodname> accepts an optional second parameter as an
  42                 array of options.
  43             </para>
  44         </note>
  45     </sect2>
  46
  47     <sect2 id="zend.service.flickr.finding-users">
  48         <title>Finding Flickr Users' Photos and Information</title>
  49
  50         <para>
  51             <classname>Zend_Service_Flickr</classname> provides several ways to get information
  52             about Flickr users:
  53         </para>
  54
  55         <itemizedlist>
  56             <listitem>
  57                 <para>
  58                     <methodname>userSearch()</methodname>: Accepts a string query of space-delimited
  59                     tags and an optional second parameter as an array of search options, and returns
  60                     a set of photos as a <classname>Zend_Service_Flickr_ResultSet</classname>
  61                     object.
  62                 </para>
  63             </listitem>
  64
  65             <listitem>
  66                 <para>
  67                     <methodname>getIdByUsername()</methodname>: Returns a string user ID associated
  68                     with the given username string.
  69                 </para>
  70             </listitem>
  71
  72             <listitem>
  73                 <para>
  74                     <methodname>getIdByEmail()</methodname>: Returns a string user ID associated
  75                     with the given email address string.
  76                 </para>
  77             </listitem>
  78         </itemizedlist>
  79
  80         <example id="zend.service.flickr.finding-users.example-1">
  81             <title>Finding a Flickr User's Public Photos by E-Mail Address</title>
  82
  83             <para>
  84                 In this example, we have a Flickr user's e-mail address, and we search for the
  85                 user's public photos by using the <methodname>userSearch()</methodname> method:
  86             </para>
  87
  88             <programlisting language="php"><![CDATA[
  89 $flickr = new Zend_Service_Flickr('MY_API_KEY');
  90
  91 $results = $flickr->userSearch($userEmail);
  92
  93 foreach ($results as $result) {
  94     echo $result->title . '<br />';
  95 }
  96 ]]></programlisting>
  97         </example>
  98     </sect2>
  99
 100     <sect2 id="zend.service.flickr.grouppoolgetphotos">
 101         <title>Finding photos From a Group Pool</title>
 102
 103         <para>
 104             <classname>Zend_Service_Flickr</classname> allows to retrieve a group's pool photos
 105             based on the group ID. Use the <methodname>groupPoolGetPhotos()</methodname> method:
 106         </para>
 107
 108         <example id="zend.service.flickr.grouppoolgetphotos.example-1">
 109             <title>Retrieving a Group's Pool Photos by Group ID</title>
 110
 111             <programlisting language="php"><![CDATA[
 112 $flickr = new Zend_Service_Flickr('MY_API_KEY');
 113
 114     $results = $flickr->groupPoolGetPhotos($groupId);
 115
 116     foreach ($results as $result) {
 117         echo $result->title . '<br />';
 118     }
 119 ]]></programlisting>
 120         </example>
 121
 122         <note>
 123             <title>Optional parameter</title>
 124
 125             <para>
 126                 <methodname>groupPoolGetPhotos()</methodname> accepts an optional second parameter
 127                 as an array of options.
 128             </para>
 129         </note>
 130     </sect2>
 131
 132     <sect2 id="zend.service.flickr.getimagedetails">
 133         <title>Retrieving Flickr Image Details</title>
 134
 135         <para>
 136             <classname>Zend_Service_Flickr</classname> makes it quick and easy to get an image's
 137             details based on a given image ID. Just use the
 138             <methodname>getImageDetails()</methodname> method, as in the following example:
 139         </para>
 140
 141         <example id="zend.service.flickr.getimagedetails.example-1">
 142             <title>Retrieving Flickr Image Details</title>
 143
 144             <para>
 145                 Once you have a Flickr image ID, it is a simple matter to fetch information about
 146                 the image:
 147             </para>
 148
 149             <programlisting language="php"><![CDATA[
 150 $flickr = new Zend_Service_Flickr('MY_API_KEY');
 151
 152 $image = $flickr->getImageDetails($imageId);
 153
 154 echo "Image ID $imageId is $image->width x $image->height pixels.<br />\n";
 155 echo "<a href=\"$image->clickUri\">Click for Image</a>\n";
 156 ]]></programlisting>
 157         </example>
 158     </sect2>
 159
 160     <sect2 id="zend.service.flickr.classes">
 161         <title>Zend_Service_Flickr Result Classes</title>
 162
 163         <para>
 164             The following classes are all returned by <methodname>tagSearch()</methodname> and
 165             <methodname>userSearch()</methodname>:
 166
 167             <itemizedlist>
 168                 <listitem>
 169                     <para>
 170                         <link
 171                             linkend="zend.service.flickr.classes.resultset"><classname>Zend_Service_Flickr_ResultSet</classname></link>
 172                     </para>
 173                 </listitem>
 174
 175                 <listitem>
 176                     <para>
 177                        <link
 178                            linkend="zend.service.flickr.classes.result"><classname>Zend_Service_Flickr_Result</classname></link>
 179                    </para>
 180                 </listitem>
 181
 182                 <listitem>
 183                     <para>
 184                         <link
 185                             linkend="zend.service.flickr.classes.image"><classname>Zend_Service_Flickr_Image</classname></link>
 186                     </para>
 187                 </listitem>
 188             </itemizedlist>
 189         </para>
 190
 191         <sect3 id="zend.service.flickr.classes.resultset">
 192             <title>Zend_Service_Flickr_ResultSet</title>
 193
 194             <para>Represents a set of Results from a Flickr search.</para>
 195
 196             <note>
 197                 <para>
 198                     Implements the <classname>SeekableIterator</classname> interface for easy
 199                     iteration (e.g., using <methodname>foreach()</methodname>), as well as direct
 200                     access to a specific result using <methodname>seek()</methodname>.
 201                 </para>
 202             </note>
 203
 204             <sect4 id="zend.service.flickr.classes.resultset.properties">
 205                 <title>Properties</title>
 206
 207                 <table id="zend.service.flickr.classes.resultset.properties.table-1">
 208                     <title>Zend_Service_Flickr_ResultSet Properties</title>
 209
 210                     <tgroup cols="3">
 211                         <thead>
 212                             <row>
 213                                 <entry>Name</entry>
 214                                 <entry>Type</entry>
 215                                 <entry>Description</entry>
 216                             </row>
 217                         </thead>
 218
 219                         <tbody>
 220                             <row>
 221                                 <entry>totalResultsAvailable</entry>
 222                                 <entry>int</entry>
 223                                 <entry>Total Number of Results available</entry>
 224                             </row>
 225
 226                             <row>
 227                                 <entry>totalResultsReturned</entry>
 228                                 <entry>int</entry>
 229                                 <entry>Total Number of Results returned</entry>
 230                             </row>
 231
 232                             <row>
 233                                 <entry>firstResultPosition</entry>
 234                                 <entry>int</entry>
 235                                 <entry>The offset in the total result set of this result set</entry>
 236                             </row>
 237                         </tbody>
 238                     </tgroup>
 239                 </table>
 240             </sect4>
 241
 242             <sect4 id="zend.service.flickr.classes.resultset.totalResults">
 243                 <title>Zend_Service_Flickr_ResultSet::totalResults()</title>
 244
 245                 <para>
 246                     <methodsynopsis>
 247                         <type>int</type>
 248                         <methodname>totalResults</methodname>
 249                         <void />
 250                     </methodsynopsis>
 251                 </para>
 252
 253                 <para>
 254                     Returns the total number of results in this result set.
 255                 </para>
 256
 257                 <para>
 258                     <link linkend="zend.service.flickr.classes">Back to Class List</link>
 259                 </para>
 260             </sect4>
 261         </sect3>
 262
 263         <sect3 id="zend.service.flickr.classes.result">
 264             <title>Zend_Service_Flickr_Result</title>
 265
 266             <para>
 267                 A single Image result from a Flickr query
 268             </para>
 269
 270             <sect4 id="zend.service.flickr.classes.result.properties">
 271                 <title>Properties</title>
 272
 273                 <table id="zend.service.flickr.classes.result.properties.table-1">
 274                     <title>Zend_Service_Flickr_Result Properties</title>
 275
 276                     <tgroup cols="3">
 277                         <thead>
 278                             <row>
 279                                 <entry>Name</entry>
 280                                 <entry>Type</entry>
 281                                 <entry>Description</entry>
 282                             </row>
 283                         </thead>
 284
 285                         <tbody>
 286                             <row>
 287                                 <entry>id</entry>
 288                                 <entry>string</entry>
 289                                 <entry>Image ID</entry>
 290                             </row>
 291
 292                             <row>
 293                                 <entry>owner</entry>
 294                                 <entry>string</entry>
 295                                 <entry>The photo owner's <acronym>NSID</acronym>.</entry>
 296                             </row>
 297
 298                             <row>
 299                                 <entry>secret</entry>
 300                                 <entry>string</entry>
 301                                 <entry>A key used in url construction.</entry>
 302                             </row>
 303
 304                             <row>
 305                                 <entry>server</entry>
 306                                 <entry>string</entry>
 307
 308                                 <entry>
 309                                     The servername to use for <acronym>URL</acronym> construction.
 310                                 </entry>
 311                             </row>
 312
 313                             <row>
 314                                 <entry>title</entry>
 315                                 <entry>string</entry>
 316                                 <entry>The photo's title.</entry>
 317                             </row>
 318
 319                             <row>
 320                                 <entry>ispublic</entry>
 321                                 <entry>string</entry>
 322                                 <entry>The photo is public.</entry>
 323                             </row>
 324
 325                             <row>
 326                                 <entry>isfriend</entry>
 327                                 <entry>string</entry>
 328
 329                                 <entry>
 330                                     The photo is visible to you because you are a friend of the
 331                                     owner.
 332                                 </entry>
 333                             </row>
 334
 335                             <row>
 336                                 <entry>isfamily</entry>
 337                                 <entry>string</entry>
 338
 339                                 <entry>
 340                                     The photo is visible to you because you are family of the owner.
 341                                 </entry>
 342                             </row>
 343
 344                             <row>
 345                                 <entry>license</entry>
 346                                 <entry>string</entry>
 347                                 <entry>The license the photo is available under.</entry>
 348                             </row>
 349
 350                             <row>
 351                                 <entry>dateupload</entry>
 352                                 <entry>string</entry>
 353                                 <entry>The date the photo was uploaded.</entry>
 354                             </row>
 355
 356                             <row>
 357                                 <entry>datetaken</entry>
 358                                 <entry>string</entry>
 359                                 <entry>The date the photo was taken.</entry>
 360                             </row>
 361
 362                             <row>
 363                                 <entry>ownername</entry>
 364                                 <entry>string</entry>
 365                                 <entry>The screenname of the owner.</entry>
 366                             </row>
 367
 368                             <row>
 369                                 <entry>iconserver</entry>
 370                                 <entry>string</entry>
 371
 372                                 <entry>
 373                                     The server used in assembling icon <acronym>URL</acronym>s.
 374                                 </entry>
 375                             </row>
 376
 377                             <row>
 378                                 <entry>Square</entry>
 379
 380                                 <entry>
 381                                     <link
 382                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 383                                 </entry>
 384
 385                                 <entry>A 75x75 thumbnail of the image.</entry>
 386                             </row>
 387
 388                             <row>
 389                                 <entry>Thumbnail</entry>
 390
 391                                 <entry>
 392                                     <link
 393                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 394                                 </entry>
 395
 396                                 <entry>A 100 pixel thumbnail of the image.</entry>
 397                             </row>
 398
 399                             <row>
 400                                 <entry>Small</entry>
 401
 402                                 <entry>
 403                                     <link
 404                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 405                                 </entry>
 406
 407                                 <entry>A 240 pixel version of the image.</entry>
 408                             </row>
 409
 410                             <row>
 411                                 <entry>Medium</entry>
 412
 413                                 <entry>
 414                                     <link
 415                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 416                                 </entry>
 417
 418                                 <entry>A 500 pixel version of the image.</entry>
 419                             </row>
 420
 421                             <row>
 422                                 <entry>Large</entry>
 423
 424                                 <entry>
 425                                     <link
 426                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 427                                 </entry>
 428
 429                                 <entry>A 640 pixel version of the image.</entry>
 430                             </row>
 431
 432                             <row>
 433                                 <entry>Original</entry>
 434
 435                                 <entry>
 436                                     <link
 437                                         linkend="zend.service.flickr.classes.image">Zend_Service_Flickr_Image</link>
 438                                 </entry>
 439
 440                                 <entry>The original image.</entry>
 441                             </row>
 442                         </tbody>
 443                     </tgroup>
 444                 </table>
 445
 446                 <para>
 447                     <link linkend="zend.service.flickr.classes">Back to Class List</link>
 448                 </para>
 449             </sect4>
 450         </sect3>
 451
 452         <sect3 id="zend.service.flickr.classes.image">
 453             <title>Zend_Service_Flickr_Image</title>
 454
 455             <para>Represents an Image returned by a Flickr search.</para>
 456
 457             <sect4 id="zend.service.flickr.classes.image.properties">
 458                 <title>Properties</title>
 459
 460                 <table id="zend.service.flickr.classes.image.properties.table-1">
 461                     <title>Zend_Service_Flickr_Image Properties</title>
 462
 463                     <tgroup cols="3">
 464                         <thead>
 465                             <row>
 466                                 <entry>Name</entry>
 467                                 <entry>Type</entry>
 468                                 <entry>Description</entry>
 469                             </row>
 470                         </thead>
 471
 472                         <tbody>
 473                             <row>
 474                                 <entry>uri</entry>
 475                                 <entry>string</entry>
 476                                 <entry>URI for the original image</entry>
 477                             </row>
 478
 479                             <row>
 480                                 <entry>clickUri</entry>
 481                                 <entry>string</entry>
 482
 483                                 <entry>
 484                                     Clickable <acronym>URI</acronym> (i.e. the Flickr page) for the
 485                                     image
 486                                 </entry>
 487                             </row>
 488
 489                             <row>
 490                                 <entry>width</entry>
 491                                 <entry>int</entry>
 492                                 <entry>Width of the Image</entry>
 493                             </row>
 494
 495                             <row>
 496                                 <entry>height</entry>
 497                                 <entry>int</entry>
 498                                 <entry>Height of the Image</entry>
 499                             </row>
 500                         </tbody>
 501                     </tgroup>
 502                 </table>
 503
 504                 <para>
 505                     <link linkend="zend.service.flickr.classes">Back to Class List</link>
 506                 </para>
 507             </sect4>
 508         </sect3>
 509     </sect2>
 510 </sect1>
 511 <!--
 512 vim:se ts=4 sw=4 et:
 513 -->