README

访问 HomeAssistant REST API & Webhooks 的客户端。

需求
安装
先决条件
使用
变更日志
贡献

需求

PHP 版本 >= 8.2
PSR-18 兼容的 HTTP 客户端。
PSR-17 兼容的工厂。

安装

您可以通过 composer 安装此包

composer require indexzer0/ha-rest-api-client

此库不依赖于 Guzzle 或其他发送 HTTP 请求的库。此包使用 HTTPlug 实现解耦。我们希望您选择用于发送 HTTP 请求的库。请查阅支持 php-http/client-implementation 的包列表以找到要使用的客户端。有关虚拟包的更多信息，请参阅 HTTPlug。

安装您选择的 HTTP 客户端。

示例

composer require guzzlehttp/guzzle
composer require guzzlehttp/psr7

先决条件

查看 Home Assistant REST Api 文档。
- 将 API 集成添加到您的 configuration.yaml。
- 在您的个人资料中创建一个 Long-Lived Access Token。

使用

此包提供两个客户端。 HaRestApiClient 和 HaWebhookClient。

基本（自动发现 HTTP 客户端）

/*
 * ---------------------------
 * HaRestApiClient
 * ---------------------------
 */
$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
    'token',
    'https://:8123/api/'
);
$restApiClient->status(); // ['message' => 'API running.']

/*
 * ---------------------------
 * HaWebhookClient
 * ---------------------------
 */
$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
    'https://:8123/api/'
);
$webhookClient->send('GET', 'webhook_id'); // ['response' => '']

自定义 HTTP 客户端（可选）

客户端需要知道您使用什么库发送 HTTP 消息。您可以选择提供 PSR-18 兼容的 HTTP 客户端和 PSR-17 兼容的工厂的实例，或者您可以选择回退到自动发现（上面提供的示例）。以下是一个提供 Guzzle7 实例的示例。

/*
 * ---------------------------
 * HaRestApiClient
 * ---------------------------
 */
$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
    'token',
    'https://:8123/api/',
    new \IndexZer0\HaRestApiClient\HttpClient\Builder(
        new \GuzzleHttp\Client(),
        new \GuzzleHttp\Psr7\HttpFactory(),
        new \GuzzleHttp\Psr7\HttpFactory(),
        new \GuzzleHttp\Psr7\HttpFactory(),
    )
);
$restApiClient->status(); // ['message' => 'API running.']

/*
 * ---------------------------
 * HaWebhookClient
 * ---------------------------
 */
$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
    'https://:8123/api/',
    new \IndexZer0\HaRestApiClient\HttpClient\Builder(
        new \GuzzleHttp\Client(),
        new \GuzzleHttp\Psr7\HttpFactory(),
        new \GuzzleHttp\Psr7\HttpFactory(),
        new \GuzzleHttp\Psr7\HttpFactory(),
    )
);
$webhookClient->send('GET', 'webhook_id'); // ['response' => '']

HaRestApiClient - 可用方法

$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
    'token',
    'https://:8123/api/'
);
$restApiClient->status();
$restApiClient->config();
$restApiClient->events();
$restApiClient->services();
$restApiClient->history(['light.bedroom_ceiling']);
$restApiClient->logbook();
$restApiClient->states();
$restApiClient->state('light.bedroom_ceiling');
$restApiClient->errorLog();
$restApiClient->calendars();
$restApiClient->calendarEvents('calendar.birthdays');
$restApiClient->updateState('light.bedroom_ceiling', 'on');
$restApiClient->fireEvent('script_started', [
    'name'      => 'Turn All Lights Off',
    'entity_id' => 'script.turn_all_lights_off'
]);
$restApiClient->callService('light', 'turn_on', [
    'entity_id' => 'light.bedroom_ceiling'
]);
$restApiClient->renderTemplate("The bedroom ceiling light is {{ states('light.bedroom_ceiling') }}.");
$restApiClient->checkConfig();
$restApiClient->handleIntent([
    'name' => 'SetTimer',
    'data' => [
        'seconds' => '30',
    ]
]);

HaWebhookClient - 可用方法

$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
    'https://:8123/api/'
);

/*
 * ---------------------------
 * GET request example
 * ---------------------------
 */
$webhookClient->send(
    method: 'GET',
    webhookId: 'webhook_id',
    queryParams: ['query' => 'param'],
);

/*
 * ---------------------------
 * POST request example - with json body
 * ---------------------------
 */
$webhookClient->send(
    method: 'POST',
    webhookId: 'webhook_id',
    payloadType: 'json',
    data: ['json' => 'data']
);

/*
 * ---------------------------
 * POST request example - with form params body
 * ---------------------------
 */
$webhookClient->send(
    method: 'POST',
    webhookId: 'webhook_id',
    payloadType: 'form_params',
    data: ['form' => 'param']
);

错误处理

包抛出的所有异常都实现了 \IndexZer0\HaRestApiClient\Exception\HaExceptionInterface。

不过，也捕获 \Throwable 也不会有什么坏处。

try {
    $webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
        'https://:8123/api/'
    );
    $response = $webhookClient->send('GET', 'webhook_id');
} catch (\IndexZer0\HaRestApiClient\Exception\HaExceptionInterface $haException) {
    
} catch (\Throwable $t) {
    // Shouldn't happen - but failsafe.
}

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近有哪些变化。

贡献

目前接受 $client->camera(); 的 PR，因为我没有摄像头实体可以开发。

有关详细信息，请参阅 CONTRIBUTING。

鸣谢

IndexZer0

许可

MIT 许可证（MIT）。请参阅许可文件了解更多信息。

indexzer0 / ha-rest-api-client

维护者

详细信息