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(4mo ago)022MITPHPPHP >=8.2CI passing

Since Dec 6Pushed 4mo 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 1mo ago

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

37

—

LowBetter than 83% of packages

Maintenance74

Regular maintenance activity

Popularity8

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

147d 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

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[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/gax

Google API Core for PHP

263103.1M454](/packages/google-gax)

PHPackages © 2026

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