|
|
@@ -5,50 +5,66 @@
|
|
|
|
|
|
<sect2 id="zend.service.technorati.introduction">
|
|
|
<title>Introduction</title>
|
|
|
+
|
|
|
<para>
|
|
|
- <classname>Zend_Service_Technorati</classname> provides an easy, intuitive and object-oriented interface for using
|
|
|
- the Technorati <acronym>API</acronym>. It provides access to all available
|
|
|
- <ulink url="http://technorati.com/developers/api/">Technorati <acronym>API</acronym> queries</ulink>
|
|
|
- and returns the original <acronym>XML</acronym> response as a friendly <acronym>PHP</acronym> object.
|
|
|
+ <classname>Zend_Service_Technorati</classname> provides an easy, intuitive and
|
|
|
+ object-oriented interface for using the Technorati <acronym>API</acronym>. It provides
|
|
|
+ access to all available <ulink url="http://technorati.com/developers/api/">Technorati
|
|
|
+ <acronym>API</acronym> queries</ulink> and returns the original <acronym>XML</acronym>
|
|
|
+ response as a friendly <acronym>PHP</acronym> object.
|
|
|
</para>
|
|
|
+
|
|
|
<para>
|
|
|
- <ulink url="http://technorati.com/">Technorati</ulink> is one of the most popular blog search engines.
|
|
|
- The <acronym>API</acronym> interface enables developers to retrieve information about a specific blog, search blogs matching a
|
|
|
- single tag or phrase and get information about a specific author (blogger). For a full list of available
|
|
|
- queries please see the
|
|
|
- <ulink url="http://technorati.com/developers/api/">Technorati <acronym>API</acronym> documentation</ulink>
|
|
|
- or the <link linkend="zend.service.technorati.queries">Available Technorati queries</link> section of this
|
|
|
- document.
|
|
|
+ <ulink url="http://technorati.com/">Technorati</ulink> is one of the most popular blog
|
|
|
+ search engines. The <acronym>API</acronym> interface enables developers to retrieve
|
|
|
+ information about a specific blog, search blogs matching a single tag or phrase and get
|
|
|
+ information about a specific author (blogger). For a full list of available queries
|
|
|
+ please see the <ulink url="http://technorati.com/developers/api/">Technorati
|
|
|
+ <acronym>API</acronym> documentation</ulink> or the <link
|
|
|
+ linkend="zend.service.technorati.queries">Available Technorati queries</link>
|
|
|
+ section of this document.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="zend.service.technorati.getting-started">
|
|
|
<title>Getting Started</title>
|
|
|
+
|
|
|
<para>
|
|
|
- Technorati requires a valid <acronym>API</acronym> key for usage. To get your own <acronym>API</acronym> Key you first need to
|
|
|
- <ulink url="http://technorati.com/signup/">create a new Technorati account</ulink>, then visit the
|
|
|
- <ulink url="http://technorati.com/developers/apikey.html">API Key section</ulink>.
|
|
|
+ Technorati requires a valid <acronym>API</acronym> key for usage. To get your own
|
|
|
+ <acronym>API</acronym> Key you first need to <ulink
|
|
|
+ url="http://technorati.com/signup/">create a new Technorati account</ulink>, then
|
|
|
+ visit the <ulink url="http://technorati.com/developers/apikey.html">API Key
|
|
|
+ section</ulink>.
|
|
|
</para>
|
|
|
+
|
|
|
<note>
|
|
|
<title>API Key limits</title>
|
|
|
+
|
|
|
<para>
|
|
|
- You can make up to 500 Technorati <acronym>API</acronym> calls per day, at no charge.
|
|
|
- Other usage limitations may apply, depending on the current Technorati <acronym>API</acronym> license.
|
|
|
+ You can make up to 500 Technorati <acronym>API</acronym> calls per day, at no
|
|
|
+ charge. Other usage limitations may apply, depending on the current Technorati
|
|
|
+ <acronym>API</acronym> license.
|
|
|
</para>
|
|
|
</note>
|
|
|
+
|
|
|
<para>
|
|
|
- Once you have a valid <acronym>API</acronym> key, you're ready to start using <classname>Zend_Service_Technorati</classname>.
|
|
|
+ Once you have a valid <acronym>API</acronym> key, you're ready to start using
|
|
|
+ <classname>Zend_Service_Technorati</classname>.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="zend.service.technorati.making-first-query">
|
|
|
<title>Making Your First Query</title>
|
|
|
+
|
|
|
<para>
|
|
|
- In order to run a query, first you need a <classname>Zend_Service_Technorati</classname> instance with a valid <acronym>API</acronym>
|
|
|
- key. Then choose one of the available query methods, and call it providing required arguments.
|
|
|
+ In order to run a query, first you need a <classname>Zend_Service_Technorati</classname>
|
|
|
+ instance with a valid <acronym>API</acronym> key. Then choose one of the available query
|
|
|
+ methods, and call it providing required arguments.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.making-first-query.example-1">
|
|
|
<title>Sending your first query</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -58,11 +74,15 @@ $technorati = new Zend_Service_Technorati('VALID_API_KEY');
|
|
|
$resultSet = $technorati->search('PHP');
|
|
|
]]></programlisting>
|
|
|
</example>
|
|
|
+
|
|
|
<para>
|
|
|
- Each query method accepts an array of optional parameters that can be used to refine your query.
|
|
|
+ Each query method accepts an array of optional parameters that can be used to refine
|
|
|
+ your query.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.making-first-query.example-2">
|
|
|
<title>Refining your query</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -76,13 +96,16 @@ $options = array('authority' => 'a4');
|
|
|
$resultSet = $technorati->search('PHP', $options);
|
|
|
]]></programlisting>
|
|
|
</example>
|
|
|
+
|
|
|
<para>
|
|
|
- A <classname>Zend_Service_Technorati</classname> instance is not a single-use object. That is, you don't need to
|
|
|
- create a new instance for each query call; simply use your current <classname>Zend_Service_Technorati</classname>
|
|
|
- object as long as you need it.
|
|
|
+ A <classname>Zend_Service_Technorati</classname> instance is not a single-use object.
|
|
|
+ That is, you don't need to create a new instance for each query call; simply use your
|
|
|
+ current <classname>Zend_Service_Technorati</classname> object as long as you need it.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.making-first-query.example-3">
|
|
|
<title>Sending multiple queries with the same Zend_Service_Technorati instance</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -99,18 +122,24 @@ $topTags = $technorati->topTags();
|
|
|
|
|
|
<sect2 id="zend.service.technorati.consuming-results">
|
|
|
<title>Consuming Results</title>
|
|
|
+
|
|
|
<para>
|
|
|
You can get one of two types of result object in response to a query.
|
|
|
</para>
|
|
|
+
|
|
|
<para>
|
|
|
- The first group is represented by <classname>Zend_Service_Technorati_*ResultSet</classname> objects. A result set
|
|
|
- object is basically a collection of result objects. It extends the basic
|
|
|
- <classname>Zend_Service_Technorati_ResultSet</classname> class and implements the <code>SeekableIterator</code> <acronym>PHP</acronym>
|
|
|
- interface. The best way to consume a result set object is to loop over it with the <acronym>PHP</acronym> <code>foreach</code>
|
|
|
- statement.
|
|
|
+ The first group is represented by
|
|
|
+ <classname>Zend_Service_Technorati_*ResultSet</classname> objects. A result set object
|
|
|
+ is basically a collection of result objects. It extends the basic
|
|
|
+ <classname>Zend_Service_Technorati_ResultSet</classname> class and implements the
|
|
|
+ <code>SeekableIterator</code> <acronym>PHP</acronym> interface. The best way to consume
|
|
|
+ a result set object is to loop over it with the <acronym>PHP</acronym>
|
|
|
+ <code>foreach</code> statement.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.consuming-results.example-1">
|
|
|
<title>Consuming a result set object</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -126,12 +155,16 @@ foreach ($resultSet as $result) {
|
|
|
}
|
|
|
]]></programlisting>
|
|
|
</example>
|
|
|
+
|
|
|
<para>
|
|
|
- Because <classname>Zend_Service_Technorati_ResultSet</classname> implements the <code>SeekableIterator</code>
|
|
|
- interface, you can seek a specific result object using its position in the result collection.
|
|
|
+ Because <classname>Zend_Service_Technorati_ResultSet</classname> implements the
|
|
|
+ <code>SeekableIterator</code> interface, you can seek a specific result object using its
|
|
|
+ position in the result collection.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.consuming-results.example-2">
|
|
|
<title>Seeking a specific result set object</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -146,20 +179,27 @@ $resultSet->seek(1);
|
|
|
$result = $resultSet->current();
|
|
|
]]></programlisting>
|
|
|
</example>
|
|
|
+
|
|
|
<note>
|
|
|
<para>
|
|
|
- <code>SeekableIterator</code> works as an array and counts positions starting from index 0. Fetching
|
|
|
- position number 1 means getting the second result in the collection.
|
|
|
+ <code>SeekableIterator</code> works as an array and counts positions starting from
|
|
|
+ index 0. Fetching position number 1 means getting the second result in the
|
|
|
+ collection.
|
|
|
</para>
|
|
|
</note>
|
|
|
+
|
|
|
<para>
|
|
|
The second group is represented by special standalone result objects.
|
|
|
- <classname>Zend_Service_Technorati_GetInfoResult</classname>, <classname>Zend_Service_Technorati_BlogInfoResult</classname> and
|
|
|
- <classname>Zend_Service_Technorati_KeyInfoResult</classname> act as wrappers for additional objects, such as
|
|
|
- <classname>Zend_Service_Technorati_Author</classname> and <classname>Zend_Service_Technorati_Weblog</classname>.
|
|
|
+ <classname>Zend_Service_Technorati_GetInfoResult</classname>,
|
|
|
+ <classname>Zend_Service_Technorati_BlogInfoResult</classname> and
|
|
|
+ <classname>Zend_Service_Technorati_KeyInfoResult</classname> act as wrappers for
|
|
|
+ additional objects, such as <classname>Zend_Service_Technorati_Author</classname> and
|
|
|
+ <classname>Zend_Service_Technorati_Weblog</classname>.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.consuming-results.example-3">
|
|
|
<title>Consuming a standalone result object</title>
|
|
|
+
|
|
|
<programlisting language="php"><![CDATA[
|
|
|
// create a new Zend_Service_Technorati
|
|
|
// with a valid API_KEY
|
|
|
@@ -178,31 +218,40 @@ foreach ($result->getWeblogs() as $weblog) {
|
|
|
echo "</ol>";
|
|
|
]]></programlisting>
|
|
|
</example>
|
|
|
+
|
|
|
<para>
|
|
|
- Please read the <link linkend="zend.service.technorati.classes">Zend_Service_Technorati Classes</link>
|
|
|
- section for further details about response classes.
|
|
|
+ Please read the <link linkend="zend.service.technorati.classes">Zend_Service_Technorati
|
|
|
+ Classes</link> section for further details about response classes.
|
|
|
</para>
|
|
|
-
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="zend.service.technorati.handling-errors">
|
|
|
<title>Handling Errors</title>
|
|
|
+
|
|
|
<para>
|
|
|
Each <classname>Zend_Service_Technorati</classname> query method throws a
|
|
|
- <classname>Zend_Service_Technorati_Exception</classname> exception on failure with a meaningful error message.
|
|
|
+ <classname>Zend_Service_Technorati_Exception</classname> exception on failure with a
|
|
|
+ meaningful error message.
|
|
|
</para>
|
|
|
+
|
|
|
<para>
|
|
|
- There are several reasons that may cause a <classname>Zend_Service_Technorati</classname> query to fail.
|
|
|
- <classname>Zend_Service_Technorati</classname> validates all parameters for any query request. If a parameter is
|
|
|
- invalid or it contains an invalid value, a new <classname>Zend_Service_Technorati_Exception</classname> exception is
|
|
|
- thrown. Additionally, the Technorati <acronym>API</acronym> interface could be temporally unavailable, or it could return a
|
|
|
- response that is not well formed.
|
|
|
+ There are several reasons that may cause a
|
|
|
+ <classname>Zend_Service_Technorati</classname> query to fail.
|
|
|
+ <classname>Zend_Service_Technorati</classname> validates all parameters for any query
|
|
|
+ request. If a parameter is invalid or it contains an invalid value, a new
|
|
|
+ <classname>Zend_Service_Technorati_Exception</classname> exception is thrown.
|
|
|
+ Additionally, the Technorati <acronym>API</acronym> interface could be temporally
|
|
|
+ unavailable, or it could return a response that is not well formed.
|
|
|
</para>
|
|
|
+
|
|
|
<para>
|
|
|
- You should always wrap a Technorati query with a <code>try</code>...<code>catch</code> block.
|
|
|
+ You should always wrap a Technorati query with a <code>try</code>...<code>catch</code>
|
|
|
+ block.
|
|
|
</para>
|
|
|
+
|
|
|
<example id="zend.service.technorati.handling-errors.example-1">
|
|
|
<title>Handling a Query Exception</title>
|
|
|
+
|
|
|
<programlisting language="php"><
thomas