documentation

README

@@ -2,4 +2,8 @@ Yahoo BOSS (Build your Own Search Service) is a free search API. This package ca
 
 Requires PHP 5.3 with allow_url_fopen=on
 
-For usage see example.php or the phpDoc documentation
+For usage see example.php, YahooBossClient/README.TXT or the phpDoc documentation
+
+The BOSS API reference can be found here:
+
+http://developer.yahoo.com/search/boss/boss_guide/index.html

YahooBossClient/README.TXT

@@ -0,0 +1,188 @@
++-----------------------------------------------------------------------------+
+|                            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!