PHPackages                             mapo-89/laravel-homeassistant-api - 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. mapo-89/laravel-homeassistant-api

ActiveLibrary[API Development](/categories/api)

mapo-89/laravel-homeassistant-api
=================================

Laravel package to interact with Home Assistant REST API.

v1.4.2(6mo ago)029MITPHPPHP >=8.2CI passing

Since Dec 6Pushed 6mo agoCompare

[ Source](https://github.com/mapo-89/laravel-homeassistant-api)[ Packagist](https://packagist.org/packages/mapo-89/laravel-homeassistant-api)[ Docs](https://github.com/mapo-89/laravel-homeassistant-api)[ RSS](/packages/mapo-89-laravel-homeassistant-api/feed)WikiDiscussions main Synced today

READMEChangelog (7)DependenciesVersions (8)Used By (0)

🚀 Laravel Homeassistant API
===========================

[](#-laravel-homeassistant-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/77bbcca503e97008b4268e060e2af23ef30b3f554f8d076f2573e8cd02f294f9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d61706f2d38392f6c61726176656c2d686f6d65617373697374616e742d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mapo-89/laravel-homeassistant-api)[![Total Downloads](https://camo.githubusercontent.com/47aa6bcbedb209fa03d1050417cc780596953ddbcbee2c30d2c23221e2299bd1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d61706f2d38392f6c61726176656c2d686f6d65617373697374616e742d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mapo-89/laravel-homeassistant-api)[![GitHub Actions](https://github.com/mapo-89/laravel-homeassistant-api/actions/workflows/main.yml/badge.svg)](https://github.com/mapo-89/laravel-homeassistant-api/actions/workflows/main.yml/badge.svg)

A simple Laravel integration for the [Homeassistant API](https://developers.home-assistant.io/docs/api/rest). This package provides a clean interface to interact with the API.

📖 This README is also available in [🇩🇪 German](README.de.md).

---

📦 Installation
--------------

[](#-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)
-----------------------------------------------------

[](#️-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
--------

[](#️-usage)

> 📚 The complete API documentation can be found here: [home-assistant.io](https://developers.home-assistant.io/docs/api/rest)

### Initialization

[](#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

[](#-system-api)

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

---

### 🔄 Config API

[](#-config-api)

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

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

---

### 🔄 States API

[](#-states-api)

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

---

### 🧩 Template API

[](#-template-api)

More information about [templating](https://www.home-assistant.io/docs/configuration/templating)

```
// renders a template
$homeassistantApi->template()->render(events()->fire('my_custom_event', [
    'source' => 'laravel',
    'user_id' => 123,
]);
```

**Supported endpoints**

- `GET /api/events`
- `POST /api/events/{event_type}`

---

### 🕒 History API

[](#-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

[](#-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)
--------------------------

[](#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
---------

[](#-example)

```
use Mapo89\LaravelHomeassistantApi\Facades\HomeassistantApi;

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

---

🧱 Available query methods
-------------------------

[](#-available-query-methods)

### `whereDomain(string $domain)`

[](#wheredomainstring-domain)

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

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

---

### `whereState(string $state)`

[](#wherestatestring-state)

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

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

---

### `whereEntityIds(array $entityIds)`

[](#whereentityidsarray-entityids)

Filters by a list of specific entity IDs.

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

---

### `whereAttribute(string $key, mixed $value)`

[](#whereattributestring-key-mixed-value)

Filters by attributes of an entity.

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

---

### `get()`

[](#get)

Returns all filtered states as an array of `State` DTOs.

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

---

### `first()`

[](#first)

Returns the first matching state or `null`.

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

---

Artisan Command
---------------

[](#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
-----------

[](#-changelog)

Please see [CHANGELOG](CHANGELOG.md) for recent changes.

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

---

🔐 Security
----------

[](#-security)

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

---

👥 Credits
---------

[](#-credits)

- [Manuel Postler](https://github.com/mapo-89)
- [All Contributors](../../contributors)

---

📄 License
---------

[](#-license)

The MIT License (MIT). Please see the [License File](LICENSE.md) for more information.

---

🛠️ Laravel Package Boilerplate
------------------------------

[](#️-laravel-package-boilerplate)

Generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance66

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 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

Every ~1 days

Total

7

Last Release

201d ago

PHP version history (2 changes)v1.0.0PHP >=8.1

v1.4.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/72ebd5bd16b28366468c5f9cdafe5350f343eaa054995d00f4b4640c5c27767b?d=identicon)[mapo-89](/maintainers/mapo-89)

---

Top Contributors

[![mapo-89](https://avatars.githubusercontent.com/u/118180259?v=4)](https://github.com/mapo-89 "mapo-89 (35 commits)")

### Embed Badge

![Health badge](/badges/mapo-89-laravel-homeassistant-api/health.svg)

```
[![Health](https://phpackages.com/badges/mapo-89-laravel-homeassistant-api/health.svg)](https://phpackages.com/packages/mapo-89-laravel-homeassistant-api)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k15](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

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