README

A simple Laravel integration for the Homeassistant API. This package provides a clean interface to interact with the API.

📖 This README is also available in 🇩🇪 German.

📦 Installation

Install the package via Composer:

composer require mapo-89/laravel-homeassistant-api

Add your API token to your .env file:

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

⚡️ Dynamic configuration (URL & token at runtime)

In addition to static configuration via config/homeassistant.php, this package also supports dynamic configurations at runtime. This is useful, for example, if each user has their own Home Assistant token or if the instance URL is to be set dynamically.

Optionally, you can publish the config file:

php artisan vendor:publish --provider="Mapo89\LaravelHomeassistantApi\HomeassistantApiServiceProvider" --tag="config"

⚙️ Usage

📚 The complete API documentation can be found here: home-assistant.io

Initialization

use Mapo89\LaravelHomeassistantApi\Facades\HomeassistantApi;

$homeassistantApi = HomeassistantApi::make();

//Alternative with dynamic configuration
$config = [
    'url' => 'http://homeassistant.local:8123',
    'token' => 'your_long_lived_token'
];
$homeassistantApi = HomeassistantApi::make($config);

🔄 System API

// Check if the API is working
$homeassistantApi->system()->verify();

🔄 Config API

// Output current configuration
$homeassistantApi->config()->get();

// Check current configuration
$homeassistantApi->config()->check();

🔄 States API

$homeassistantApi->states()->all(); // adapt this to your use case

🧩 Template API

More information about templating

// renders a template
$homeassistantApi->template()->render(<<<'TEMPLATE'
    Paulus is at {{ states('device_tracker.paulus') }}!
    TEMPLATE
);

🔔 Events API

Interaction with the Home Assistant event system.

// Retrieve all available events
$events = $homeassistantApi->events()->all();

// Trigger custom event
$homeassistantApi->events()->fire('my_custom_event', [
    'source' => 'laravel',
    'user_id' => 123,
]);

Supported endpoints

• GET /api/events
• POST /api/events/{event_type}

🕒 History API

Access historical state changes of entities.

// Grouped history by entity
$history = $homeassistantApi->history()->get(
    start: now()->subHours(12),
    entityIds: ['light.kitchen', 'sensor.temperature'],
    significantOnly: true
);

// Access per entity
$history['light.kitchen']; // HistoryState[]

Flat output (ideal for charts & analytics)

$flat = $homeassistantApi->history()->flat(
    start: now()->subHours(6),
    entityIds: ['light.kitchen', 'sensor.temperature'],
);

Supported endpoints

• GET /api/history/period
• POST /api/history/period/{timestamp}

📒 Logbook API

Access the Home Assistant logbook – ideal for user activities, automations, and system events.

⚠️ The logbook API requires at least one entityId.

$entries = $homeassistantApi->logbook()->get(
    start: now()->subHours(6),
    entityIds: ['light.kitchen'],
    end: now()
);

Supported endpoint

• GET /api/logbook

Query Builder API (States)

Home Assistant does not support server-side filtering of states. This package therefore provides a query builder-like API that can be used to filter states on the client side – inspired by Laravel Eloquent.

✨ Example

use Mapo89\LaravelHomeassistantApi\Facades\HomeassistantApi;

$states = HomeassistantApi::make()
    ->states()
    ->whereDomain('light')
    ->whereState('on')
    ->get();

🧱 Available query methods

whereDomain(string $domain)

Filters by the domain of an entity (e.g., light, sensor, switch).

$lights = HomeassistantApi::make()
    ->states()
    ->whereDomain('light')
    ->get();

whereState(string $state)

Filters by the state of an entity (e.g., on, off, unavailable).

$active = HomeassistantApi::make()
    ->states()
    ->whereState('on')
    ->get();

whereEntityIds(array $entityIds)

Filters by a list of specific entity IDs.

$states = HomeassistantApi::make()
    ->states()
    ->whereEntityIds([
        'light.kitchen',
        'sensor.temperature',
    ])
    ->get();

whereAttribute(string $key, mixed $value)

Filters by attributes of an entity.

$lights = HomeassistantApi::make()
    ->states()
    ->whereDomain('light')
    ->whereAttribute('brightness', 255)
    ->get();

get()

Returns all filtered states as an array of State DTOs.

$states = HomeassistantApi::make()
    ->states()->get();

first()

Returns the first matching state or null.

$state = HomeassistantApi::make()
    ->states()
    ->whereEntityIds(['light.kitchen'])
    ->first();

Artisan Command

The following Artisan commands always use the static configuration from .env or config/homeassistant.php:

# List all states
php artisan ha:call

# Call a service (e.g., switch lights) (in implementation)
php artisan ha:call light toggle --entity=light.livingroom

📒 Changelog

Please see CHANGELOG for recent changes.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

🔐 Security

If you discover any security issues, please do not use the issue tracker. Instead, email us directly at info@postler.de.

👥 Credits

• Manuel Postler
• All Contributors

📄 License

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

🛠️ Laravel Package Boilerplate

Generated using the Laravel Package Boilerplate.