ha-rest-api-client

Clients for accessing HomeAssistant Rest API & Webhooks.

• Requirements
• Installation
• Prerequisites
• Usage
  • Basic (Http Client Auto Discovery)
  • Custom Http Client (optional)
  • HaRestApiClient - Available Methods
  • HaWebhookClient - Available Methods
  • Error Handling
• Changelog
• Contributing

Requirements

• PHP Version >= 8.2
• A PSR-18 compatible http client.
• A PSR-17 compatible factory.

Installation

You can install the package via composer:

composer require indexzer0/ha-rest-api-client

This library does not have a dependency on Guzzle or any other library that sends HTTP requests. This packages uses the awesome HTTPlug to achieve the decoupling. We want you to choose what library to use for sending HTTP requests. Consult this list of packages that support php-http/client-implementation to find clients to use. For more information about virtual packages please refer to HTTPlug.

Install your choice of http client.

Example:

composer require guzzlehttp/guzzle
composer require guzzlehttp/psr7

Prerequisites

• Check out the Home Assistant Rest Api docs.
  • Add the API integration to your configuration.yaml.
  • Create a Long-Lived Access Token in your profile.

Usage

This package provides two clients. HaRestApiClient and HaWebhookClient.

Basic (Http Client Auto Discovery)

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

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

Custom Http Client (optional)

The client needs to know what library you are using to send HTTP messages. You could provide an instance of a PSR-18 compatible http client and PSR-17 compatible factory, or you could fallback on auto discovery (basic example above). Below is an example on where you provide a Guzzle7 instance.

/*
 * ---------------------------
 * HaRestApiClient
 * ---------------------------
 */
$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
    'token',
    'http://localhost: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(
    'http://localhost: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 - Available Methods

$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
    'token',
    'http://localhost: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 - Available Methods

$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
    'http://localhost: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']
);

Error Handling

All exceptions thrown by the package implement \IndexZer0\HaRestApiClient\Exception\HaExceptionInterface.

How-ever it doesn't harm to also catch \Throwable.

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

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

• Currently accepting PR for$client->camera(); as I don't have a camera entity to develop against.

Please see CONTRIBUTING for details.

Credits

• IndexZer0

License

The MIT License (MIT). Please see License File for more information.