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).
• 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 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.