<?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 Technorati

 * @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: Technorati.php 24593 2012-01-05 20:35:02Z matthew $

 */

/**

 * Zend_Service_Technorati provides an easy, intuitive and object-oriented interface

 * for using the Technorati API.

 *

 * It provides access to all available Technorati API queries

 * and returns the original XML response as a friendly PHP object.

 *

 * @category   Zend

 * @package    Zend_Service

 * @subpackage Technorati

 * @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_Technorati

{

    /** Base Technorati API URI */

    const API_URI_BASE = 'http://api.technorati.com';

    /** Query paths */

    const API_PATH_COSMOS           = '/cosmos';

    const API_PATH_SEARCH           = '/search';

    const API_PATH_TAG              = '/tag';

    const API_PATH_DAILYCOUNTS      = '/dailycounts';

    const API_PATH_TOPTAGS          = '/toptags';

    const API_PATH_BLOGINFO         = '/bloginfo';

    const API_PATH_BLOGPOSTTAGS     = '/blogposttags';

    const API_PATH_GETINFO          = '/getinfo';

    const API_PATH_KEYINFO          = '/keyinfo';

    /** Prevent magic numbers */

    const PARAM_LIMIT_MIN_VALUE = 1;

    const PARAM_LIMIT_MAX_VALUE = 100;

    const PARAM_DAYS_MIN_VALUE  = 1;

    const PARAM_DAYS_MAX_VALUE  = 180;

    const PARAM_START_MIN_VALUE = 1;

    /**

     * Technorati API key

     *

     * @var     string

     * @access  protected

     */

    protected $_apiKey;

    /**

     * Zend_Rest_Client instance

     *

     * @var     Zend_Rest_Client

     * @access  protected

     */

    protected $_restClient;

    /**

     * Constructs a new Zend_Service_Technorati instance

     * and setup character encoding.

     *

     * @param  string $apiKey  Your Technorati API key

     */

    public function __construct($apiKey)

    {

        iconv_set_encoding('output_encoding', 'UTF-8');

        iconv_set_encoding('input_encoding', 'UTF-8');

        iconv_set_encoding('internal_encoding', 'UTF-8');

        $this->_apiKey = $apiKey;

    }

    /**

     * Cosmos query lets you see what blogs are linking to a given URL.

     *

     * On the Technorati site, you can enter a URL in the searchbox and

     * it will return a list of blogs linking to it.

     * The API version allows more features and gives you a way

     * to use the cosmos on your own site.

     *

     * Query options include:

     *

     * 'type'       => (link|weblog)

     *      optional - A value of link returns the freshest links referencing your target URL.

     *      A value of weblog returns the last set of unique weblogs referencing your target URL.

     * 'limit'      => (int)

     *      optional - adjust the size of your result from the default value of 20

     *      to between 1 and 100 results.

     * 'start'      => (int)

     *      optional - adjust the range of your result set.

     *      Set this number to larger than zero and you will receive

     *      the portion of Technorati's total result set ranging from start to start+limit.

     *      The default start value is 1.

     * 'current'    => (true|false)

     *      optional - the default setting of true

     *      Technorati returns links that are currently on a weblog's homepage.

     *      Set this parameter to false if you would like to receive all links

     *      to the given URL regardless of their current placement on the source blog.

     *      Internally the value is converted in (yes|no).

     * 'claim'      => (true|false)

     *      optional - the default setting of FALSE returns no user information

     *      about each weblog included in the result set when available.

     *      Set this parameter to FALSE to include Technorati member data

     *      in the result set when a weblog in your result set

     *      has been successfully claimed by a member of Technorati.

     *      Internally the value is converted in (int).

     * 'highlight'  => (true|false)

     *      optional - the default setting of TRUE

     *      highlights the citation of the given URL within the weblog excerpt.

     *      Set this parameter to FALSE to apply no special markup to the blog excerpt.

     *      Internally the value is converted in (int).

     *

     * @param   string $url     the URL you are searching for. Prefixes http:// and www. are optional.

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_CosmosResultSet

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/cosmos.html Technorati API: Cosmos Query reference

     */

    public function cosmos($url, $options = null)

    {

        static $defaultOptions = array( 'type'      => 'link',

                                        'start'     => 1,

                                        'limit'     => 20,

                                        'current'   => 'yes',

                                        'format'    => 'xml',

                                        'claim'     => 0,

                                        'highlight' => 1,

                                        );

        $options['url'] = $url;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateCosmos($options);

        $response = $this->_makeRequest(self::API_PATH_COSMOS, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_CosmosResultSet

         */

        require_once 'Zend/Service/Technorati/CosmosResultSet.php';

        return new Zend_Service_Technorati_CosmosResultSet($dom, $options);

    }

    /**

     * Search lets you see what blogs contain a given search string.

     *

     * Query options include:

     *

     * 'language'   => (string)

     *      optional - a ISO 639-1 two character language code

     *      to retrieve results specific to that language.

     *      This feature is currently beta and may not work for all languages.

     * 'authority'  => (n|a1|a4|a7)

     *      optional - filter results to those from blogs with at least

     *      the Technorati Authority specified.

     *      Technorati calculates a blog's authority by how many people link to it.

     *      Filtering by authority is a good way to refine your search results.

     *      There are four settings:

     *      - n  => Any authority: All results.

     *      - a1 => A little authority: Results from blogs with at least one link.

     *      - a4 => Some authority: Results from blogs with a handful of links.

     *      - a7 => A lot of authority: Results from blogs with hundreds of links.

     * 'limit'      => (int)

     *      optional - adjust the size of your result from the default value of 20

     *      to between 1 and 100 results.

     * 'start'      => (int)

     *      optional - adjust the range of your result set.

     *      Set this number to larger than zero and you will receive

     *      the portion of Technorati's total result set ranging from start to start+limit.

     *      The default start value is 1.

     * 'claim'      => (true|false)

     *      optional - the default setting of FALSE returns no user information

     *      about each weblog included in the result set when available.

     *      Set this parameter to FALSE to include Technorati member data

     *      in the result set when a weblog in your result set

     *      has been successfully claimed by a member of Technorati.

     *      Internally the value is converted in (int).

     *

     * @param   string $query   the words you are searching for.

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_SearchResultSet

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/search.html Technorati API: Search Query reference

     */

    public function search($query, $options = null)

    {

        static $defaultOptions = array( 'start'     => 1,

                                        'limit'     => 20,

                                        'format'    => 'xml',

                                        'claim'     => 0);

        $options['query'] = $query;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateSearch($options);

        $response = $this->_makeRequest(self::API_PATH_SEARCH, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_SearchResultSet

         */

        require_once 'Zend/Service/Technorati/SearchResultSet.php';

        return new Zend_Service_Technorati_SearchResultSet($dom, $options);

    }

    /**

     * Tag lets you see what posts are associated with a given tag.

     *

     * Query options include:

     *

     * 'limit'          => (int)

     *      optional - adjust the size of your result from the default value of 20

     *      to between 1 and 100 results.

     * 'start'          => (int)

     *      optional - adjust the range of your result set.

     *      Set this number to larger than zero and you will receive

     *      the portion of Technorati's total result set ranging from start to start+limit.

     *      The default start value is 1.

     * 'excerptsize'    => (int)

     *      optional - number of word characters to include in the post excerpts.

     *      By default 100 word characters are returned.

     * 'topexcerptsize' => (int)

     *      optional - number of word characters to include in the first post excerpt.

     *      By default 150 word characters are returned.

     *

     * @param   string $tag     the tag term you are searching posts for.

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_TagResultSet

     * @throws  Zend_Service_Technorati_Exception

     *  @link    http://technorati.com/developers/api/tag.html Technorati API: Tag Query reference

     */

    public function tag($tag, $options = null)

    {

        static $defaultOptions = array( 'start'          => 1,

                                        'limit'          => 20,

                                        'format'         => 'xml',

                                        'excerptsize'    => 100,

                                        'topexcerptsize' => 150);

        $options['tag'] = $tag;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateTag($options);

        $response = $this->_makeRequest(self::API_PATH_TAG, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_TagResultSet

         */

        require_once 'Zend/Service/Technorati/TagResultSet.php';

        return new Zend_Service_Technorati_TagResultSet($dom, $options);

    }

    /**

     * TopTags provides daily counts of posts containing the queried keyword.

     *

     * Query options include:

     *

     * 'days'       => (int)

     *      optional - Used to specify the number of days in the past

     *      to request daily count data for.

     *      Can be any integer between 1 and 180, default is 180

     *

     * @param   string $q       the keyword query

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_DailyCountsResultSet

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/dailycounts.html Technorati API: DailyCounts Query reference

     */

    public function dailyCounts($query, $options = null)

    {

        static $defaultOptions = array( 'days'      => 180,

                                        'format'    => 'xml'

                                        );

        $options['q'] = $query;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateDailyCounts($options);

        $response = $this->_makeRequest(self::API_PATH_DAILYCOUNTS, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_DailyCountsResultSet

         */

        require_once 'Zend/Service/Technorati/DailyCountsResultSet.php';

        return new Zend_Service_Technorati_DailyCountsResultSet($dom);

    }

    /**

     * TopTags provides information on top tags indexed by Technorati.

     *

     * Query options include:

     *

     * 'limit'      => (int)

     *      optional - adjust the size of your result from the default value of 20

     *      to between 1 and 100 results.

     * 'start'      => (int)

     *      optional - adjust the range of your result set.

     *      Set this number to larger than zero and you will receive

     *      the portion of Technorati's total result set ranging from start to start+limit.

     *      The default start value is 1.

     *

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_TagsResultSet

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/toptags.html Technorati API: TopTags Query reference

     */

    public function topTags($options = null)

    {

        static $defaultOptions = array( 'start'     => 1,

                                        'limit'     => 20,

                                        'format'    => 'xml'

                                        );

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateTopTags($options);

        $response = $this->_makeRequest(self::API_PATH_TOPTAGS, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_TagsResultSet

         */

        require_once 'Zend/Service/Technorati/TagsResultSet.php';

        return new Zend_Service_Technorati_TagsResultSet($dom);

    }

    /**

     * BlogInfo provides information on what blog, if any, is associated with a given URL.

     *

     * @param   string $url     the URL you are searching for. Prefixes http:// and www. are optional.

     *                          The URL must be recognized by Technorati as a blog.

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_BlogInfoResult

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/bloginfo.html Technorati API: BlogInfo Query reference

     */

    public function blogInfo($url, $options = null)

    {

        static $defaultOptions = array( 'format'    => 'xml'

                                        );

        $options['url'] = $url;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateBlogInfo($options);

        $response = $this->_makeRequest(self::API_PATH_BLOGINFO, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_BlogInfoResult

         */

        require_once 'Zend/Service/Technorati/BlogInfoResult.php';

        return new Zend_Service_Technorati_BlogInfoResult($dom);

    }

    /**

     * BlogPostTags provides information on the top tags used by a specific blog.

     *

     * Query options include:

     *

     * 'limit'      => (int)

     *      optional - adjust the size of your result from the default value of 20

     *      to between 1 and 100 results.

     * 'start'      => (int)

     *      optional - adjust the range of your result set.

     *      Set this number to larger than zero and you will receive

     *      the portion of Technorati's total result set ranging from start to start+limit.

     *      The default start value is 1.

     *      Note. This property is not documented.

     *

     * @param   string $url     the URL you are searching for. Prefixes http:// and www. are optional.

     *                          The URL must be recognized by Technorati as a blog.

     * @param   array $options  additional parameters to refine your query

     * @return  Zend_Service_Technorati_TagsResultSet

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/blogposttags.html Technorati API: BlogPostTags Query reference

     */

    public function blogPostTags($url, $options = null)

    {

        static $defaultOptions = array( 'start'     => 1,

                                        'limit'     => 20,

                                        'format'    => 'xml'

                                        );

        $options['url'] = $url;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateBlogPostTags($options);

        $response = $this->_makeRequest(self::API_PATH_BLOGPOSTTAGS, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_TagsResultSet

         */

        require_once 'Zend/Service/Technorati/TagsResultSet.php';

        return new Zend_Service_Technorati_TagsResultSet($dom);

    }

    /**

     * GetInfo query tells you things that Technorati knows about a member.

     *

     * The returned info is broken up into two sections:

     * The first part describes some information that the user wants

     * to allow people to know about him- or herself.

     * The second part of the document is a listing of the weblogs

     * that the user has successfully claimed and the information

     * that Technorati knows about these weblogs.

     *

     * @param   string $username    the Technorati user name you are searching for

     * @param   array $options      additional parameters to refine your query

     * @return  Zend_Service_Technorati_GetInfoResult

     * @throws  Zend_Service_Technorati_Exception

     * @link    http://technorati.com/developers/api/getinfo.html Technorati API: GetInfo reference

     */

    public function getInfo($username, $options = null)

    {

        static $defaultOptions = array('format' => 'xml');

        $options['username'] = $username;

        $options = $this->_prepareOptions($options, $defaultOptions);

        $this->_validateGetInfo($options);

        $response = $this->_makeRequest(self::API_PATH_GETINFO, $options);

        $dom = $this->_convertResponseAndCheckContent($response);

        /**

         * @see Zend_Service_Technorati_GetInfoResult

         */

        require_once 'Zend/Service/Technorati/GetInfoResult.php';

        return new Zend_Service_Technorati_GetInfoResult($dom);

    }

    /**

     * KeyInfo query provides information on daily usage of an API key.

     * Key Info Queries do not count against a key's daily query limit.