Update the package for v1 of the MQTT client (#1)

* Update composer packages and untrack composer.lock

* Update code and config for v1.0.0-rc1

* Use contract instead of implementation

* Update README.md

Author: Namoshek

.gitignore

@@ -1,2 +1,3 @@
 /.idea/
 /vendor/
+composer.lock

README.md

@@ -1,13 +1,17 @@
 # php-mqtt/laravel-client
 
-**:warning: Work in progress - use at own risk! :warning:** 
+[![Latest Stable Version](https://poser.pugx.org/php-mqtt/laravel-client/v)](https://packagist.org/packages/php-mqtt/laravel-client)
+[![Total Downloads](https://poser.pugx.org/php-mqtt/laravel-client/downloads)](https://packagist.org/packages/php-mqtt/laravel-client)
+[![License](https://poser.pugx.org/php-mqtt/laravel-client/license)](https://packagist.org/packages/php-mqtt/laravel-client)
 
-`php-mqtt/laravel-client` was created by, and is maintained by [Namoshek](https://github.com/namoshek).
+`php-mqtt/laravel-client` was created by, and is maintained by [Marvin Mall](https://github.com/namoshek).
 It is a Laravel wrapper for the [`php-mqtt/client`](https://github.com/php-mqtt/client) package and
 allows you to connect to an MQTT broker where you can publish messages and subscribe to topics.
 
 ## Installation
 
+The package is available on [packagist.org](https://packagist.org/packages/php-mqtt/laravel-client) and can be installed using composer:
+
 ```bash
 composer require php-mqtt/laravel-client
 ```
@@ -18,20 +22,17 @@ Registered will be the service provider as well as an `MQTT` facade.
 After installing the package, you should publish the configuration file using
 
 ```bash
-php artisan vendor:publish --provider="PhpMqtt\Client\MqttClientServiceProvider"
+php artisan vendor:publish --provider="PhpMqtt\Client\MqttClientServiceProvider" --tag="config"
 ```
 
 and change the configuration in `config/mqtt-client.php` according to your needs.
 
 ## Configuration
 
-The package allows you to configure multiple named connections. An initial example
-can be found in the published configuration file. Except for the `host` parameter,
-all configuration options are entirely optional and come with the defaults provided 
-to the `env()` helper in the example configuration file (no default means `null`).
+The package allows you to configure multiple named connections. An initial example with inline documentation can be found in the published configuration file.
+Most of the configuration options are optional and come with sane defaults (especially all of the `connection_settings`).
 
-An example configuration of two connections, where one is meant for sharing public
-data and one for private data, could look like the following:
+An example configuration of two connections, where one is meant for sharing public data and one for private data, could look like the following:
 ```php
 'default_connection' => 'private',
 
@@ -48,6 +49,8 @@ data and one for private data, could look like the following:
 ```
 In this example, the private connection is the default one.
 
+_Note: it is recommended to use environment variables to configure the MQTT client. Available environment variables can be found in the configuration file._
+
 ## Usage
 
 ### Publish (QoS level 0)
@@ -59,53 +62,64 @@ use PhpMqtt\Client\Facades\MQTT;
 MQTT::publish('some/topic', 'Hello World!');
 ```
 
-If needed, the connection name can be passed as third parameter:
+If needed, the _retain_ flag (default: `false`) can be passed as third and the connection name as fourth parameter:
 ```php
 use PhpMqtt\Client\Facades\MQTT;
 
-MQTT::publish('some/topic', 'Hello World!', 'public');
+MQTT::publish('some/topic', 'Hello World!', true, 'public');
 ```
 
-Using `MQTT::publish($topic, $message)` will implicitly call `MQTT::connection()`,
-but the connection will not be closed after usage. If you want to close the connection
-manually because your script does not need the connection any more, you can call
-`MQTT:close()` (optionally with the connection name as a parameter).
+Using `MQTT::publish($topic, $message)` will implicitly call `MQTT::connection()`, but the connection will not be closed after usage.
+If you want to close the connection manually because your script does not need the connection anymore,
+you can call `MQTT:disconnect()` (optionally with the connection name as a parameter).
 Please also note that using `MQTT::publish($topic, $message)` will always use QoS level 0.
-If you need a different QoS level, then please follow the instructions below.
+If you need a different QoS level, you will need to use the `MqttClient` directly which is explained below.
 
 ### Publish (QoS level 1 & 2)
 
 Different to QoS level 0, we need to run an event loop in order for QoS 1 and 2 to work.
-This is because with a one-off command we cannot guarantee that a message reaches it's target.
-The event loop will ensure a published message gets sent again if no acknowledgment is returned
-by the broker within a grace period (in case of QoS level 1). Also handled by the event loop will
-be the release of packages in case of QoS level 2.
+This is because with a one-off command we cannot guarantee that a message reaches its target.
+The event loop will ensure a published message gets sent again if no acknowledgment is returned by the broker within a grace period.
+Only when the broker returns an acknowledgement (or all of the acknowledgements in case of QoS 2),
+the client will stop resending the message.
 
 ```php
 use PhpMqtt\Client\Facades\MQTT;
 
+/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
 $mqtt = MQTT::connection();
 $mqtt->publish('some/topic', 'foo', 1);
-$mqtt->publish('some/other/topic', 'bar', 2);
+$mqtt->publish('some/other/topic', 'bar', 2, true); // Retain the message
 $mqtt->loop(true);
 ```
 
-In order to escape the loop, you can call `$mqtt->interrupt()` which will exit the loop during
-the next iteration. The method can for example be called in a registered signal handler:
+`$mqtt->loop()` actually starts an infinite loop. To escape it, there are multiple options.
+In case of simply publishing a message, all we want is to receive an acknowledgement.
+Therefore, we can simply pass `true` as second parameter to exit the loop as soon as all resend queues are cleared:
+
 ```php
-pcntl_signal(SIGINT, function (int $signal, $info) use ($mqtt) {
+/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
+$mqtt->loop(true, true);
+```
+
+In order to escape the loop, you can also call `$mqtt->interrupt()` which will exit the loop during
+the next iteration. The method can, for example, be called in a registered signal handler:
+```php
+/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
+pcntl_signal(SIGINT, function () use ($mqtt) {
     $mqtt->interrupt();
 });
 ```
 
 ### Subscribe
 
 Very similar to publishing with QoS level 1 and 2, subscribing requires to run an event loop.
-But before running the loop, topics need to be subscribed to:
+Although before running the loop, topics need to be subscribed to:
 
 ```php
 use PhpMqtt\Client\Facades\MQTT;
 
+/** @var \PhpMqtt\Client\Contracts\MqttClient $mqtt */
 $mqtt = MQTT::connection();
 $mqtt->subscribe('some/topic', function (string $topic, string $message) {
     echo sprintf('Received QoS level 1 message on topic [%s]: %s', $topic, $message);
@@ -116,7 +130,11 @@ $mqtt->loop(true);
 ## Features
 
 This library allows you to use all the features provided by [`php-mqtt/client`](https://github.com/php-mqtt/client).
+Simply retrieve an instance of `\PhpMqtt\Client\Contracts\MqttClient` with `MQTT::connection(string $name = null)` and use it directly.
+
+For an extensive collection of examples which explain how to use the MQTT client (directly),
+you can visit the [`php-mqtt/client-examples` repository](https://github.com/php-mqtt/client-examples).
 
 ## License
 
-`php-mqtt/laravel-client` is open-sourced software licensed under the [MIT license](LICENSE.md).
+`php-mqtt/laravel-client` is open-source software licensed under the [MIT license](LICENSE.md).

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "php-mqtt/laravel-client",
-  "description": "An MQTT client library for Laravel.",
+  "description": "A wrapper for the php-mqtt/client library for Laravel.",
   "type": "library",
   "keywords": [
     "mqtt",
@@ -13,16 +13,16 @@
   "license": "MIT",
   "authors": [
     {
-      "name": "Namoshek",
-      "email": "namoshek@gmx.at",
+      "name": "Marvin Mall",
+      "email": "marvin-mall@msn.com",
       "role": "developer"
     }
   ],
   "require": {
-    "php": "^7.2",
-    "illuminate/config": "~5.8|~6.0",
-    "illuminate/support": "~5.8|~6.0",
-    "php-mqtt/client": "0.1.*"
+    "php": "^7.4|^8.0",
+    "illuminate/config": "~7.0|~8.0",
+    "illuminate/support": "~7.0|~8.0",
+    "php-mqtt/client": "v1.0.0-rc1"
   },
   "autoload": {
     "psr-4": {