suyuan-breed/vendor/php-mqtt/client/CHANGELOG.md

# 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._