Goodreads API PHP Library

This library was originally developed to work with the Goodreads Integration for Joomla extension.·· It encapsulates all the functionality needed to access the public, unauthenticated parts of the Goodreads REST API and it returns data in a hierarchical object format.· This file is licensed separately under the LGPL license so that you can use it freely in any other Goodreads projects you might be developing.

If you find this library useful, please consider making a contribution to support further development.

Download the GoodreadsParser PHP Library (version 1.0) here.
You will need an API key which you can obtain at goodreads.com.

Bug Reports

The code in library is fully documented, so if you are having problems using the library, please read through the documentation on this page and the comment in the code.

If you find a bug, you can submit a bug report in the issue tracker at joomlacode.org.

Documentation

The GoodreadsParser library obtains XML data from the Goodreads API or a local cache and returns a hierarchy of Container and Leaf objects that can be used to easily access the data.

This library only makes GET requests that require an API key.· It does not deal with oauth requests for modifying user data.

Caching Behavior

XML results are cached for performance and to prevent the parser from violating the API terms of use.

File timestamps on the last request file (e.g. "user-last.txt") provide a channel for communication between multiple instances of the parser.· This way, the API request frequency is maintained even if there are multiple instances of the parser.· This mechanism may not achieve the desired result on a multithreaded server, but PHP is limited in this respect.

XML results from the API are cached in files that reflect the API call type, the user ID, bookshelf and the pagination of the result (or as many of those attributes as make sense).· For example, review-12345-read-1-20.xml is the first 20 results from the 'read' bookshelf of user 12345.

Note that this code does not cache the parsed data object, merely the xml results called from the API.· Depending on the application, you may want to cache the actual processed output as well.

Data structures

Container objects have a property for each tag that they contain.· If there are multiple tags· with the same name, then the property will be an array.· Each container· has an xmlAttributes property that contains the tag attributes (if any).

Tags that do not contain other tags are represented by Leaf objects which contain an xmlAttribute array and a value property.

Example Usage

Here is an example XML snippet representative of the results returned by the Goodreads API.

<book>
 <isbn>0803730462</isbn>
 <authors>
 <author>
 <name>John Doe</name>
 <average_rating>3.38</average_rating>
 </author>
 <author>
 <name>Jane Doe</name>
 <average_rating>3.38</average_rating>
 </author>
 </authors>
 <shelves>
 <shelf name="read" />
 <shelf name="young-adult" />
 </shelves>
</book>

The following code example is based on the XML above, assuming the top-level Container object is in the variable 'book':

//print isbn
echo $book->isbn->value;
//print author names
echo $book->authors[0]->name->value . " and " . $book->authors[1]->name->value;
//print shelf names
foreach (GoodreadsParser::asArray($book->shelves->shelf) {
 echo $shelf->xmlAttributes->name;
}

Note the use of the asArray function -- this is needed because if the book were only on one shelf, the object $book->shelves->shelf would not be an array, and would cause a PHP error.