Yahoo Search API Client (BOSS): Perform Web searches using the Yahoo BOSS API

+-----------------------------------------------------------------------------+
|                            Yahoo BOSS Client                                |
+-----------------------------------------------------------------------------+

- Synopsis
- Requirements
- Files
- Step-by-Step Usage
- Extending

Synopsis
--------
Yahoo BOSS (Build your Own Search Service) is a free search API. This package
can retrieve results of web, news and image search and also cache them.


Requirements
------------
The package requires PHP 5.3.0 or later with ini setting allow_url_fopen.

To use the package, just include YBC.lib.php

You will need a BOSS AppId from Yahoo. Get one for free at:

	http://developer.yahoo.com/boss


Files
-----
readme.txt - the file you are reading right now
license.txt - BSD license
YBC.lib.php - library loader, include this file to use the package
example.php - example: simple demonstration
YBC/AbstractQuery.php - class file: base class for queries
YBC/AbstractResult.php - class file: base class for result
YBC/Cache.php - class file: cache interface
YBC/CacheException.php - class file: cache exception
YBC/Client.php - class file: main class
YBC/FileCache.php - class file: a filesystem based implementation of cache
YBC/ImagesQuery.php - class file: class for image search queries
YBC/ImagesResult.php - class file: class for image search results
YBC/NewsQuery.php - class file: class for news search queries
YBC/NewsResult.php - class file: class for news search results
YBC/NullCache.php - class file: dummy implementation of cache
YBC/Query.php - class file: query interface
YBC/ResultSet.php - class file: class for the whole result
YBC/WebQuery.php - class file: class for web search queries
YBC/WebResult.php - class file: class for web search results


Step-by-Step Usage
------------------

To initialize the client write

	$ybc = new YBC\Client(APPID);

where APPID is your BOSS AppId (see: http://developer.yahoo.com/boss)

If you want to use the cache, instantiate a cache object and provide it to the
client constructor

	$dir = '/tmp/ybc-cache';
	$cache = new YBC\FileCache($dir);
	$ybc = new YBC\Client(APPID, $cache);

$dir must be the absolute path to an existing writable directory. By default it
is '../cache' relative to the YBC class directory. You can also use your own
caching mechanism (see: Extending)

A query is generated like this:

	$webQuery = new YBC\WebQuery('search term');
	$newsQuery = new YBC\NewsQuery('search term');
	$imagesQuery = new YBC\ImagesQuery('search term');

To determine how many result are shown and beginning from which offset, use
setLimit(), for example to retrieve the first five results (preset is 0,10):

	$webQuery->setLimit(0,5);

To determine a region and language, use setLocale(), which allows different
parameters (preset is 'us-en'):

a) single key:

	$webQuery->setLocale('de'); // region 'de', language 'de'

b) combined key:

	$webQuery->setLocale('us-en'); // region 'us', language 'en'

c) class constant:

	$webQuery->setLocale(YBC\AbstractQuery::LOCALE_HONG_KONG // region 'hk', language 'tzh'

Additionaly you can enforce strict language checking with setStrictLang()

	$webQuery->setStrictLang(true);

To search only selected sites, use setSites() or addSite():

	$webQuery->setSites(array('github.com', 'phpclasses.org');
	$webQuery->addSite('sgh-it.eu');

By default, the search term gets surrounded with <b>-Tags in title and
description of the result. To turn this off, use setRawStyle():

	$webQuery->setRawStyle(true);

These options are available in all query objects (web, news, images). But there
are many more options for each query type, for example:

	// longer preview text:
	$webQuery->setLongAbstract(true);
	// include number of saves in delicious:
	$webQuery->setDeliciousSavesView(true);

	// get only news from the last 2 days:
	$newsQuery->setAge('2d');
	// order news results by date:
	$newsQuery->setOrderBy(YBC\NewsQuery::ORDERBY_DATE);

	// get only images of wallpaper sizes:
	$imagesQuery->setDimensions(YBC\ImagesQuery::DIMENSIONS_WALLPAPER);
	// deactivate filter for offensive content:
	$imagesQuery->setFilter(false);

For all the options see phpDoc comments of YBC\WebQuery, YBC\ImagesQuery and
YBC\NewsQuery

It is also useful to read the BOSS API Guide to see what is possible within BOSS

	http://developer.yahoo.com/search/boss/boss_guide/index.html

Tip: The query object has a fluent interface, you also can write something like:

	$webQuery->setLimit(10,10)->setLongAbstract(true);

After instantiating and if necessary configuring the query object you can
execute the query like so:

	$resultSet = $ybc->query($webQuery);

The returned YBC\ResultSet object is an iterator over YBC\WebResult and provides
some additional infos, for example the total number of hits and a query object
for the next page:

	$totalHits = $resultSet->getTotalhits();
	$nextQuery = $resultSet->getNextpageQuery(); 

To iterate over the results, just use foreach. The result attributes can be
accessed directly:

	foreach($resultSet as $result) {
		echo <<<EOT
<div>
	<h2>$result->title</h2>
	<p>$result->abstract</p>
	<p><a href="$result->clickurl">$result->url</a></p>
	<p>$result->date</p>
</div>
EOT;
	}

For a complete reference about the result classes see phpDoc comments of
YBC\ResultSet, YBC\WebResult, YBC\ImagesResult and YBC\NewsResult. Also -again-
it may be helpful to read the BOSS API Guide.

	http://developer.yahoo.com/search/boss/boss_guide/index.html

Now just go and try it out :-)


Extending
---------

As mentioned above, you can easily implement your own caching mechanisms, i.e.
a MySQL based cache. Just implement the YBC\Cache interface (see YBC/Cache.php)

Note that the get() and delete() methods expect Query objects as parameters. In
the FileCache implementation a hash of the object is used as identifier, which
should work out pretty good:

	$id = md5(serialize($query));

The spl_object_hash() function is NOT appliable here because it only hashes the
object id to identify an object at runtime!