README

#QBank - API2包装器

简介

QBankAPI2Wrapper是一个库，它使您能够轻松地从PHP直接使用QBank API2。无需自行处理连接或解释结果。QBankAPI2Wrapper还提供了包含常用函数的类和方法。

安装

使用composer安装。

"require": {
	"kaigan/qbankapi2wrapper": "~1.3"
}

类库

类库可在http://tools.kaigantbk.se/docs/docs/QBankAPI2Wrapper/找到，或根据需求以PDF形式提供。

用法

实例化和登录

QBankAPI2Wrapper中有许多类，但找到执行QBank API2调用的类相当简单。它们的命名遵循“QBank 功能_API”的约定，其中“功能”指明了该类包含哪些类型的函数。还有一个名为“QBankAPI”的类。它是一个抽象基类，因此不能被实例化。

要实例化API类，最简单的方法是使用“QBankAPIFactory”类。设置后，它可以实例化其他所有API类，随时可以使用。

<?php
	QBankAPIFactory::setup(QBANK_ADDRESS, USERNAME, PASSWORD);
	try {
		$searchAPI = QBankAPIFactory::createAPI(QBankAPIFactory::SearchAPI);
	} catch (QBankAPIException $qae) {
		// Handle the error
	}
?>

请注意，这将调用session_start()并在$_SESSION中存储一个值。

手动方式

如果您想自己处理登录和API类的实例化，当然是可以的。

<?php
	$searchAPI = new QBankSearchAPI(QBANK_ADDRESS);
	if ($objectAPI->login(USERNAME, PASSWORD) !== true) {
		// Handle faulty login
	} else {
		$qbankSessionHash = $objectAPI->getHash();
		// Save the session hash somewhere
	}
?>

如果您需要实例化多个API类（通常需要），请避免在实例化每个类时都进行登录。最佳实践是第一次登录并回收会话哈希。登录应该只在每个用户会话中需要一次。

<?php
	$searchAPI = new QBankSearchAPI(QBANK_ADDRESS);
	$objectAPI = new QBankObjectAPI(QBANK_ADDRESS);
	if ($objectAPI->login(USERNAME, PASSWORD) !== true) {
		// Handle faulty login
	} else {
		$qbankSessionHash = $objectAPI->getHash();
		$objectAPI->setHash($qbankSessionHash);
		// Save the session hash somewhere
	}
?>

日志记录

QBankAPI2Wrapper使用Monolog，并具有默认的Monolog\Handler\ErrorLogHandler，允许您在PHP的默认错误日志中查看大多数消息。如果需要，您可以通过BaseAPI->addLogHandler()方法推送其他处理器。

搜索

搜索是检索QBank中多个对象的主要方式。有几种执行搜索的方法，最佳方法取决于具体情况。

通过创建搜索对象来进行搜索。请注意，此类只能在实例化搜索API之后使用。然后可以根据您的需求自定义搜索。在设置搜索对象后，将其提供给QBankSearchAPI::execute()。

<?php
	QBankAPIFactory::setup(QBANK_ADDRESS, USERNAME, PASSWORD);
	try {
		$searchAPI = QBankAPIFactory::createAPI(QBankAPIFactory::SearchAPI);
		$search = new Search();
		$search->setFreeText('string to search for');
		$results = $searchAPI->execute($search);
		// Display the results
	} catch (QBankAPIException $qae) {
		// Handle the error
	}
?>

检索属性（元数据）

QBank为用户可以设置的所有对象存储属性。默认情况下，这些属性不包括在结果中，但需要请求。

错误方式

进行搜索的一种直观但错误的方法是先进行搜索，然后遍历结果并对每个结果调用QBankObjectAPI::getObject()。这将返回有关这些对象的所有信息，但会产生大量的网络流量和开销。请避免这样做！

更好的方式

为了在不引起网络拥堵的情况下达到与错误方式相同的结果，可以将Search::setAdvancedObjects()设置为true。这将批量处理所有调用。

更智能的方式

如果只想返回结果中的一些属性，则应使用类PropertyRequest。

<?php
	QBankAPIFactory::setup(QBANK_ADDRESS, USERNAME, PASSWORD);
	try {
		$searchAPI = QBankAPIFactory::createAPI(QBankAPIFactory::SearchAPI);
		$search = new Search();
		$properties = array();
		$properties[] = new PropertyRequest(PROPERTY_SYSTEM_NAME);
		$search->addPropertyCriterias($properties);
		$results = $searchAPI->execute($search);
		// Display the results
	} catch (QBankAPIException $qae) {
		// Handle the error
	}
?>

请注意，这种方式产生的信息比之前的方法要少。其中一个变化是属性默认值将缺失。通常情况下这是可以的，但请考虑您的需求并相应地搜索。

搜索结果

搜索返回一个类型为SearchResult的对象。这是一个包含搜索将返回的Object或SimpleObject的容器。将其视为数组中的SearchResult也是可以的。您可以像访问数组一样遍历和访问SearchResult。

<?php
	$results = $searchApi->execute($search);
	$firstResult = $results[0];
	
	foreach($results as $result) {
		echo $result->getId();
	}
?>