README

#Bookboon API PHP 类

PHP 类是 Bookboon.com API 的包装器。因为这是一个包装器类，所以在使用之前你应该熟悉 REST API。

##使用方法

要使用 Bookboon API，你需要一个应用程序 ID 和密钥（如下面的 $API_ID 和 $API_SECRET），请参阅 API 页面 获取详细信息。通过 composer 安装

composer require bookboon/api

如果不使用 composer，可以使用任何 PSR-0 兼容的自动加载器，或者手动要求每个文件。

获取书籍的最简单方法就是使用 getBook 方法

$bookboon = new Bookboon($API_ID, $API_SECRET, array(/*optional named array to set request headers*/));
$book = $bookboon->getBook("BOOK_GUID");

这将返回一个具有每个属性公共获取器的 Book 对象。还有许多其他的简单获取函数

$category = $bookboon->getCategory("CATEGORY_GUID"); // return Category object
$reviews = $bookboon->getReviews("BOOK_GUID"); // return array of Review
$search = $bookboon->getSearch("query text"); // return array of Book
$recommendations = $bookboon->getRecommendations(array("BOOK_ID_1", "BOOK_ID_2"); // return array of Book
$questions = $bookboon->getQuestions(); // return array of Question

最后，你可以下载书籍，通常如下所示，你需要为每个唯一的用户发送一个唯一的用户标识符 handle（例如用户 ID、电子邮件）

$url = $bookboon->getBookDownloadUrl("BOOK_GUID", array("handle" => "user@email"));
// Send the $url in a redirect header to the user

重要：请不要存储此值，因为它将不断更改。

使用 api 原始数据

您还可以使用 api 方法从 API 获取数据库。要向 API 传递变量，请使用 api 函数发送一个包含 api 的数组

/* The bacon-loving student */
$vars = array('post' => array( 'answer[0]' => '6230e12c-68d8-45d5-8f02-1d3997713150',
			  			       'answer[1]' => '5aca0fe1-0d93-41b1-8691-aa242a526f17'
							 )
			 );
							
$bookboon->api('/questions', $vars);

注意：为了让 PHP 类更加灵活，您需要告诉它是否使用 POST 或 GET 方法传递变量。api 函数仅接受名为 'post' 和 'get' 的键，并将它们各自的数组解析为正确的查询字符串。

##结果

api 方法的结果是来自 API 的直接数据 json 解码数组，如果您使用其他任何方法（getbooks、getCategories 等），则将返回适当的对象。

##异常

包装器将抛出几种不同的异常。如果 API 响应未处理的 HTTP 状态，例如如果缺少变量（403）、提交的数据格式不正确（400）或未知 API 错误（500），则可能需要捕获这些错误，如下所示

$bookboon = new Bookboon($API_ID, $API_SECRET);

try {
	print_r($bookboon->api('/recommendations', array(
        'get' => array(
            'books' => $book_id
        )));
} 
catch (NotFoundException $e) {
    // handle exception here
}

目前我们抛出以下异常

ApiSyntaxException - 通常缺少或格式不正确的参数
AuthenticationException - 凭证无效
GeneralApiException - 当发生某些未知错误时，请向我们报告此问题
NotFoundException - API 返回未找到状态（404）

##缓存

包装器类提供了一个用于加速 GET 查询的缓存接口。目前仅实现了 memcached。要设置缓存提供程序，请使用 setCache 方法

$bookboon->setCache(new \Bookboon\Api\Memcached($server, $port, $timeToLive));

要实现自己的提供者缓存软件，请确保您的接口实现了 \Bookboon\Api\Cache。它只有三个方法：save、get和delete，因此应该足够简单易行。