MqttClient
in
An interface for the MQTT client.
Table of Contents
- connect() : void
- Connect to the MQTT broker using the given settings.
- disconnect() : void
- Sends a disconnect message to the broker and closes the socket.
- getClientId() : string
- Returns the identifier used by the client.
- getHost() : string
- Returns the host used by the client to connect to.
- getPort() : int
- Returns the port used by the client to connect to.
- getReceivedBytes() : int
- Returns the total number of received bytes, across reconnects.
- getSentBytes() : int
- Returns the total number of sent bytes, across reconnects.
- interrupt() : void
- Sets the interrupted signal. Doing so instructs the client to exit the loop, if it is actually looping.
- isConnected() : bool
- Returns an indication, whether the client is supposed to be connected already or not.
- loop() : void
- Runs an event loop that handles messages from the server and calls the registered callbacks for published messages.
- loopOnce() : void
- Runs an event loop iteration that handles messages from the server and calls the registered callbacks for published messages. Also resends pending messages and calls loop event handlers.
- publish() : void
- Publishes the given message on the given topic. If the additional quality of service and retention flags are set, the message will be published using these settings.
- registerLoopEventHandler() : MqttClient
- Registers a loop event handler which is called each iteration of the loop.
- registerMessageReceivedEventHandler() : MqttClient
- Registers an event handler which is called when a message is received from the broker.
- registerPublishEventHandler() : MqttClient
- Registers a loop event handler which is called when a message is published.
- subscribe() : void
- Subscribe to the given topic with the given quality of service.
- unregisterLoopEventHandler() : MqttClient
- Unregisters a loop event handler which prevents it from being called in the future.
- unregisterMessageReceivedEventHandler() : MqttClient
- Unregisters a message received event handler which prevents it from being called in the future.
- unregisterPublishEventHandler() : MqttClient
- Unregisters a publish event handler which prevents it from being called in the future.
- unsubscribe() : void
- Unsubscribe from the given topic.
Methods
connect()
Connect to the MQTT broker using the given settings.
public
connect([ConnectionSettings|null $settings = null ][, bool $useCleanSession = false ]) : void
If no custom settings are passed, the client will use the default settings. See ConnectionSettings for more details about the defaults.
Parameters
- $settings : ConnectionSettings|null = null
- $useCleanSession : bool = false
Tags
Return values
void —disconnect()
Sends a disconnect message to the broker and closes the socket.
public
disconnect() : void
Tags
Return values
void —getClientId()
Returns the identifier used by the client.
public
getClientId() : string
Return values
string —getHost()
Returns the host used by the client to connect to.
public
getHost() : string
Return values
string —getPort()
Returns the port used by the client to connect to.
public
getPort() : int
Return values
int —getReceivedBytes()
Returns the total number of received bytes, across reconnects.
public
getReceivedBytes() : int
Return values
int —getSentBytes()
Returns the total number of sent bytes, across reconnects.
public
getSentBytes() : int
Return values
int —interrupt()
Sets the interrupted signal. Doing so instructs the client to exit the loop, if it is actually looping.
public
interrupt() : void
Sending multiple interrupt signals has no effect, unless the client exits the loop, which resets the signal for another loop.
Return values
void —isConnected()
Returns an indication, whether the client is supposed to be connected already or not.
public
isConnected() : bool
Note: the result of this method should be used carefully, since we can only detect a closed socket once we try to send or receive data. Therefore, this method only gives an indication whether the client is in a connected state or not.
This information may be useful in applications where multiple parts use the client.
Return values
bool —loop()
Runs an event loop that handles messages from the server and calls the registered callbacks for published messages.
public
loop([bool $allowSleep = true ][, bool $exitWhenQueuesEmpty = false ][, int|null $queueWaitLimit = null ]) : void
If the second parameter is provided, the loop will exit as soon as all queues are empty. This means there may be no open subscriptions, no pending messages as well as acknowledgments and no pending unsubscribe requests.
The third parameter will, if set, lead to a forceful exit after the specified amount of seconds, but only if the second parameter is set to true. This basically means that if we wait for all pending messages to be acknowledged, we only wait a maximum of $queueWaitLimit seconds until we give up. We do not exit after the given amount of time if there are open topic subscriptions though.
Parameters
- $allowSleep : bool = true
- $exitWhenQueuesEmpty : bool = false
- $queueWaitLimit : int|null = null
Tags
Return values
void —loopOnce()
Runs an event loop iteration that handles messages from the server and calls the registered callbacks for published messages. Also resends pending messages and calls loop event handlers.
public
loopOnce(float $loopStartedAt[, bool $allowSleep = false ][, int $sleepMicroseconds = 100000 ]) : void
This method can be used to integrate the MQTT client in another event loop (like ReactPHP or Ratchet).
Note: To ensure the event handlers called by this method will receive the correct elapsed time,
the caller is responsible to provide the correct starting time of the loop as returned by microtime(true).
Parameters
- $loopStartedAt : float
- $allowSleep : bool = false
- $sleepMicroseconds : int = 100000
Tags
Return values
void —publish()
Publishes the given message on the given topic. If the additional quality of service and retention flags are set, the message will be published using these settings.
public
publish(string $topic, string $message, int $qualityOfService[, bool $retain = false ]) : void
Parameters
- $topic : string
- $message : string
- $qualityOfService : int
- $retain : bool = false
Tags
Return values
void —registerLoopEventHandler()
Registers a loop event handler which is called each iteration of the loop.
public
registerLoopEventHandler(Closure $callback) : MqttClient
This event handler can be used for example to interrupt the loop under certain conditions.
The loop event handler is passed the MQTT client instance as first and the elapsed time which the loop is already running for as second parameter. The elapsed time is a float containing seconds.
Example:
$mqtt->registerLoopEventHandler(function (
MqttClient $mqtt,
float $elapsedTime
) use ($logger) {
$logger->info("Running for [{$elapsedTime}] seconds already.");
});
Multiple event handlers can be registered at the same time.
Parameters
- $callback : Closure
Return values
MqttClient —registerMessageReceivedEventHandler()
Registers an event handler which is called when a message is received from the broker.
public
registerMessageReceivedEventHandler(Closure $callback) : MqttClient
The message received event handler is passed the MQTT client as first, the topic as second and the message as third parameter. As fourth parameter, the QoS level will be passed and the retained flag as fifth.
Example:
$mqtt->registerReceivedMessageEventHandler(function (
MqttClient $mqtt,
string $topic,
string $message,
int $qualityOfService,
bool $retained
) use ($logger) {
$logger->info("Received message on topic [{$topic}]: {$message}");
});
Multiple event handlers can be registered at the same time.
Parameters
- $callback : Closure
Return values
MqttClient —registerPublishEventHandler()
Registers a loop event handler which is called when a message is published.
public
registerPublishEventHandler(Closure $callback) : MqttClient
The loop event handler is passed the MQTT client as first, the topic as second and the message as third parameter. As fourth parameter, the message identifier will be passed. The QoS level as well as the retained flag will also be passed as fifth and sixth parameters.
Example:
$mqtt->registerPublishEventHandler(function (
MqttClient $mqtt,
string $topic,
string $message,
int $messageId,
int $qualityOfService,
bool $retain
) use ($logger) {
$logger->info("Received message on topic [{$topic}]: {$message}");
});
Multiple event handlers can be registered at the same time.
Parameters
- $callback : Closure
Return values
MqttClient —subscribe()
Subscribe to the given topic with the given quality of service.
public
subscribe(string $topicFilter[, callable|null $callback = null ], int $qualityOfService) : void
The subscription callback is passed the topic as first and the message as second parameter. A third parameter indicates whether the received message has been sent because it was retained by the broker. A fourth parameter contains matched topic wildcards.
Example:
$mqtt->subscribe(
'/foo/bar/+',
function (string $topic, string $message, bool $retained, array $matchedWildcards) use ($logger) {
$logger->info("Received {retained} message on topic [{topic}]: {message}", [
'topic' => $topic,
'message' => $message,
'retained' => $retained ? 'retained' : 'live'
]);
}
);
If no callback is passed, a subscription will still be made. Received messages are delivered only to event handlers for received messages though.
Parameters
- $topicFilter : string
- $callback : callable|null = null
- $qualityOfService : int
Tags
Return values
void —unregisterLoopEventHandler()
Unregisters a loop event handler which prevents it from being called in the future.
public
unregisterLoopEventHandler([Closure|null $callback = null ]) : MqttClient
This does not affect other registered event handlers. It is possible to unregister all registered event handlers by passing null as callback.
Parameters
- $callback : Closure|null = null
Return values
MqttClient —unregisterMessageReceivedEventHandler()
Unregisters a message received event handler which prevents it from being called in the future.
public
unregisterMessageReceivedEventHandler([Closure|null $callback = null ]) : MqttClient
This does not affect other registered event handlers. It is possible to unregister all registered event handlers by passing null as callback.
Parameters
- $callback : Closure|null = null
Return values
MqttClient —unregisterPublishEventHandler()
Unregisters a publish event handler which prevents it from being called in the future.
public
unregisterPublishEventHandler([Closure|null $callback = null ]) : MqttClient
This does not affect other registered event handlers. It is possible to unregister all registered event handlers by passing null as callback.
Parameters
- $callback : Closure|null = null
Return values
MqttClient —unsubscribe()
Unsubscribe from the given topic.
public
unsubscribe(string $topicFilter) : void
Parameters
- $topicFilter : string