Merge pull request #3 from IndexZer0/feature/httplug

Feature/httplug

CHANGELOG.md

@@ -2,3 +2,20 @@
 
 All notable changes to `ha-rest-api-client` will be documented in this file.
 
+## v2.0.0
+### Added
+- `HaWebhookClient`.
+- Various exception types.
+### Changed
+- Updated documentation in README.md.
+- No longer depend on `guzzlehttp/guzzle` (Guzzle7), instead use HTTPlug for client interoperability.
+- Handle converting http responses to exceptions manually.
+
+## v1.0.1
+### Changed
+- Nothing notable to package function, just code clean up.
+
+## v1.0.0
+- Initial release.
+- `guzzlehttp/guzzle` (Guzzle7) dependency.
+- `HaRestApiClient`.

README.md

@@ -5,11 +5,13 @@
 [![codecov](https://codecov.io/gh/IndexZer0/ha-rest-api-client/graph/badge.svg?token=JMF8UG8S4Y)](https://codecov.io/gh/IndexZer0/ha-rest-api-client)
 [![Total Downloads](https://img.shields.io/packagist/dt/indexzer0/ha-rest-api-client.svg?style=flat-square)](https://packagist.org/packages/indexzer0/ha-rest-api-client)
 
-Simple client wrapper around GuzzleHttp for accessing HomeAssistant Rest API.
+Clients for accessing HomeAssistant Rest API & Webhooks.
 
 ## Requirements
 
 - PHP Version >= 8.2
+- A PSR-18 compatible http client.
+- A PSR-17 compatible factory.
 
 ## Installation
 
@@ -19,6 +21,16 @@ You can install the package via composer:
 composer require indexzer0/ha-rest-api-client
 ```
 
+This library does not have a dependency on Guzzle or any other library that sends HTTP requests. This packages uses the awesome HTTPlug to achieve the decoupling. We want you to choose what library to use for sending HTTP requests. Consult this list of packages that support [php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation) to find clients to use. For more information about virtual packages please refer to [HTTPlug](https://docs.php-http.org/en/latest/httplug/users.html).
+
+Install your choice of http client.
+
+Example:
+```bash
+composer require guzzlehttp/guzzle
+composer require guzzlehttp/psr7
+```
+
 ## Prerequisites
 
 - Check out the [Home Assistant Rest Api docs](https://developers.home-assistant.io/docs/api/rest/).
@@ -27,52 +39,181 @@ composer require indexzer0/ha-rest-api-client
 
 ## Usage
 
+This package provides two clients. `HaRestApiClient` and `HaWebhookClient`.
+
+### Basic (Http Client Auto Discovery)
 ```php
-$client = new \IndexZer0\HaRestApiClient\HaRestApiClient(
+/*
+ * ---------------------------
+ * HaRestApiClient
+ * ---------------------------
+ */
+$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
     'token',
     'http://localhost:8123/api/'
 );
-$client->status(); // ['message' => 'API running.']
+$restApiClient->status(); // ['message' => 'API running.']
+
+/*
+ * ---------------------------
+ * HaWebhookClient
+ * ---------------------------
+ */
+$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
+    'http://localhost:8123/api/'
+);
+$webhookClient->send('GET', 'webhook_id'); // ['response' => '']
 ```
 
-### Available Methods
+### Custom Http Client (optional)
+
+The client needs to know what library you are using to send HTTP messages. You could provide an instance of a PSR-18 compatible http client and PSR-17 compatible factory, or you could fallback on auto discovery (basic example above). Below is an example on where you provide a Guzzle7 instance.
 
 ```php
-$client->status();
-$client->config();
-$client->events();
-$client->services();
-$client->history(['light.bedroom_ceiling']);
-$client->logbook();
-$client->states();
-$client->state('light.bedroom_ceiling');
-$client->errorLog();
-$client->calendars();
-$client->calendarEvents('calendar.birthdays');
-$client->updateState('light.bedroom_ceiling', 'on');
-$client->fireEvent('script_started', [
+/*
+ * ---------------------------
+ * HaRestApiClient
+ * ---------------------------
+ */
+$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
+    'token',
+    'http://localhost:8123/api/',
+    new \IndexZer0\HaRestApiClient\HttpClient\Builder(
+        new \GuzzleHttp\Client(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+    )
+);
+$restApiClient->status(); // ['message' => 'API running.']
+
+/*
+ * ---------------------------
+ * HaWebhookClient
+ * ---------------------------
+ */
+$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
+    'http://localhost:8123/api/',
+    new \IndexZer0\HaRestApiClient\HttpClient\Builder(
+        new \GuzzleHttp\Client(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+        new \GuzzleHttp\Psr7\HttpFactory(),
+    )
+);
+$webhookClient->send('GET', 'webhook_id'); // ['response' => '']
+```
+
+### HaRestApiClient - Available Methods
+
+```php
+$restApiClient = new \IndexZer0\HaRestApiClient\HaRestApiClient(
+    'token',
+    'http://localhost:8123/api/'
+);
+$restApiClient->status();
+$restApiClient->config();
+$restApiClient->events();
+$restApiClient->services();
+$restApiClient->history(['light.bedroom_ceiling']);
+$restApiClient->logbook();
+$restApiClient->states();
+$restApiClient->state('light.bedroom_ceiling');
+$restApiClient->errorLog();
+$restApiClient->calendars();
+$restApiClient->calendarEvents('calendar.birthdays');
+$restApiClient->updateState('light.bedroom_ceiling', 'on');
+$restApiClient->fireEvent('script_started', [
     'name'      => 'Turn All Lights Off',
     'entity_id' => 'script.turn_all_lights_off'
 ]);
-$client->callService('light', 'turn_on', [
+$restApiClient->callService('light', 'turn_on', [
     'entity_id' => 'light.bedroom_ceiling'
 ]);
-$client->renderTemplate("The bedroom ceiling light is {{ states('light.bedroom_ceiling') }}.");
-$client->checkConfig();
-$client->handleIntent([
+$restApiClient->renderTemplate("The bedroom ceiling light is {{ states('light.bedroom_ceiling') }}.");
+$restApiClient->checkConfig();
+$restApiClient->handleIntent([
     'name' => 'SetTimer',
     'data' => [
         'seconds' => '30',
     ]
 ]);
 ```
 
+### HaWebhookClient - Available Methods
+
+```php
+$webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
+    'http://localhost:8123/api/'
+);
+
+/*
+ * ---------------------------
+ * GET request example
+ * ---------------------------
+ */
+$webhookClient->send(
+    method: 'GET',
+    webhookId: 'webhook_id',
+    queryParams: ['query' => 'param'],
+);
+
+/*
+ * ---------------------------
+ * POST request example - with json body
+ * ---------------------------
+ */
+$webhookClient->send(
+    method: 'POST',
+    webhookId: 'webhook_id',
+    payloadType: 'json',
+    data: ['json' => 'data']
+);
+
+/*
+ * ---------------------------
+ * POST request example - with form params body
+ * ---------------------------
+ */
+$webhookClient->send(
+    method: 'POST',
+    webhookId: 'webhook_id',
+    payloadType: 'form_params',
+    data: ['form' => 'param']
+);
+```
+
+### Error Handling
+
+All exceptions thrown by the package implement `\IndexZer0\HaRestApiClient\Exception\HaExceptionInterface`.
+
+How-ever it doesn't harm to also catch `\Throwable`.
+
+
+
+```php
+try {
+    $webhookClient = new \IndexZer0\HaRestApiClient\HaWebhookClient(
+        'http://localhost:8123/api/'
+    );
+    $response = $webhookClient->send('GET', 'webhook_id');
+} catch (\IndexZer0\HaRestApiClient\Exception\HaExceptionInterface $haException) {
+
+} catch (\Throwable $t) {
+    // Shouldn't happen - but failsafe.
+}
+```
+
 ## Testing
 
 ```bash
 composer test
 ```
 
+## Changelog
+
+Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+
 ## Contributing
 
 - Currently accepting PR for```$client->camera();``` as I don't have a camera entity to develop against.

composer.json

@@ -7,7 +7,16 @@
         "Home Assistant",
         "Smart Tech",
         "Rest API",
-        "Guzzle"
+        "Webhook",
+        "HTTPlug",
+        "PSR-7",
+        "PSR-7: HTTP message interfaces",
+        "PSR-17",
+        "PSR-17: HTTP Factories",
+        "PSR-18",
+        "PSR-18: HTTP Client",
+        "PHP-FIG",
+        "PHP"
     ],
     "homepage": "https://github.com/indexzer0/ha-rest-api-client",
     "license": "MIT",
@@ -20,11 +29,17 @@
     ],
     "require": {
         "php": "^8.2",
-        "guzzlehttp/guzzle": "^7.8"
+        "php-http/client-common": "^2.4",
+        "php-http/discovery": "^1.19",
+        "php-http/httplug": "^2.4"
     },
     "require-dev": {
+        "guzzlehttp/guzzle": "^7.8",
+        "guzzlehttp/psr7": "^2.0",
         "laravel/pint": "^1.0",
+        "php-http/mock-client": "^1.6",
         "phpunit/phpunit": "^11.0",
+        "robiningelbrecht/phpunit-pretty-print": "^1.3",
         "spatie/ray": "^1.28"
     },
     "autoload": {
@@ -45,7 +60,8 @@
     "config": {
         "sort-packages": true,
         "allow-plugins": {
-            "phpstan/extension-installer": true
+            "phpstan/extension-installer": true,
+            "php-http/discovery": false
         }
     },
     "minimum-stability": "dev",

phpunit.xml.dist

@@ -35,4 +35,8 @@
             <directory suffix=".php">./src</directory>
         </include>
     </source>
+    <extensions>
+        <bootstrap class="RobinIngelbrecht\PHPUnitPrettyPrint\PhpUnitExtension">
+        </bootstrap>
+    </extensions>
 </phpunit>

src/Exception/HaException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+use Exception;
+
+class HaException extends Exception implements HaExceptionInterface
+{
+}

src/Exception/HaExceptionInterface.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+use Throwable;
+
+interface HaExceptionInterface extends Throwable
+{
+}

src/Exception/HttpClientException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+class HttpClientException extends HttpException
+{
+}

src/Exception/HttpException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+class HttpException extends HaException
+{
+}

src/Exception/HttpServerException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+class HttpServerException extends HttpException
+{
+}

src/Exception/InvalidArgumentException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+use InvalidArgumentException as BaseInvalidArgumentException;
+
+class InvalidArgumentException extends BaseInvalidArgumentException implements HaExceptionInterface
+{
+}

src/Exception/UnknownErrorException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace IndexZer0\HaRestApiClient\Exception;
+
+use Throwable;
+
+class UnknownErrorException extends HaException
+{
+    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct('Unknown Error.', $code, $previous);
+    }
+}