View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFDEV:Zend Proposal Zone Template}

{zone-data:component-name}
Zend_Service_Technorati
{zone-data}

{zone-data:proposer-list}
[Simone Carletti|mailto:weppos@weppos.net]
[Darby Felton|mailto:darby@zend.com], Zend liaison
{zone-data}

{zone-data:revision}
1.0 - 4 February 2007: Proposal draft.
2.0 - 13 November 2007: Proposal approved, updated details.
{zone-data}

{zone-data:overview}
Zend_Service_Technorati provides an easy, intuitive and object oriented interface for using [Technorati APIs|http://technorati.com/developers/api/].

Each API call has a 1:1 method in the Zend_Service_Technorati class.
Convenient methods may be created in order to make developer's life easier.
{zone-data}

{zone-data:references}
* [Technorati API|http://technorati.com/developers/api/]
* [Technorati API (old wiki pages)|http://developers.technorati.com/wiki]
{zone-data}

{zone-data:requirements}
* This component *will* implement all available Technorati API calls with 1:1 naming convention.
* This component *will* implement not-documented API calls from useful API services, for example KeyInfo.
* This component *will* implement convenient calls to access complex data or properties.
* This component *will* parse and return server responses as intuitive data objects.
{zone-data}

{zone-data:dependencies}
* Zend_Service_Exception
* Zend_Rest_Client
* Zend_Uri
* Zend_Date
{zone-data}

{zone-data:operation}
An instance of Zend_Service_Technorati object is created, with an unique Technorati API Key.
After that, you can use this instance to query Technorati search index with one of available Zend_Service_Technorati API methods.

Depending on query type, developer *MUST* provide mandatory parameters required by Technorati.
Optional parameters *MAY* be provided using an associative array.
{zone-data}

{zone-data:milestones}
Milestone 0: \[DONE\] develop release 0.1 alpha for testing
Milestone 1: \[DONE\] write component proposal
Milestone 2: \[DONE\] proposal acceptance
Milestone 3: \[DONE\] import release 0.1 alpha to incubator/lab svn
Milestone 4: \[DONE\] class development and improvements
Milestone 5: \[DONE\] write unit tests and debugging
Milestone 6: \[DONE\] write documentation
{zone-data}

{zone-data:class-list}
* Zend_Service_Technorati - core class
* Zend_Service_Technorati_ResultSet - a base result set
* Zend_Service_Technorati_Result - a base result
* Zend_Service_Technorati_CosmosResultSet - a Cosmos query result set
* Zend_Service_Technorati_CosmosResult - a Cosmos query result
* ...
* Zend_Service_Technorati_Author - each weblog has zero or more authors
* Zend_Service_Technorati_Weblog - some queries returns weblog object along with other data
* Zend_Service_Technorati_Key - a Technorati key, used for KeyInfo() query

_Note. Due to Technorati API responses, each query should have a specific result set and result class._
{zone-data}

{zone-data:use-cases}
||UC-01||

*Create a Zend_Service_Technorati instance*

{code}
include 'Zend/Service/Technorati.php';

$t = new Zend_Service_Technorati('YOUR_API_KEY');
{code}


||UC-02||

*Retrieve key info*

{code}
include 'Zend/Service/Technorati.php';

$t = new Zend_Service_Technorati('YOUR_API_KEY');
$myKey = $t->keyInfo();

print( 'You used ' . $myKey->apiQueries .
' of your ' . $myKey->maxQueries . ' queries per day.'
);
{code}


||UC-03||

*Retrieve Cosmos with default options, URL www.simonecarletti.com/blog*

{code}
include 'Zend/Service/Technorati.php';

$t = new Zend_Service_Technorati('YOUR_API_KEY');
$results = $t->cosmos('www.simonecarletti.com/blog');

print('Cosmos query returned ' . $results->totalResultsReturned . ' results.');
foreach ($results as $result) {
// print_r($result);
print("<h1>{$result->weblog->name}</h1>");
print("<p>{$result->excerpt}</p>");
}
{code}


||UC-04||

*Retrieve Cosmos with custom options, URL www.simonecarletti.com/blog*

{code}
include 'Zend/Service/Technorati.php';

$t = new Zend_Service_Technorati('YOUR_API_KEY');
$results = $t->cosmos('www.simonecarletti.com/blog',
array('limit' => 3, 'type' => 'link', 'claim' => '1'));

print('Cosmos query returned ' . $results->totalResultsReturned . ' results.');
foreach ($results as $result) {
print_r($result);
print("<h1>{$result->weblog->name}</h1>");
print("<p>{$result->excerpt}</p>");
}
{code}


||UC-05||

*Retrieve Cosmos XML response (useful for debugging purpose) with custom options*

{code}
include 'Zend/Service/Technorati.php';

$t = new Zend_Service_Technorati('YOUR_API_KEY');
$results = $t->cosmos('www.simonecarletti.com/blog',
array('limit' => 3, 'type' => 'link', 'claim' => '1'));

print('Cosmos query returned ' . $results->totalResultsReturned . ' results.');

print('<h1>XML response</h1>');
print('<pre>');
print_r(htmlentities($results->getXML()));
print('</pre>')
{code}

{zone-data}

{zone-data:skeletons}

*Core Object*
{code}

/** Zend_Service_Exception */
require_once 'Zend/Service/Exception.php';

/** Zend_Service_Technorati_Result */
require_once 'Zend/Service/Technorati/Result.php';

/** Zend_Service_Technorati_ResultSet */
require_once 'Zend/Service/Technorati/ResultSet.php';

/** Zend_Service_Technorati_CosmosResult */
require_once 'Zend/Service/Technorati/CosmosResult.php';

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

/** Zend_Service_Technorati_Author */
require_once 'Zend/Service/Technorati/Author.php';

/** Zend_Service_Technorati_Key */
require_once 'Zend/Service/Technorati/Key.php';

/** Zend_Service_Technorati_Weblog */
require_once 'Zend/Service/Technorati/Weblog.php';


class Zend_Service_Technorati
{
/** Base Technorati API Uri for Requests */
const URI_BASE = 'http://api.technorati.com';

/**
* Your Technorati API key
*
* @var string
* @access protected
*/
protected $_apiKey;

/**
* Zend_Rest_Client instance
*
* @var Zend_Rest_Client
* @access protected
*/
protected $_restClient;


/**
* Zend_Service_Technorati Constructor, setup character encoding
*
* @param string $apiKey Your Technorati API key
*/
public function __construct($apiKey)
{}


/**
* Cosmos Query
*
* Cosmos 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' => (yes|no)
* 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.
* 'claim' => (int)
* optional - the default setting of 0 returns no user information
* about each weblog included in the result set when available.
* Set this parameter to 1 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.
* 'highlight' => (int)
* optional - the default setting of 1
* highlights the citation of the given URL within the weblog excerpt.
* Set this parameter to 0 to apply no special markup to the blog excerpt.
*
* @param string $url Target URL. Prefixes http:// and www. are optional.
* @param array $options Additional parameters to refine your query
* @return Zend_Service_Technorati_CosmosResultSet Cosmos resultset
* @link http://technorati.com/developers/api/cosmos.html Technorati API: Cosmos Query reference
*/
public function cosmos($url, $options = null)
{}

/**
* Search Query
*
* @todo docblock
* @todo develop function
*
* @param string $query Set this to the words you are searching for.
* Separate words with '+' as usual.
* @param array $options Additional parameters to refine your query
* @return Zend_Service_Technorati_SearchResultSet Search resultset
* @link http://technorati.com/developers/api/search.html Technorati API: Search Query reference
*/
public function search($query, $options = null)
{}

/**
* Tag Query
*
* @todo docblock
* @todo develop function
*
* @param string $tag Set this to the tag term you are searching posts for.
* @param array $options Additional parameters to refine your query
* @return Zend_Service_Technorati_TagResultSet Tag resultset
* @link http://technorati.com/developers/api/tag.html Technorati API: Tag Query reference
*/
public function tag($tag, $options = null)
{}

/**
* KeyInfo Query
*
* @todo docblock
*/
public function keyInfo()
{}


/**
* Return Technorati API key
*
* @return string Technorati API key
*/
public function getApiKey()
{}

/**
* Set Technorati API key
*
* @param string $value Technorati API Key
* @link http://technorati.com/developers/apikey.html How to get your Technorati API Key
* @todo Should this function validate the key?
*/
public function setApiKey($value)
{}


/**
* Validate Cosmos Options
*
* @param array $options
* @throws Zend_Service_Exception
*/
protected function _validateCosmos($options)
{}

/**
* Validate Search Options
*
* @param array $options
* @throws Zend_Service_Exception
* @todo develop function
*/
protected function _validateSearch($options)
{}

/**
* Validate Tag Options
*
* @param array $options
* @throws Zend_Service_Exception
* @todo develop function
*/
protected function _validateTag($options)
{}

/**
* Validate that an option is in a given array
*
* @param string $name Option name
* @param string $value Option value
* @param array $array Array in which to check for the option
* @throws Zend_Service_Exception
*/
protected function _validateInArray($name, $value, $array)
{}

/**
* Check Result for errors
*
* @param DomDocument $dom API response DOM document
* @throws Zend_Service_Exception
* @link http://technorati.com/developers/api/error.html Technorati API: Error response
*/
protected static function _checkErrors(DomDocument $dom)
{}

/**
* Check ReST response for errors
*
* @param Zend_Http_Response $response ReST response
* @throws Zend_Service_Exception
*/
protected static function _checkResponseErrors(Zend_Http_Response $response)
{}

/**
* Checks whether the user options are valid
*
* @param array $options User options
* @param array $validOptions Valid options
* @throws Zend_Service_Exception
*/
protected function _compareOptions($options, $validOptions)
{}

/**
* Prepare options for the request
*
* @param array $options User options
* @param array $defaultOptions Default options
* @return array Merged array of user and default/required options.
*/
protected function _prepareOptions($options, $defaultOptions)
{}
}
{code}

*Author Object*
{code}
class Zend_Service_Technorati_Author
{
/**
* Author first name
*
* @var string
*/
public $firsName;

/**
* Author last name
*
* @var string
*/
public $lastName;

/**
* Technorati account description
*
* @var string
*/
public $description;

/**
* Technorati account biography
*
* @var string
*/
public $bio;

/**
* Technorati account thumbnail picture URL, if any
*
* @var null|Zend_Uri_Http
*/
public $thumbnailPicture;


/**
* Parse the given Author Element
*
* @param DomElement $dom The ReST fragment for this author object
* @todo Check which elements are optional
*/
public function __construct(DomElement $dom)
{}
}
{code}

*Weblog Object*
{code}
class Zend_Service_Technorati_Weblog
{
/**
* Blog name as written in the feed
*
* @var string
*/
public $name;

/**
* Base blog URL
*
* @var Zend_Uri_Http
*/
public $url;

/**
* RSS feed URL, if any
*
* @var null|Zend_Uri_Http
*/
public $rssUrl;

/**
* Atom feed URL, if any
*
* @var null|Zend_Uri_Http
*/
public $atomUrl;

/**
* Number of unique blogs linking this blog
*
* @var int
*/
public $inboundBlogs;

/**
* Number of incoming links to this blog
*
* @var int
*/
public $inboundLinks;

/**
* Technorati rank value for this blog
*
* @var int
*/
public $rank;

/**
* Last blog update timestamp
*
* @var int
*/
public $lastUpdate;

/**
* Blog latitude coordinate
*
* @var float
*/
public $lat;

/**
* Blog longitude coordinate
*
* @var float
*/
public $lon;

/**
* Whether the author who claimed this weblog has a photo
*
* @var int
* @see Zend_Service_Technorati_Author::$thumbnailPicture
*/
public $hasPhoto;

/**
* A list of Zend_Service_Technorati_Author who claimed this blog
*
* @var array
*/
public $authors = array();


/**
* Parse the given Weblog Element
*
* @param DomElement $dom The ReST fragment for this weblog object
*/
public function __construct(DomElement $dom)
{}
}
{code}

*Key Object*
{code}
class Zend_Service_Technorati_Key
{
/**
* Technorati API key
*
* @var string
*/
public $apiKey;

/**
* Number of queries used today
*
* @var string
*/
public $apiQueries;

/**
* Total number of available queries per day
*
* @var string
*/
public $maxQueries;


/**
* Technorati API response document
*
* @var DomDocument
* @access protected
*/
protected $_dom;

/**
* Object for $this->_dom
*
* @var DOMXpath
* @access protected
*/
protected $_xpath;


/**
* Parse the given Weblog Element
*
* @param DomElement $dom
* @param Zend_Service_Technorati $technorati Object that generated the request
*/
public function __construct(DomDocument $dom, $technorati)
{}

/**
* Return the response XML document
*
* @return string The response document converted into XML format
*/
function getXML()
{}
}
{code}

*ResultSet Object*
{code}
class Zend_Service_Technorati_ResultSet implements SeekableIterator
{
/**
* The total number of results available
*
* @var int
*/
public $totalResultsAvailable;

/**
* The number of results in this result set
*
* @var int
*/
public $totalResultsReturned;

/**
* The offset in the total result set of this search set
*
* @var int
*/
public $firstResultPosition;


/**
* A DomNodeList of results
*
* @var DomNodeList
* @access protected
*/
protected $_results;

/**
* Technorati API response document
*
* @var DomDocument
* @access protected
*/
protected $_dom;

/**
* Object for $this->_dom
*
* @var DOMXpath
* @access protected
*/
protected $_xpath;

/**
* Current Item
*
* @var int
* @access protected
*/
protected $_currentItem = 0;


/**
* Parse the search response and retrieve the results for iteration
*
* @param DomDocument $dom The ReST fragment for this object
* @param array $options Query options as associative array
*/
public function __construct(DomDocument $dom, $options = array())
{}


/**
* Total Number of results returned
*
* @return int Total number of results returned
*/
public function totalResults()
{}


/**
* Implement SeekableIterator::current
*
* @return void
* @throws Zend_Service_Exception
*/
public function current()
{}


/**
* Implement SeekableIterator::key
*
* @return int
*/
public function key()
{}


/**
* Implement SeekableIterator::next
*
* @return void
*/
public function next()
{}


/**
* Implement SeekableIterator::rewind
*
* @return bool
*/
public function rewind()
{}


/**
* Implement SeekableIterator::seek
*
* @param int $item
* @return Zend_Service_Technorati_Result
* @throws Zend_Service_Exception
*/
public function seek($item)
{}


/**
* Implement SeekableIterator::valid
*
* @param int $item
* @return bool
*/
public function valid($item = null)
{}

/**
* Return the response XML document
*
* @return string The response document converted into XML format
*/
function getXML()
{}
}
{code}

*Result Object*
{code}
class Zend_Service_Technorati_Result
{
/**
* An associative array of 'fieldName' => 'xmlfieldtag'
*
* @var array
* @access protected
*/
protected $_fields;

/**
* The ReST fragment for this result object
*
* @var DomElement
* @access protected
*/
protected $_result;

/**
* Object for $this->_dom
*
* @var DOMXpath
* @access protected
*/
protected $_xpath;


/**
*
*
* @param DomElement $result The ReST fragment for this object
* @todo docblock
*/
public function __construct(DomElement $result)
{}
}
{code}

*Cosmos ResultSet Object (each service will have its own class)*
{code}
class Zend_Service_Technorati_CosmosResultSet extends Zend_Service_Technorati_ResultSet
{
/**
* Parse the search response and retrieve the results for iteration
*
* @param DomDocument $dom The ReST fragment for this object
* @param array $options Query options as associative array
*/
public function __construct(DomDocument $dom, $options = array())
{}


/**
* Implement SeekableIterator::current and
* overwrites Zend_Service_Technorati_ResultSet::current()
*
* @return Zend_Service_Technorati_CosmosResult Current Zend_Service_Technorati_Cosmos result
*/
public function current()
{}
}
{code}

*Cosmos Result Object (each service will have its own class)*
{code}
class Zend_Service_Technorati_CosmosResult extends Zend_Service_Technorati_Result
{
/**
* @var Zend_Service_Technorati_Blog
* @todo docblock
*/
public $weblog;

/**
* @var
* @todo docblock
*/
public $nearestPermalink;

/**
* @var
* @todo docblock
*/
public $excerpt;

/**
* @var
* @todo docblock
*/
public $linkCreated;

/**
* @var
* @todo docblock
*/
public $linkUrl;


/**
*
*
* @param DomElement $result The ReST fragment for this object
* @todo docblock
*/
public function __construct(DomElement $result)
{}
}
{code}

{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>