tweet_live: comparison web/Zend/Service/Flickr.php

equal deleted inserted replaced

--1:000000000000
+:4eba9c11703f
+<?php
+/**
+* Zend Framework
+*
+* LICENSE
+*
+* This source file is subject to the new BSD license that is bundled
+* with this package in the file LICENSE.txt.
+* It is also available through the world-wide-web at this URL:
+* http://framework.zend.com/license/new-bsd
+* If you did not receive a copy of the license and are unable to
+* obtain it through the world-wide-web, please send an email
+* to license@zend.com so we can send you a copy immediately.
+*
+* @category   Zend
+* @package    Zend_Service
+* @subpackage Flickr
+* @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+* @license    http://framework.zend.com/license/new-bsd     New BSD License
+* @version    $Id: Flickr.php 22598 2010-07-16 21:24:14Z mikaelkael $
+*/
+/**
+* @category   Zend
+* @package    Zend_Service
+* @subpackage Flickr
+* @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
+* @license    http://framework.zend.com/license/new-bsd     New BSD License
+*/
+class Zend_Service_Flickr
+{
+/**
+* Base URI for the REST client
+*/
+const URI_BASE = 'http://www.flickr.com';
+/**
+* Your Flickr API key
+*
+* @var string
+*/
+public $apiKey;
+/**
+* Reference to REST client object
+*
+* @var Zend_Rest_Client
+*/
+protected $_restClient = null;
+/**
+* Performs object initializations
+*
+*  # Sets up character encoding
+*  # Saves the API key
+*
+* @param  string $apiKey Your Flickr API key
+* @return void
+*/
+public function __construct($apiKey)
+{
+$this->apiKey = (string) $apiKey;
+}
+/**
+* Find Flickr photos by tag.
+*
+* Query options include:
+*
+*  # per_page:        how many results to return per query
+*  # page:            the starting page offset.  first result will be (page - 1) * per_page + 1
+*  # tag_mode:        Either 'any' for an OR combination of tags,
+*                     or 'all' for an AND combination. Default is 'any'.
+*  # min_upload_date: Minimum upload date to search on.  Date should be a unix timestamp.
+*  # max_upload_date: Maximum upload date to search on.  Date should be a unix timestamp.
+*  # min_taken_date:  Minimum upload date to search on.  Date should be a MySQL datetime.
+*  # max_taken_date:  Maximum upload date to search on.  Date should be a MySQL datetime.
+*
+* @param  string|array $query   A single tag or an array of tags.
+* @param  array        $options Additional parameters to refine your query.
+* @return Zend_Service_Flickr_ResultSet
+* @throws Zend_Service_Exception
+*/
+public function tagSearch($query, array $options = array())
+{
+static $method = 'flickr.photos.search';
+static $defaultOptions = array('per_page' => 10,
+'page'     => 1,
+'tag_mode' => 'or',
+'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
+$options['tags'] = is_array($query) ? implode(',', $query) : $query;
+$options = $this->_prepareOptions($method, $options, $defaultOptions);
+$this->_validateTagSearch($options);
+// now search for photos
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+if ($response->isError()) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('An error occurred sending request. Status code: '
+. $response->getStatus());
+}
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+self::_checkErrors($dom);
+/**
+* @see Zend_Service_Flickr_ResultSet
+*/
+require_once 'Zend/Service/Flickr/ResultSet.php';
+return new Zend_Service_Flickr_ResultSet($dom, $this);
+}
+/**
+* Finds photos by a user's username or email.
+*
+* Additional query options include:
+*
+*  # per_page:        how many results to return per query
+*  # page:            the starting page offset.  first result will be (page - 1) * per_page + 1
+*  # min_upload_date: Minimum upload date to search on.  Date should be a unix timestamp.
+*  # max_upload_date: Maximum upload date to search on.  Date should be a unix timestamp.
+*  # min_taken_date:  Minimum upload date to search on.  Date should be a MySQL datetime.
+*  # max_taken_date:  Maximum upload date to search on.  Date should be a MySQL datetime.
+*
+* @param  string $query   username or email
+* @param  array  $options Additional parameters to refine your query.
+* @return Zend_Service_Flickr_ResultSet
+* @throws Zend_Service_Exception
+*/
+public function userSearch($query, array $options = null)
+{
+static $method = 'flickr.people.getPublicPhotos';
+static $defaultOptions = array('per_page' => 10,
+'page'     => 1,
+'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
+// can't access by username, must get ID first
+if (strchr($query, '@')) {
+// optimistically hope this is an email
+$options['user_id'] = $this->getIdByEmail($query);
+} else {
+// we can safely ignore this exception here
+$options['user_id'] = $this->getIdByUsername($query);
+}
+$options = $this->_prepareOptions($method, $options, $defaultOptions);
+$this->_validateUserSearch($options);
+// now search for photos
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+if ($response->isError()) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('An error occurred sending request. Status code: '
+. $response->getStatus());
+}
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+self::_checkErrors($dom);
+/**
+* @see Zend_Service_Flickr_ResultSet
+*/
+require_once 'Zend/Service/Flickr/ResultSet.php';
+return new Zend_Service_Flickr_ResultSet($dom, $this);
+}
+/**
+* Finds photos in a group's pool.
+*
+* @param  string $query   group id
+* @param  array  $options Additional parameters to refine your query.
+* @return Zend_Service_Flickr_ResultSet
+* @throws Zend_Service_Exception
+*/
+public function groupPoolGetPhotos($query, array $options = array())
+{
+static $method = 'flickr.groups.pools.getPhotos';
+static $defaultOptions = array('per_page' => 10,
+'page'     => 1,
+'extras'   => 'license, date_upload, date_taken, owner_name, icon_server');
+if (empty($query) || !is_string($query)) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('You must supply a group id');
+}
+$options['group_id'] = $query;
+$options = $this->_prepareOptions($method, $options, $defaultOptions);
+$this->_validateGroupPoolGetPhotos($options);
+// now search for photos
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+if ($response->isError()) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('An error occurred sending request. Status code: '
+. $response->getStatus());
+}
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+self::_checkErrors($dom);
+/**
+* @see Zend_Service_Flickr_ResultSet
+*/
+require_once 'Zend/Service/Flickr/ResultSet.php';
+return new Zend_Service_Flickr_ResultSet($dom, $this);
+}
+/**
+* Utility function to find Flickr User IDs for usernames.
+*
+* (You can only find a user's photo with their NSID.)
+*
+* @param  string $username the username
+* @return string the NSID (userid)
+* @throws Zend_Service_Exception
+*/
+public function getIdByUsername($username)
+{
+static $method = 'flickr.people.findByUsername';
+$options = array('api_key' => $this->apiKey, 'method' => $method, 'username' => (string) $username);
+if (empty($username)) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('You must supply a username');
+}
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+if ($response->isError()) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('An error occurred sending request. Status code: '
+. $response->getStatus());
+}
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+self::_checkErrors($dom);
+$xpath = new DOMXPath($dom);
+return (string) $xpath->query('//user')->item(0)->getAttribute('id');
+}
+/**
+* Utility function to find Flickr User IDs for emails.
+*
+* (You can only find a user's photo with their NSID.)
+*
+* @param  string $email the email
+* @return string the NSID (userid)
+* @throws Zend_Service_Exception
+*/
+public function getIdByEmail($email)
+{
+static $method = 'flickr.people.findByEmail';
+if (empty($email)) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('You must supply an e-mail address');
+}
+$options = array('api_key' => $this->apiKey, 'method' => $method, 'find_email' => (string) $email);
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+if ($response->isError()) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('An error occurred sending request. Status code: '
+. $response->getStatus());
+}
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+self::_checkErrors($dom);
+$xpath = new DOMXPath($dom);
+return (string) $xpath->query('//user')->item(0)->getAttribute('id');
+}
+/**
+* Returns Flickr photo details by for the given photo ID
+*
+* @param  string $id the NSID
+* @return array of Zend_Service_Flickr_Image, details for the specified image
+* @throws Zend_Service_Exception
+*/
+public function getImageDetails($id)
+{
+static $method = 'flickr.photos.getSizes';
+if (empty($id)) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('You must supply a photo ID');
+}
+$options = array('api_key' => $this->apiKey, 'method' => $method, 'photo_id' => $id);
+$restClient = $this->getRestClient();
+$restClient->getHttpClient()->resetParameters();
+$response = $restClient->restGet('/services/rest/', $options);
+$dom = new DOMDocument();
+$dom->loadXML($response->getBody());
+$xpath = new DOMXPath($dom);
+self::_checkErrors($dom);
+$retval = array();
+/**
+* @see Zend_Service_Flickr_Image
+*/
+require_once 'Zend/Service/Flickr/Image.php';
+foreach ($xpath->query('//size') as $size) {
+$label = (string) $size->getAttribute('label');
+$retval[$label] = new Zend_Service_Flickr_Image($size);
+}
+return $retval;
+}
+/**
+* Returns a reference to the REST client, instantiating it if necessary
+*
+* @return Zend_Rest_Client
+*/
+public function getRestClient()
+{
+if (null === $this->_restClient) {
+/**
+* @see Zend_Rest_Client
+*/
+require_once 'Zend/Rest/Client.php';
+$this->_restClient = new Zend_Rest_Client(self::URI_BASE);
+}
+return $this->_restClient;
+}
+/**
+* Validate User Search Options
+*
+* @param  array $options
+* @return void
+* @throws Zend_Service_Exception
+*/
+protected function _validateUserSearch(array $options)
+{
+$validOptions = array('api_key', 'method', 'user_id', 'per_page', 'page', 'extras', 'min_upload_date',
+'min_taken_date', 'max_upload_date', 'max_taken_date', 'safe_search');
+$this->_compareOptions($options, $validOptions);
+/**
+* @see Zend_Validate_Between
+*/
+require_once 'Zend/Validate/Between.php';
+$between = new Zend_Validate_Between(1, 500, true);
+if (!$between->isValid($options['per_page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
+}
+/**
+* @see Zend_Validate_Int
+*/
+require_once 'Zend/Validate/Int.php';
+$int = new Zend_Validate_Int();
+if (!$int->isValid($options['page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
+}
+// validate extras, which are delivered in csv format
+if ($options['extras']) {
+$extras = explode(',', $options['extras']);
+$validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
+foreach($extras as $extra) {
+/**
+* @todo The following does not do anything [yet], so it is commented out.
+*/
+//in_array(trim($extra), $validExtras);
+}
+}
+}
+/**
+* Validate Tag Search Options
+*
+* @param  array $options
+* @return void
+* @throws Zend_Service_Exception
+*/
+protected function _validateTagSearch(array $options)
+{
+$validOptions = array('method', 'api_key', 'user_id', 'tags', 'tag_mode', 'text', 'min_upload_date',
+'max_upload_date', 'min_taken_date', 'max_taken_date', 'license', 'sort',
+'privacy_filter', 'bbox', 'accuracy', 'safe_search', 'content_type', 'machine_tags',
+'machine_tag_mode', 'group_id', 'contacts', 'woe_id', 'place_id', 'media', 'has_geo',
+'geo_context', 'lat', 'lon', 'radius', 'radius_units', 'is_commons', 'is_gallery',
+'extras', 'per_page', 'page');
+$this->_compareOptions($options, $validOptions);
+/**
+* @see Zend_Validate_Between
+*/
+require_once 'Zend/Validate/Between.php';
+$between = new Zend_Validate_Between(1, 500, true);
+if (!$between->isValid($options['per_page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
+}
+/**
+* @see Zend_Validate_Int
+*/
+require_once 'Zend/Validate/Int.php';
+$int = new Zend_Validate_Int();
+if (!$int->isValid($options['page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
+}
+// validate extras, which are delivered in csv format
+if ($options['extras']) {
+$extras = explode(',', $options['extras']);
+$validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
+foreach($extras as $extra) {
+/**
+* @todo The following does not do anything [yet], so it is commented out.
+*/
+//in_array(trim($extra), $validExtras);
+}
+}
+}
+/**
+* Validate Group Search Options
+*
+* @param  array $options
+* @throws Zend_Service_Exception
+* @return void
+*/
+protected function _validateGroupPoolGetPhotos(array $options)
+{
+$validOptions = array('api_key', 'tags', 'method', 'group_id', 'per_page', 'page', 'extras', 'user_id');
+$this->_compareOptions($options, $validOptions);
+/**
+* @see Zend_Validate_Between
+*/
+require_once 'Zend/Validate/Between.php';
+$between = new Zend_Validate_Between(1, 500, true);
+if (!$between->isValid($options['per_page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['per_page'] . ' is not valid for the "per_page" option');
+}
+/**
+* @see Zend_Validate_Int
+*/
+require_once 'Zend/Validate/Int.php';
+$int = new Zend_Validate_Int();
+if (!$int->isValid($options['page'])) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception($options['page'] . ' is not valid for the "page" option');
+}
+// validate extras, which are delivered in csv format
+if (isset($options['extras'])) {
+$extras = explode(',', $options['extras']);
+$validExtras = array('license', 'date_upload', 'date_taken', 'owner_name', 'icon_server');
+foreach($extras as $extra) {
+/**
+* @todo The following does not do anything [yet], so it is commented out.
+*/
+//in_array(trim($extra), $validExtras);
+}
+}
+}
+/**
+* Throws an exception if and only if the response status indicates a failure
+*
+* @param  DOMDocument $dom
+* @return void
+* @throws Zend_Service_Exception
+*/
+protected static function _checkErrors(DOMDocument $dom)
+{
+if ($dom->documentElement->getAttribute('stat') === 'fail') {
+$xpath = new DOMXPath($dom);
+$err = $xpath->query('//err')->item(0);
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('Search failed due to error: ' . $err->getAttribute('msg')
+. ' (error #' . $err->getAttribute('code') . ')');
+}
+}
+/**
+* Prepare options for the request
+*
+* @param  string $method         Flickr Method to call
+* @param  array  $options        User Options
+* @param  array  $defaultOptions Default Options
+* @return array Merged array of user and default/required options
+*/
+protected function _prepareOptions($method, array $options, array $defaultOptions)
+{
+$options['method']  = (string) $method;
+$options['api_key'] = $this->apiKey;
+return array_merge($defaultOptions, $options);
+}
+/**
+* Throws an exception if and only if any user options are invalid
+*
+* @param  array $options      User options
+* @param  array $validOptions Valid options
+* @return void
+* @throws Zend_Service_Exception
+*/
+protected function _compareOptions(array $options, array $validOptions)
+{
+$difference = array_diff(array_keys($options), $validOptions);
+if ($difference) {
+/**
+* @see Zend_Service_Exception
+*/
+require_once 'Zend/Service/Exception.php';
+throw new Zend_Service_Exception('The following parameters are invalid: ' . implode(',', $difference));
+}
+}
+}