README

Whise API 的 PHP 客户端。有关使用条款和 API 凭证，请参阅官方文档。

安装

composer require fw4/whise-api

使用方法

use Whise\Api\WhiseApi;

$api = new WhiseApi();

// Retrieve existing access token from storage (getAccessTokenFromDataStore to be implemented)
$accessToken = getAccessTokenFromDataStore();

if (!$accessToken) {
    // Request and store new access token (saveAccessTokenToDataStore to be implemented)
    $accessToken = $api->requestAccessToken('username', 'password');
    saveAccessTokenToDataStore($accessToken);
}

$api->setAccessToken($accessToken);

所有端点都作为 WhiseApi 类的方法提供。有关可用端点和响应格式的更多信息，请参阅官方 API 文档。

可用端点

使用以下方法访问可用端点

管理

$api->admin()->clients()->list($parameters);
$api->admin()->clients()->settings($parameters);
$api->admin()->clients()->updateSettings($parameters);
$api->admin()->clients()->token($parameters);
$api->admin()->offices()->list($parameters);
$api->admin()->representatives()->list($parameters);

房地产

$api->estates()->list($filter, $sorting, $fields);
$api->estates()->get($id, $filter, $fields);
$api->estates()->regions()->list($parameters);
$api->estates()->usedCities()->list($filter);
$api->estates()->usedCountries()->list($filter);
$api->estates()->exports()->list($office_id, $parameters);
$api->estates()->exports()->changeStatus($estate_id, $export_status, $id_in_media, $export_message);
$api->estates()->owned()->list($username, $password, $filter, $sorting, $fields);

联系人

$api->contacts()->upsert($parameters);
$api->contacts()->origins()->list($parameters);
$api->contacts()->titles()->list($parameters);
$api->contacts()->types()->list($parameters);

日历

$api->calendars()->list($filter, $sorting, $fields, $aggregation);
$api->calendars()->create($parameters);
$api->calendars()->delete($id);
$api->calendars()->update($parameters);
$api->calendars()->actions()->list($parameters);

活动

$api->activities()->calendars($filter, $aggregation);
$api->activities()->histories($filter, $aggregation);
$api->activities()->audits($filter, $aggregation);
$api->activities()->historyExports($filter, $aggregation);

分页

返回多个项的端点将返回一个可遍历的对象列表。对于大型列表的分页将自动进行。

$estates = $api->estates()->list();

// Traversing over the response takes care of pagination in the background
foreach ($estates as $estate) {
    echo $estate->name . PHP_EOL;
}

手动分页

对于需要手动分页的情况，提供了一个 page 方法。调用此方法时，需要提供所需的页面索引（从 0 开始）以及每页要检索的项目数量，将返回一个可遍历的对象列表。此列表还提供了处理分页元数据的多种方法。

• getPage() 用于检索当前页面索引（从 0 开始）。
• getPageSize() 用于检索每页的最大项目数量。
• count() 用于检索当前页上的实际项目数量。
• getTotalCount() 用于检索所有页面的总项目数量。此方法目前在 activity 端点上不可用。
• getPageCount() 用于检索总页数。此方法目前在 activity 端点上不可用。

示例

$page_index = 2;
$items_per_page = 20;

$estates = $api->estates()->list([
    'CategoryIds' => [1]
]);
$page = $estates->page($page_index, $items_per_page);

echo 'Showing ' . $page->count() . ' items out of ' . $page->getTotalCount() . PHP_EOL;
echo 'Page ' . ($page->getPage() + 1) . ' of ' . $page->getPageCount() . PHP_EOL;
foreach ($page as $estate) {
    echo $estate->name . PHP_EOL;
}

缓存

可以使用 PSR-6 兼容的缓存适配器 启用缓存。请注意，这将导致所有读取操作都被缓存，覆盖了 Whise API 使用的任何缓存控制策略，违反了 RFC。

use Cache\Adapter\Redis\RedisCachePool;

$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);
$cache = new RedisCachePool($redis);

$api = new Whise\Api\WhiseApi($access_token);
$api->setCache($cache);

您可以使用 setCache 方法的第二个和第三个参数分别更改默认缓存生命周期（为一小时）以及缓存键前缀。这些也可以通过使用 setCacheTtl 和 setCachePrefix 方法在运行时更改。

响应按访问令牌进行缓存，因此请确保重用您的访问令牌以在脚本执行之间共享缓存。

要确定响应是否从缓存中返回，请调用 isCacheHit 方法。当使用自动分页时，此方法不可用。

$estate = $api->estates()->get(1);
if ($estate->isCacheHit()) {
    echo 'Response fetched from cache' . PHP_EOL;
} else {
    echo 'Response fetched from API' . PHP_EOL;
}

许可证

fw4/whise-api 使用 MIT 许可证 (MIT) 许可。有关更多信息，请参阅 LICENSE。