PHPackages                             sharkydog/hass-connector - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. sharkydog/hass-connector

ActiveLibrary[API Development](/categories/api)

sharkydog/hass-connector
========================

Home Assistant REST and WebSocket api wrappers

v1.0(6mo ago)02MITPHPPHP >=7.4

Since Oct 23Pushed 6mo agoCompare

[ Source](https://github.com/sharkydog/hass-connector)[ Packagist](https://packagist.org/packages/sharkydog/hass-connector)[ RSS](/packages/sharkydog-hass-connector/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

hass-connector
==============

[](#hass-connector)

Home Assistant REST and WebSocket api wrappers

These are simple "barebones" clients, they do not provide high level abstraction for Home Assistant, so you must have some knowledge about the APIs, automation triggers and configuring Home Assistant in general.

- REST API -
- WebSocket API -

Responses are awaited using [ReactPHP Promises](https://reactphp.org/promise/). Data comes in and out mostly as `\stdClass` objects and has the same structure as seen in various Home Assistant documentation and examples.

An example state object from `print_r()`

```
stdClass Object
(
    [entity_id] => input_boolean.test_toggle
    [state] => off
    [attributes] => stdClass Object
        (
            [editable] => 1
            [friendly_name] => Test Toggle
        )

    [last_changed] => 2025-10-21T13:09:18.481787+00:00
    [last_reported] => 2025-10-21T13:09:18.481787+00:00
    [last_updated] => 2025-10-21T13:09:18.481787+00:00
    [context] => stdClass Object
        (
            [id] => XXXXXXXXXXXXXXXXXXXXXXXXXX
            [parent_id] =>
            [user_id] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        )

)

```

REST Client
-----------

[](#rest-client)

Class `SharkyDog\HASS\ClientREST`

```
public function __construct(string $url, string $token);
public function setDefaultTimeout(int $timeout);
public function setDefaultSilent(bool $silent);

public function GET(
    string $endpoint,
    ?int $timeout=null,
    ?bool $silent=null
): Promise\PromiseInterface;

public function POST(
    string $endpoint,
    ?\stdClass $data=null,
    ?int $timeout=null,
    ?bool $silent=null
): Promise\PromiseInterface;
```

- `$url` is the base rest api url - `http://192.168.1.123:8123/api`
- `$endpoint` is path after `/api/` in docs above - `states/`
- `$timeout` is in seconds, can be 0 to wait forever, default 60s
- `$data` is a `\stdClass` with the same structure as required for the endpoint, shown as json in docs
- `$silent` will silence errors, `catch(fn()=>null)` will be used on the promise if `$silent==true`, so the returned promise will be resolved with `null` on error, default `false`

Example

```
use SharkyDog\HASS;

$url = 'http://192.168.1.123:8123/api';
$token = 'xxxxxxx';
$hass = new HASS\ClientREST($url, $token);

// === GET ===
$promise = $hass->GET('states/input_boolean.test_toggle');
$promise = $promise->then(function($result) {
    print_r($result);
});
$promise = $promise->catch(function(\Exception $e) {
    print_r(['GET error', $e->getMessage(), $e->getCode()]);
});
// cancelling the promise will abort the request
//$promise->cancel();

// === POST ===
$hass->POST(
    'template',
    (object)['template' => 'Toggle is {{ states("input_boolean.test_toggle") }}']
)->then(function($result) {
  print_r($result);
})->catch(function(\Exception $e) {
  print_r(['POST error', $e->getMessage(), $e->getCode()]);
});
```

First (GET) will print the state object like shown above. Second (POST) renders a template and will print plain text.

WebSocket Client
----------------

[](#websocket-client)

Extends `SharkyDog\HTTP\Helpers\WsClientDecorator`, which decorates `SharkyDog\HTTP\WebSocket\Client` from [sharkydog/http](https://github.com/sharkydog/http) package. Some methods, events and reconnect logic are inherited from these classes. See the [websocket client example](https://github.com/sharkydog/http/blob/main/examples/08-websocket-client.php)

Class `SharkyDog\HASS\ClientWS`

```
public function __construct(string $url, string $token);
public function setDefaultTimeout(int $timeout);
public function setDefaultSilent(bool $silent);
public function connected(): bool;

public function subscribe(callable $callback, \stdClass $data): int;
public function subscribeEvent(callable $callback, string $event): int;
public function subscribeTrigger(callable $callback, \stdClass ...$triggers): int;
public function unsubscribe(int $sid): Promise\PromiseInterface;

public function sendCommand(
    \stdClass $data,
    ?int $timeout=null,
    ?bool $silent=null
): Promise\PromiseInterface;

public function fireEvent(
    string $event,
    ?\stdClass $data=null
): Promise\PromiseInterface;

public function callService(
    string $service,
    ?\stdClass $target=null,
    ?\stdClass $data=null,
    bool $resp=false
): Promise\PromiseInterface;
```

- Timeout and silencing errors work the same as in the REST client
- Subscribe methods return an id to be used in `unsubscribe()`, these can also be used when client is not connected. Subscriptions will be reestablished on reconnect.
- `connected()` will return `true` only after auth phase passed
    - There is also `open` event, more on that bellow
- Sending commands is possible only when connected, they will reject otherwise. Except `unsubscribe()`, when offline it will remove the subscription and resolve with `null`
- `fireEvent()` and `callService()`, do not have `$timeout` and `$silent` parameters. They will use default values.

```
use SharkyDog\HASS;

$url = 'http://192.168.1.123:8123/api';
$token = 'xxxxxxx';
$hassWS = new HASS\ClientWS($url, $token);
// reconnects are disabled by default
// this will tell the client to reconnect 10 seconds after remote connection close
$hassWS->reconnect(10);

// client event
$hassWS->on('open', function() use($hassWS) {
    print_r(['open',$hassWS->hassVer]);
    // send commands, fire events, call services
});

// setup subscriptions
// will also work after connect() call
// as subscriptions will be send after connect or reconnect
// and client will not transition to connected
// until execution is passed to the event loop
// and connection is established and auth succeeds

$hassWS->connect();
```

### Events

[](#events)

Events are emitted using [Evenement\\EventEmitter](https://github.com/igorw/evenement/tree/v3.0.2)

`event` \[`parameter1`, `parameter2`, ...\]

- `open`
    - Client connected and auth phase passed
- `close` \[`bool $reconnect`\]
    - Connection close, will try to reconnect if `$reconnect==true`, all pending commands will be rejected
- `subscribed` \[`int $sid`\]
    - Subscription with id `$sid` registered
- `error-auth` \[`string $message`\]
    - Error in auth phase, connection will be closed
- `error-subscribe` \[`\Exception $e`, `int $sid`\]
    - Subscription with id `$sid` failed

### subscribe()

[](#subscribe)

Create a general subscription. Besides `subscribe_events` and `subscribe_trigger`, there are other undocumented types, this method allows subscribing for such messages. Find out types and message structure by peeking into communication between Home Assistant frontend and core using your browser's developer console.

Monitor entity state

```
$entity = 'input_boolean.test_toggle';
$sid = $hassWS->subscribe(function(\stdClass $data) use($entity) {
    $states = $data->event->states->$entity;
    print_r([
        date('Y-m-d\TH:i:s', (int)$states[0]->lu),
        $states[0]->s
    ]);
}, (object)[
    'type' => 'history/stream',
    'entity_ids' => [$entity],
    'start_time' => gmdate('Y-m-d\TH:i:s\Z'),
    'minimal_response' => true,
    'significant_changes_only' => false,
    'no_attributes' => true
]);
```

### subscribeEvent()

[](#subscribeevent)

Calls `subscribe()` for type `subscribe_events` and supplied `event_type`.

Callback receives `$data->event->data` and `$data->event->time_fired`.

```
$sid1 = $hassWS->subscribeEvent(function(\stdClass $event_data, string $time_fired) {
    print_r(['event test', $event_data, $time_fired]);
}, 'test');
```

### subscribeTrigger()

[](#subscribetrigger)

Calls `subscribe()` for type `subscribe_trigger` and supplied triggers.

Triggers are `\stdClass` object with the same structure as automation triggers. Callback receives `$data->event->variables`.

```
$sid2 = $hassWS->subscribeTrigger(
    function($vars) {
        print_r([
            $vars->trigger->id,
            $vars->trigger->entity_id,
            $vars->trigger->from_state->state,
            $vars->trigger->to_state->state
        ]);
    },
    (object)[
        'id' => 'tg1',
        'platform' => 'state',
        'entity_id' => 'input_boolean.test_toggle',
        'from' => 'off',
        'to' => 'on'
    ],
    (object)[
        'id' => 'tg2',
        'platform' => 'state',
        'entity_id' => ['input_boolean.test_toggle','input_boolean.test_toggle_2'],
        'to' => ['on','off'],
        'for' => '00:00:02'
    ]
);
```

### unsubscribe()

[](#unsubscribe)

Remove a subscription

```
// this returns a promise
// use either setDefaultSilent() or attach rejection handlers
// to avoid unhandled rejections if unsubscribe fails
$hassWS->unsubscribe($sid1);
// silence this one
$hassWS->unsubscribe($sid2)->catch(fn()=>null);
```

### sendCommand()

[](#sendcommand)

Send a command, overwrite default timeout and silence option.

```
$promise = $hassWS->sendCommand((object)[
    'type' => 'auth/current_user'
], 5, true);
$promise->then(function(?\stdClass $result) {
    print_r($result);
})->catch(function(\Exception $e) {
    print_r(['user err', $e->getMessage(), $e->getCode()]);
});
```

### fireEvent()

[](#fireevent)

Fire event `test`.

```
$promise = $hassWS->fireEvent('test', (object)[
    'a' => 'b',
    'c' => [
        (object)['d'=>'e'],
        (object)['f'=>'g', 'h'=>'i']
    ]
]);
```

In Home Assistant developer tools, it would look like this in yaml

```
event_type: test
data:
  a: b
  c:
    - d: e
    - f: g
      h: i
```

### callService()

[](#callservice)

Call a service with response. For services that do not return response, the 4th parameter must be `false` (default). Home Assistant will return and error when calling a service and expecting response, but the service do not return one.

```
$hassWS->callService(
    'media_player.browse_media',
    (object)[
        'entity_id' => 'media_player.player_that_can_browse_media'
    ],
    (object)[
        'media_content_id' => 'media-source://media_source'
    ],
    true
)->then(function(?\stdClass $response) {
    print_r($response);
})->catch(function(\Exception $e) {
    print_r(['svc err', $e->getMessage(), $e->getCode()]);
});
```

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance66

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

201d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d54985ab7d672df15e1ac9f278a842cddb25502a1bda7693e455680dbaa782b4?d=identicon)[SharkyDog](/maintainers/SharkyDog)

---

Top Contributors

[![sharkydog](https://avatars.githubusercontent.com/u/6613422?v=4)](https://github.com/sharkydog "sharkydog (13 commits)")

---

Tags

iotHome Assistant

### Embed Badge

![Health badge](/badges/sharkydog-hass-connector/health.svg)

```
[![Health](https://phpackages.com/badges/sharkydog-hass-connector/health.svg)](https://phpackages.com/packages/sharkydog-hass-connector)
```

###  Alternatives

[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[knplabs/github-api

GitHub API v3 client

2.2k15.8M187](/packages/knplabs-github-api)[facebook/php-business-sdk

PHP SDK for Facebook Business

90121.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

73813.7M114](/packages/meilisearch-meilisearch-php)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)[hubspot/api-client

Hubspot API client

23414.2M16](/packages/hubspot-api-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)