<?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-2012 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: Flickr.php 24594 2012-01-05 21:27:01Z matthew $
*/
/**
* @category Zend
* @package Zend_Service
* @subpackage Flickr
* @copyright Copyright (c) 2005-2012 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));
}
}
}