mapo-89 / laravel-homeassistant-api

v2.0.1 2026-11-04 23:51 UTC

Requires

• php: >=8.3
• illuminate/support: ^12.0|^13.0
• phrity/websocket: ^4.1
• spatie/laravel-package-tools: ^1.93.0

Requires (Dev)

• larastan/larastan: ^3.13
• laravel/pint: ^1.32
• orchestra/testbench: ^10.0|^11.0
• phpunit/phpunit: ^11.0|^12.0|^13.0

MIT

• Manuel Postler

Published on Packagist.org on 2026-11-05 21:33 UTC

README

Laravel integration for the Home Assistant REST and WebSocket APIs, with support for separate URLs and tokens per installation.

Deutsche Dokumentation

Requirements

• PHP 8.3 or newer
• Laravel 12 or 13
• A Home Assistant instance and an access token

Installation

composer require mapo-89/laravel-homeassistant-api

Laravel discovers the service provider and facade automatically. Configure your installation in .env:

HA_URL=http://homeassistant.local:8123
HA_TOKEN=your_long_lived_token

Configuration

Optionally publish config/homeassistant-api.php:

php artisan vendor:publish --tag=homeassistant-api-config

The legacy --tag=config tag remains supported.

Option	Default	Purpose
connect_timeout	3	Connection timeout in seconds.
timeout	8	Request timeout in seconds.
cache_responses	true	Cache state lists for five seconds; set to false for fresh reads.

Usage

use Mapo89\LaravelHomeassistantApi\Facades\HomeassistantApi;

$ha = HomeassistantApi::make();

// For a separate installation, supply both URL and token.
$ha = HomeassistantApi::make([
    'url' => 'https://homeassistant.example.com',
    'token' => 'your_long_lived_token',
]);

The same configuration options are available in the array passed to make().

States and filters

$states = $ha->states()->get(); // State[]; all() is an equivalent alias
$state = $ha->states()->get('light.kitchen'); // State

$lights = $ha->states()
    ->whereDomain('light')
    ->whereState('on')
    ->get();

Filters run on the retrieved state list.

Method	Purpose
whereDomain($domain)	Filter by entity domain.
whereState($state)	Filter by state.
whereEntityIds($ids)	Filter by entity IDs.
whereAttribute($key, $value)	Filter by an attribute value.
get()	Return matching State objects.
first()	Return the first matching State, or null.

Services

$ha->services()->turnOn('light.kitchen', ['brightness' => 80]);
$ha->services()->turnOff('light.kitchen');
$ha->services()->toggle('light.kitchen');

$response = $ha->services()->call(
    'weather',
    'get_forecasts',
    ['entity_id' => 'weather.home', 'type' => 'daily'],
    returnResponse: true,
);
$forecast = $response['service_response']['weather.home']['forecast'];

call() normally returns changed states. For services that support or require a response, use returnResponse: true to receive changed_states and service_response.

System and configuration

$ha->system()->verify();
$ha->config()->get();
$ha->config()->check();
$ha->config()->setExternalUrl('https://customer.example.com');

Setting the external URL requires a Home Assistant administrator token.

WebSocketClient::systemState() falls back to known active CHICO/HACS restart repairs when the system-state command is unsupported. Dismissed active repairs still count. In this fallback, restartRequired is true or null (unknown), rebootRequired is null, and sources lists the detected domains. Other errors fail the request.

Templates and events

$text = $ha->template()->render('Temperature: {{ states("sensor.kitchen_temperature") }}');

$events = $ha->events()->all();
$ha->events()->fire('my_custom_event', ['source' => 'laravel']);

History and logbook

Both APIs require at least one entity ID. Dates may be Carbon or CarbonImmutable.

$entities = ['light.kitchen'];
$start = now()->subHours(6);

$history = $ha->history()->get(start: $start, entityIds: $entities);
$flat = $ha->history()->flat(start: $start, entityIds: $entities);
$entries = $ha->logbook()->get(entityIds: $entities, start: $start, end: now());

get() groups HistoryState objects by entity ID; flat() returns a single list. History also accepts significantOnly and minimal options. Logbook returns LogbookEntry objects.

For Home Assistant endpoint details, see the REST API documentation.

Artisan

php artisan ha:call
php artisan ha:call --entity=light.kitchen
php artisan ha:call light toggle --entity=light.kitchen

Artisan uses the static package configuration.

Upgrading to version 2

• Laravel 10 and 11 are no longer supported.
• States and Services no longer extend ApiClient. Use ApiClient directly for low-level HTTP calls.

API failures throw HomeAssistantException; invalid arguments throw InvalidArgumentException.

Development

composer install
composer qa

Tests use simulated API responses and do not need a running Home Assistant instance. See CONTRIBUTING and the release guide for development, dependency updates and releases. Changes are listed in CHANGELOG.

Security

Report security issues to [e-mail].

Credits and license

• Manuel Postler
• All contributors

Licensed under the MIT License.