<?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');