Update README and add CHANGELOG (#58)

* Minor code-doc changes

* Add changelog

* Update README.md

* Change author information to real name

Author: Namoshek

CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## Version `v1.0.0`
+
+Significant improvements to the architecture, API and design of the library have been part of `v1.0.0`.
+Upgrading should be rather simple for most users though, since the public API has not changed a lot
+and only in places which are not used too frequently.
+
+A lot of effort has been put into this summary to document as many changes as possible.
+It is impossible to give a guarantee about the completeness of this list though.
+You should cover your uses of the library with tests yourself as well.
+
+The following summary compares `v0.3.0` to `v1.0.0`.
+
+### Breaking Changes
+
+- The library does now require PHP 7.4 and supports PHP 8.0. This move was made with the clear intention to drop support for PHP 7.4 at some point.
+- The primary interface and class of the library have been renamed to StudlyCaps to follow PSR-2:
+  - `\PhpMqtt\Client\Contracts\MQTTClient` → `\PhpMqtt\Client\Contracts\MqttClient`
+  - `\PhpMqtt\Client\MQTTClient` → `\PhpMqtt\Client\MqttClient`
+  - `\PhpMqtt\Client\Exceptions\MQTTClientException` → `\PhpMqtt\Client\Exceptions\MqttClientException`
+- Protocol specific logic has been extracted from the `MQTTClient` class to a new interface `\PhpMqtt\Client\Contracts\MessageProcessor` and the respective implementation for MQTT 3.1, `\PhpMqtt\Client\MessageProcessors\Mqtt31MessageProcessor`.
+  - The `MessageProcessor` is responsible for parsing and building packages on a byte level.
+  - Splitting the logic from the main class did not only reduce the overall complexity of the class, it also made testing a lot easier and builds a solid foundation for future development and extension by implementing more protocol versions (like MQTT 5).
+- Some `protected` properties have been changed to `private` to ensure they are not manipulated outside the offered scope, which is enforced through getters and setters. This change only affects users which actively inherited their own implementation from the library.
+- The QoS 2 message flow is now implemented properly and should just work.
+  
+#### Connection Settings
+
+- The `$caFile` parameter of the `MQTTClient` constructor as well as the `$username` and `$password` parameters of the `MQTTClient::connect()` method have been moved to the `ConnectionSettings` class.
+- The `ConnectionSettings` use fluent setters for configuration now ([see README](README.md)). 
+- The `ConnectionSettings`` passed to `MQTTClient::connect()` are now validated and may not contain invalid configuration. In case of invalid configuration, a `\PhpMqtt\Client\Exceptions\ConfigurationInvalidException` is thrown.
+- Additional TLS options have been added to the `ConnectionSettings` to support more uses cases with secured connections.
+
+#### Methods
+
+- Most methods can now throw a `\PhpMqtt\Client\Exceptions\RepositoryException` if an interaction with the repository fails. This should happen with the `MemoryRepository` only in exceptional situations, but when implementing persisted repositories, this may happen more frequently and should therefore be considered.
+- The `MQTTClient::connect()` method had a parameter called `$sendCleanSessionFlag` while the `MqttClient::connect()` method has the same parameter, but called `$useCleanSession`. The parameters `$username` and `$password` have been removed entirely and are now part of the `ConnectionSettings`.
+- The method `MQTTClient::close()` has been renamed to `MqttClient::disconnect()`.
+- The parameter `$topic` of `MQTTClient::subscribe()` has been renamed to `$topicFilter` to reflect its meaning (which is a topic, but with wildcards). The `$callback` parameter can be `null` now and has `null` as default.
+- The parameter `$topic` of `MQTTClient::unsubscribe()` has been renamed to `$topicFilter` as well.
+
+#### Exceptions
+
+- New exceptions have been introduced and old ones were removed. All exceptions inherit from `\PhpMqtt\Client\Exceptions\MqttClientException` as base. You should ensure your calls to methods of the `MqttClient` handle the exceptions appropriately.
+- The exception constants previously defined on the `\PhpMqtt\Client\MQTTClient` class have been moved to the respective exception classes. This change only affects you if you used these constants to render detailed exception information for your users.
+
+#### Repositories
+
+- The `\PhpMqtt\Client\Contracts\Repository` interface has been changed significantly and summarizing all changes would be quite hard anyway. We therefore encourage you to have a look at the interface again and update your own implementation(s) of it, if you have any.
+
+#### Logger
+
+- The `\PhpMqtt\Client\Logger` implementation of `Psr\Log\LoggerInterface` does now decorate the log output with details about the MQTT client (format: `MQTT [{host}:{port}] [{clientId}] {message}`).
+
+### Additions
+
+- It is now possible to register event handlers for received messages. In combination with subscriptions without a callback, this allows to use centralized logic for multiple subscriptions. It also can be used for centralized logging, for example.
+- A lot of unit and integration tests have been added which cover most parts of the library, especially the non-exception paths.
+- All unit tests, integration tests, and the code style are enforced using a GitHub Actions workflow which runs under Ubuntu against multiple MQTT brokers (currently Mosquitto, HiveMQ and EMQ X). Contributing became easier therefore, but we expect that tests are added for changes and additions.
+  - To run the tests locally, an MQTT broker without authorization needs to run at `localhost:1883` (or the configuration in `phpunit.xml` is changed instead).
+- The project is now analyzed using [sonarcloud.io](https://sonarcloud.io/dashboard?id=php-mqtt_client) which helps us keep up the high standards of the library.
+
+#### Methods
+
+- `MqttClient::isConnected()`: returns `true` if a connection is established (socket opened), and `false` otherwise.
+- `MqttClient::getReceivedBytes()`: returns the number of raw bytes received from the broker (this includes meta information and not only message contents).
+- `MqttClient::getSentBytes()`: returns the number of raw bytes sent to the broker (this includes meta information and not only message contents).
+
+### Removals
+
+_No functionality has been removed in this version._

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) Namoshek <namoshek@gmx.at>
+Copyright (c) Marvin Mall <marvin-mall@msn.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -11,23 +11,28 @@
 [![License](https://poser.pugx.org/php-mqtt/client/license)](https://packagist.org/packages/php-mqtt/client)
 
 [`php-mqtt/client`](https://packagist.org/packages/php-mqtt/client) was created by, and is maintained
-by [Namoshek](https://github.com/namoshek).
+by [Marvin Mall](https://github.com/namoshek).
 It allows you to connect to an MQTT broker where you can publish messages and subscribe to topics.
 The current implementation supports all QoS levels ([with limitations](#limitations)).
 
 ## Installation
 
+The package is available on [packagist.org](https://packagist.org/packages/php-mqtt/client) and can be installed using `composer`:
+
 ```bash
 composer require php-mqtt/client
 ```
 
-This library requires PHP version 7.4 or higher.
+The package requires PHP version 7.4 or higher.
 
 ## Usage
 
+In the following, only a few very basic examples are given. For more elaborate examples, have a look at the
+[`php-mqtt/client-examples` repository](https://github.com/php-mqtt/client-examples).
+
 ### Publish
 
-A very basic publish example requires only three steps: connect, publish and close
+A very basic publish example using QoS 0 requires only three steps: connect, publish and disconnect
 
 ```php
 $server   = 'some-broker.example.com';
@@ -46,9 +51,11 @@ Be also aware that most of the methods can throw exceptions. The above example d
 
 ### Subscribe
 
-Subscribing is a little more complex than publishing as it requires to run an event loop:
+Subscribing is a little more complex than publishing as it requires to run an event loop which reads, parses and handles messages from the broker:
 
 ```php
+$server   = 'some-broker.example.com';
+$port     = 1883;
 $clientId = 'test-subscriber';
 
 $mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);
@@ -90,7 +97,7 @@ Lastly, a logger can be passed as sixth parameter. If none is given, a null logg
 
 Example:
 ```php
-$mqtt = new \PhpMqtt\Client\MQTTClient(
+$mqtt = new \PhpMqtt\Client\MqttClient(
     $server, 
     $port, 
     $clientId,
@@ -104,15 +111,19 @@ The `Logger` must implement the `Psr\Log\LoggerInterface`.
 
 ### Connection Settings
 
-The `connect()` method of the `MQTTClient` takes two optional parameters:
+The `connect()` method of the `MqttClient` takes two optional parameters:
 1. A `ConnectionSettings` instance
 2. A `boolean` flag indicating whether a clean session should be requested (a random client id does this implicitly)
 
 Example:
 ```php
-$mqtt = new \PhpMqtt\Client\MQTTClient($server, $port, $clientId);
+$mqtt = new \PhpMqtt\Client\MqttClient($server, $port, $clientId);
 
-$connectionSettings = new \PhpMqtt\Client\ConnectionSettings();
+$connectionSettings = (new \PhpMqtt\Client\ConnectionSettings)
+    ->setConnectTimeout(3)
+    ->setUseTls(true)
+    ->setTlsSelfSignedAllowed(true);
+    
 $mqtt->connect($connectionSettings, true);
 ```
 
@@ -123,7 +134,7 @@ This also prevents changes to the connection settings after a connection has bee
 The following is a complete list of options with their respective default:
 
 ```php
-$connectionSettings = (new \PhpMqtt\Client\ConnectionSettings())
+$connectionSettings = (new \PhpMqtt\Client\ConnectionSettings)
     ->setUsername(null)
     ->setPassword(null)
     ->setConnectTimeout(60)
@@ -147,7 +158,7 @@ $connectionSettings = (new \PhpMqtt\Client\ConnectionSettings())
 
 ## Features
 
-- MQTT Versions
+- Supported MQTT Versions
   - [x] v3 (just don't use v3.1 features like username & password)
   - [x] v3.1
   - [ ] v3.1.1
@@ -157,11 +168,9 @@ $connectionSettings = (new \PhpMqtt\Client\ConnectionSettings())
   - [x] TLS (secured, verifies the peer using a certificate authority file)
 - Connect
   - [x] Last Will
-  - [x] Last Will Topic
-  - [x] Last Will Message
-  - [x] Required QoS
   - [x] Message Retention
   - [x] Authentication (username & password)
+  - [x] TLS encrypted connections
   - [ ] Clean Session (can be set and sent, but the client has no persistence for QoS 2 messages)
 - Publish
   - [x] QoS Level 0

composer.json

@@ -11,8 +11,8 @@
     "license": "MIT",
     "authors": [
         {
-            "name": "Namoshek",
-            "email": "namoshek@gmx.at",
+            "name": "Marvin Mall",
+            "email": "marvin-mall@msn.com",
             "role": "developer"
         }
     ],

src/ConnectionSettings.php

@@ -153,7 +153,7 @@ public function getResendTimeout(): int
     /**
      * The keep alive interval is the number of seconds the client will wait without sending a message
      * until it sends a keep alive signal (ping) to the broker. The value cannot be less than 1 second
-     * and may not be higher than 65536 seconds. A reasonable value is 10 seconds (the default).
+     * and may not be higher than 65535 seconds. A reasonable value is 10 seconds (the default).
      *
      * @param int $keepAliveInterval
      * @return ConnectionSettings

src/Logger.php

@@ -10,6 +10,7 @@
 /**
  * Wrapper for another logger. Drops logged messages if no logger is available.
  *
+ * @internal This class is not part of the public API of the library and used internally only.
  * @package PhpMqtt\Client
  */
 class Logger implements LoggerInterface