[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Zend Framework
   5   *
   6   * LICENSE
   7   *
   8   * This source file is subject to the new BSD license that is bundled
   9   * with this package in the file LICENSE.txt.
  10   * It is also available through the world-wide-web at this URL:
  11   * http://framework.zend.com/license/new-bsd
  12   * If you did not receive a copy of the license and are unable to
  13   * obtain it through the world-wide-web, please send an email
  14   * to [email protected] so we can send you a copy immediately.
  15   *
  16   * @category   Zend
  17   * @package    Zend_Service
  18   * @subpackage Flickr
  19   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  20   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21   * @version    $Id$
  22   */
  23  
  24  
  25  /**
  26   * @category   Zend
  27   * @package    Zend_Service
  28   * @subpackage Flickr
  29   * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
  30   * @license    http://framework.zend.com/license/new-bsd     New BSD License
  31   */
  32  class Zend_Service_Flickr
  33  {
  34      /**
  35       * Base URI for the REST client
  36       */
  37      const URI_BASE = 'http://www.flickr.com';
  38  
  39      /**
  40       * Your Flickr API key
  41       *
  42       * @var string
  43       */
  44      public $apiKey;
  45  
  46      /**
  47       * Reference to REST client object
  48       *
  49       * @var Zend_Rest_Client
  50       */
  51      protected $_restClient = null;
  52  
  53  
  54      /**
  55       * Performs object initializations
  56       *
  57       *  # Sets up character encoding
  58       *  # Saves the API key
  59       *
  60       * @param  string $apiKey Your Flickr API key
  61       * @return void
  62       */
  63      public function __construct($apiKey)
  64      {
  65          iconv_set_encoding('output_encoding', 'UTF-8');
  66          iconv_set_encoding('input_encoding', 'UTF-8');
  67          iconv_set_encoding('internal_encoding', 'UTF-8');
  68  
  69          $this->apiKey = (string) $apiKey;
  70      }
  71  
  72  
  73      /**
  74       * Find Flickr photos by tag.
  75       *
  76       * Query options include:
  77       *
  78       *  # per_page:        how many results to return per query
  79       *  # page:            the starting page offset.  first result will be (page - 1) * per_page + 1
  80       *  # tag_mode:        Either 'any' for an OR combination of tags,
  81       *                     or 'all' for an AND combination. Default is 'any'.
  82       *  # min_upload_date: Minimum upload date to search on.  Date should be a unix timestamp.
  83       *  # max_upload_date: Maximum upload date to search on.  Date should be a unix timestamp.
  84       *  # min_taken_date:  Minimum upload date to search on.  Date should be a MySQL datetime.
  85       *  # max_taken_date:  Maximum upload date to search on.  Date should be a MySQL datetime.
  86       *
  87       * @param  string|array $query   A single tag or an array of tags.
  88       * @param  array        $options Additional parameters to refine your query.
  89       * @return Zend_Service_Flickr_ResultSet
  90       * @throws Zend_Service_Exception
  91       */
  92      public function tagSearch($query, array $options = array())
  93      {
  94          static $method = 'flickr.photos.search';
  95          static $defaultOptions = array('per_page' => 10,
  96                                         'page'     => 1,
  97                                         'tag_mode' => 'or',
  98                                         'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
  99  
 100          $options['tags'] = is_array($query) ? implode(',', $query) : $query;
 101  
 102          $options = $this->_prepareOptions($method, $options, $defaultOptions);
 103  
 104          $this->_validateTagSearch($options);
 105  
 106          // now search for photos
 107          $restClient = $this->getRestClient();
 108          $restClient->getHttpClient()->resetParameters();
 109          $response = $restClient->restGet('/services/rest/', $options);
 110  
 111          if ($response->isError()) {
 112              /**
 113               * @see Zend_Service_Exception
 114               */
 115              require_once 'Zend/Service/Exception.php';
 116              throw new Zend_Service_Exception('An error occurred sending request. Status code: '
 117                                             . $response->getStatus());
 118          }
 119  
 120          $dom = new DOMDocument();
 121          $dom->loadXML($response->getBody());
 122  
 123          self::_checkErrors($dom);
 124  
 125          /**
 126           * @see Zend_Service_Flickr_ResultSet
 127           */
 128          require_once 'Zend/Service/Flickr/ResultSet.php';
 129          return new Zend_Service_Flickr_ResultSet($dom, $this);
 130      }
 131  
 132  
 133      /**
 134       * Finds photos by a user's username or email.
 135       *
 136       * Additional query options include:
 137       *
 138       *  # per_page:        how many results to return per query
 139       *  # page:            the starting page offset.  first result will be (page - 1) * per_page + 1
 140       *  # min_upload_date: Minimum upload date to search on.  Date should be a unix timestamp.
 141       *  # max_upload_date: Maximum upload date to search on.  Date should be a unix timestamp.
 142       *  # min_taken_date:  Minimum upload date to search on.  Date should be a MySQL datetime.
 143       *  # max_taken_date:  Maximum upload date to search on.  Date should be a MySQL datetime.
 144       *
 145       * @param  string $query   username or email
 146       * @param  array  $options Additional parameters to refine your query.
 147       * @return Zend_Service_Flickr_ResultSet
 148       * @throws Zend_Service_Exception
 149       */
 150      public function userSearch($query, array $options = null)
 151      {
 152          static $method = 'flickr.people.getPublicPhotos';
 153          static $defaultOptions = array('per_page' => 10,
 154                                         'page'     => 1,
 155                                         'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
 156  
 157  
 158          // can't access by username, must get ID first
 159          if (strchr($query, '@')) {
 160              // optimistically hope this is an email
 161              $options['user_id'] = $this->getIdByEmail($query);
 162          } else {
 163              // we can safely ignore this exception here
 164              $options['user_id'] = $this->getIdByUsername($query);
 165          }
 166  
 167          $options = $this->_prepareOptions($method, $options, $defaultOptions);
 168          $this->_validateUserSearch($options);
 169  
 170          // now search for photos
 171          $restClient = $this->getRestClient();
 172          $restClient->getHttpClient()->resetParameters();
 173          $response = $restClient->restGet('/services/rest/', $options);
 174  
 175          if ($response->isError()) {
 176              /**
 177               * @see Zend_Service_Exception
 178               */
 179              require_once 'Zend/Service/Exception.php';
 180              throw new Zend_Service_Exception('An error occurred sending request. Status code: '
 181                                             . $response->getStatus());
 182          }
 183  
 184          $dom = new DOMDocument();
 185          $dom->loadXML($response->getBody());
 186  
 187          self::_checkErrors($dom);
 188  
 189          /**
 190           * @see Zend_Service_Flickr_ResultSet
 191           */
 192          require_once 'Zend/Service/Flickr/ResultSet.php';
 193          return new Zend_Service_Flickr_ResultSet($dom, $this);
 194      }
 195  
 196      /**
 197       * Finds photos in a group's pool.
 198       *
 199       * @param  string $query   group id
 200       * @param  array  $options Additional parameters to refine your query.
 201       * @return Zend_Service_Flickr_ResultSet
 202       * @throws Zend_Service_Exception
 203       */
 204      public function groupPoolGetPhotos($query, array $options = array())
 205      {
 206          static $method = 'flickr.groups.pools.getPhotos';
 207          static $defaultOptions = array('per_page' => 10,
 208                                         'page'     => 1,
 209                                         'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
 210  
 211          if (empty($query) || !is_string($query)) {
 212              /**
 213               * @see Zend_Service_Exception
 214               */
 215              require_once 'Zend/Service/Exception.php';
 216              throw new Zend_Service_Exception('You must supply a group id');
 217          }
 218  
 219          $options['group_id'] = $query;
 220  
 221          $options = $this->_prepareOptions($method, $options, $defaultOptions);
 222  
 223          $this->_validateGroupPoolGetPhotos($options);
 224  
 225          // now search for photos
 226          $restClient = $this->getRestClient();
 227          $restClient->getHttpClient()->resetParameters();
 228          $response = $restClient->restGet('/services/rest/', $options);
 229  
 230          if ($response->isError()) {
 231              /**
 232              * @see Zend_Service_Exception
 233              */
 234              require_once 'Zend/Service/Exception.php';
 235              throw new Zend_Service_Exception('An error occurred sending request. Status code: '
 236                                             . $response->getStatus());
 237          }
 238  
 239          $dom = new DOMDocument();
 240          $dom->loadXML($response->getBody());
 241  
 242          self::_checkErrors($dom);
 243  
 244          /**
 245          * @see Zend_Service_Flickr_ResultSet
 246          */
 247          require_once 'Zend/Service/Flickr/ResultSet.php';
 248          return new Zend_Service_Flickr_ResultSet($dom, $this);
 249      }
 250  
 251  
 252  
 253      /**
 254       * Utility function to find Flickr User IDs for usernames.
 255       *
 256       * (You can only find a user's photo with their NSID.)
 257       *
 258       * @param  string $username the username
 259       * @return string the NSID (userid)
 260       * @throws Zend_Service_Exception
 261       */
 262      public function getIdByUsername($username)
 263      {
 264          static $method = 'flickr.people.findByUsername';
 265  
 266          $options = array('api_key' => $this->apiKey, 'method' => $method, 'username' => (string) $username);
 267  
 268          if (empty($username)) {
 269              /**
 270               * @see Zend_Service_Exception
 271               */
 272              require_once 'Zend/Service/Exception.php';
 273              throw new Zend_Service_Exception('You must supply a username');
 274          }
 275  
 276          $restClient = $this->getRestClient();
 277          $restClient->getHttpClient()->resetParameters();
 278          $response = $restClient->restGet('/services/rest/', $options);
 279  
 280          if ($response->isError()) {
 281              /**
 282               * @see Zend_Service_Exception
 283               */
 284              require_once 'Zend/Service/Exception.php';
 285              throw new Zend_Service_Exception('An error occurred sending request. Status code: '
 286                                             . $response->getStatus());
 287          }
 288  
 289          $dom = new DOMDocument();
 290          $dom->loadXML($response->getBody());
 291          self::_checkErrors($dom);
 292          $xpath = new DOMXPath($dom);
 293          return (string) $xpath->query('//user')->item(0)->getAttribute('id');
 294      }
 295  
 296  
 297      /**
 298       * Utility function to find Flickr User IDs for emails.
 299       *
 300       * (You can only find a user's photo with their NSID.)
 301       *
 302       * @param  string $email the email
 303       * @return string the NSID (userid)
 304       * @throws Zend_Service_Exception
 305       */
 306      public function getIdByEmail($email)
 307      {
 308          static $method = 'flickr.people.findByEmail';
 309  
 310          if (empty($email)) {
 311              /**
 312               * @see Zend_Service_Exception
 313               */
 314              require_once 'Zend/Service/Exception.php';
 315              throw new Zend_Service_Exception('You must supply an e-mail address');
 316          }
 317  
 318          $options = array('api_key' => $this->apiKey, 'method' => $method, 'find_email' => (string) $email);
 319  
 320          $restClient = $this->getRestClient();
 321          $restClient->getHttpClient()->resetParameters();
 322          $response = $restClient->restGet('/services/rest/', $options);
 323  
 324          if ($response->isError()) {
 325              /**
 326               * @see Zend_Service_Exception
 327               */
 328              require_once 'Zend/Service/Exception.php';
 329              throw new Zend_Service_Exception('An error occurred sending request. Status code: '
 330                                             . $response->getStatus());
 331          }
 332  
 333          $dom = new DOMDocument();
 334          $dom->loadXML($response->getBody());
 335          self::_checkErrors($dom);
 336          $xpath = new DOMXPath($dom);
 337          return (string) $xpath->query('//user')->item(0)->getAttribute('id');
 338      }
 339  
 340  
 341      /**
 342       * Returns Flickr photo details by for the given photo ID
 343       *
 344       * @param  string $id the NSID
 345       * @return array of Zend_Service_Flickr_Image, details for the specified image
 346       * @throws Zend_Service_Exception
 347       */
 348      public function getImageDetails($id)
 349      {
 350          static $method = 'flickr.photos.getSizes';
 351  
 352          if (empty($id)) {
 353              /**
 354               * @see Zend_Service_Exception
 355               */
 356              require_once 'Zend/Service/Exception.php';
 357              throw new Zend_Service_Exception('You must supply a photo ID');
 358          }
 359  
 360          $options = array('api_key' => $this->apiKey, 'method' => $method, 'photo_id' => $id);
 361  
 362          $restClient = $this->getRestClient();
 363          $restClient->getHttpClient()->resetParameters();
 364          $response = $restClient->restGet('/services/rest/', $options);
 365  
 366          $dom = new DOMDocument();
 367          $dom->loadXML($response->getBody());
 368          $xpath = new DOMXPath($dom);
 369          self::_checkErrors($dom);
 370          $retval = array();
 371          /**
 372           * @see Zend_Service_Flickr_Image
 373           */
 374          require_once 'Zend/Service/Flickr/Image.php';
 375          foreach ($xpath->query('//size') as $size) {
 376              $label = (string) $size->getAttribute('label');
 377              $retval[$label] = new Zend_Service_Flickr_Image($size);
 378          }
 379  
 380          return $retval;
 381      }
 382  
 383  
 384      /**
 385       * Returns a reference to the REST client, instantiating it if necessary
 386       *
 387       * @return Zend_Rest_Client
 388       */
 389      public function getRestClient()
 390      {
 391          if (null === $this->_restClient) {
 392              /**
 393               * @see Zend_Rest_Client
 394               */
 395              require_once 'Zend/Rest/Client.php';
 396              $this->_restClient = new Zend_Rest_Client(self::URI_BASE);
 397          }
 398  
 399          return $this->_restClient;
 400      }
 401  
 402  
 403      /**
 404       * Validate User Search Options
 405       *
 406       * @param  array $options
 407       * @return void
 408       * @throws Zend_Service_Exception
 409       */
 410      protected function _validateUserSearch(array $options)
 411      {
 412          $validOptions = array('api_key', 'method', 'user_id', 'per_page', 'page', 'extras', 'min_upload_date',
 413                                'min_taken_date', 'max_upload_date', 'max_taken_date', 'safe_search');
 414  
 415          $this->_compareOptions($options, $validOptions);
 416  
 417          /**
 418           * @see Zend_Validate_Between
 419           */
 420          require_once 'Zend/Validate/Between.php';
 421          $between = new Zend_Validate_Between(1, 500, true);
 422          if (!$between->isValid($options['per_page'])) {
 423              /**
 424               * @see Zend_Service_Exception
 425               */
 426              require_once 'Zend/Service/Exception.php';
 427              throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
 428          }
 429  
 430          /**
 431           * @see Zend_Validate_Int
 432           */
 433          require_once 'Zend/Validate/Int.php';
 434          $int = new Zend_Validate_Int();
 435          if (!$int->isValid($options['page'])) {
 436              /**
 437               * @see Zend_Service_Exception
 438               */
 439              require_once 'Zend/Service/Exception.php';
 440              throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
 441          }
 442  
 443          // validate extras, which are delivered in csv format
 444          if ($options['extras']) {
 445              $extras = explode(',', $options['extras']);
 446              $validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
 447              foreach($extras as $extra) {
 448                  /**
 449                   * @todo The following does not do anything [yet], so it is commented out.
 450                   */
 451                  //in_array(trim($extra), $validExtras);
 452              }
 453          }
 454      }
 455  
 456  
 457      /**
 458       * Validate Tag Search Options
 459       *
 460       * @param  array $options
 461       * @return void
 462       * @throws Zend_Service_Exception
 463       */
 464      protected function _validateTagSearch(array $options)
 465      {
 466          $validOptions = array('method', 'api_key', 'user_id', 'tags', 'tag_mode', 'text', 'min_upload_date',
 467                                'max_upload_date', 'min_taken_date', 'max_taken_date', 'license', 'sort',
 468                                'privacy_filter', 'bbox', 'accuracy', 'safe_search', 'content_type', 'machine_tags',
 469                                'machine_tag_mode', 'group_id', 'contacts', 'woe_id', 'place_id', 'media', 'has_geo',
 470                                'geo_context', 'lat', 'lon', 'radius', 'radius_units', 'is_commons', 'is_gallery',
 471                                'extras', 'per_page', 'page');
 472  
 473          $this->_compareOptions($options, $validOptions);
 474  
 475          /**
 476           * @see Zend_Validate_Between
 477           */
 478          require_once 'Zend/Validate/Between.php';
 479          $between = new Zend_Validate_Between(1, 500, true);
 480          if (!$between->isValid($options['per_page'])) {
 481              /**
 482               * @see Zend_Service_Exception
 483               */
 484              require_once 'Zend/Service/Exception.php';
 485              throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
 486          }
 487  
 488          /**
 489           * @see Zend_Validate_Int
 490           */
 491          require_once 'Zend/Validate/Int.php';
 492          $int = new Zend_Validate_Int();
 493          if (!$int->isValid($options['page'])) {
 494              /**
 495               * @see Zend_Service_Exception
 496               */
 497              require_once 'Zend/Service/Exception.php';
 498              throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
 499          }
 500  
 501          // validate extras, which are delivered in csv format
 502          if ($options['extras']) {
 503              $extras = explode(',', $options['extras']);
 504              $validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
 505              foreach($extras as $extra) {
 506                  /**
 507                   * @todo The following does not do anything [yet], so it is commented out.
 508                   */
 509                  //in_array(trim($extra), $validExtras);
 510              }
 511          }
 512  
 513      }
 514  
 515  
 516      /**
 517      * Validate Group Search Options
 518      *
 519      * @param  array $options
 520      * @throws Zend_Service_Exception
 521      * @return void
 522      */
 523      protected function _validateGroupPoolGetPhotos(array $options)
 524      {
 525          $validOptions = array('api_key', 'tags', 'method', 'group_id', 'per_page', 'page', 'extras', 'user_id');
 526  
 527          $this->_compareOptions($options, $validOptions);
 528  
 529          /**
 530          * @see Zend_Validate_Between
 531          */
 532          require_once 'Zend/Validate/Between.php';
 533          $between = new Zend_Validate_Between(1, 500, true);
 534          if (!$between->isValid($options['per_page'])) {
 535              /**
 536              * @see Zend_Service_Exception
 537              */
 538              require_once 'Zend/Service/Exception.php';
 539              throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
 540          }
 541  
 542          /**
 543          * @see Zend_Validate_Int
 544          */
 545          require_once 'Zend/Validate/Int.php';
 546          $int = new Zend_Validate_Int();
 547  
 548          if (!$int->isValid($options['page'])) {
 549              /**
 550              * @see Zend_Service_Exception
 551              */
 552              require_once 'Zend/Service/Exception.php';
 553              throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
 554          }
 555  
 556          // validate extras, which are delivered in csv format
 557          if (isset($options['extras'])) {
 558              $extras = explode(',', $options['extras']);
 559              $validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
 560              foreach($extras as $extra) {
 561                  /**
 562                  * @todo The following does not do anything [yet], so it is commented out.
 563                  */
 564                  //in_array(trim($extra), $validExtras);
 565              }
 566          }
 567      }
 568  
 569  
 570      /**
 571       * Throws an exception if and only if the response status indicates a failure
 572       *
 573       * @param  DOMDocument $dom
 574       * @return void
 575       * @throws Zend_Service_Exception
 576       */
 577      protected static function _checkErrors(DOMDocument $dom)
 578      {
 579          if ($dom->documentElement->getAttribute('stat') === 'fail') {
 580              $xpath = new DOMXPath($dom);
 581              $err = $xpath->query('//err')->item(0);
 582              /**
 583               * @see Zend_Service_Exception
 584               */
 585              require_once 'Zend/Service/Exception.php';
 586              throw new Zend_Service_Exception('Search failed due to error: ' . $err->getAttribute('msg')
 587                                             . ' (error #' . $err->getAttribute('code') . ')');
 588          }
 589      }
 590  
 591  
 592      /**
 593       * Prepare options for the request
 594       *
 595       * @param  string $method         Flickr Method to call
 596       * @param  array  $options        User Options
 597       * @param  array  $defaultOptions Default Options
 598       * @return array Merged array of user and default/required options
 599       */
 600      protected function _prepareOptions($method, array $options, array $defaultOptions)
 601      {
 602          $options['method']  = (string) $method;
 603          $options['api_key'] = $this->apiKey;
 604  
 605          return array_merge($defaultOptions, $options);
 606      }
 607  
 608  
 609      /**
 610       * Throws an exception if and only if any user options are invalid
 611       *
 612       * @param  array $options      User options
 613       * @param  array $validOptions Valid options
 614       * @return void
 615       * @throws Zend_Service_Exception
 616       */
 617      protected function _compareOptions(array $options, array $validOptions)
 618      {
 619          $difference = array_diff(array_keys($options), $validOptions);
 620          if ($difference) {
 621              /**
 622               * @see Zend_Service_Exception
 623               */
 624              require_once 'Zend/Service/Exception.php';
 625              throw new Zend_Service_Exception('The following parameters are invalid: ' . implode(',', $difference));
 626          }
 627      }
 628  }
 629