Client
class Client (View source)
Constants
| LOG_DEBUG |
Identifies a debug-level log message |
| LOG_INFO |
Identifies an info-level log message |
| LOG_NOTICE |
Identifies a notice-level log message |
| LOG_WARNING |
Identifies a warning-level log message |
| LOG_ERR |
Identifies an error-level log message |
| SSL_VERIFY_NONE |
Used with |
| SSL_VERIFY_PEER |
Used with |
Methods
Construct a new Client instance.
Set the username and password to use on connecting to the broker. Must be called before connect.
Configure the client for certificate based SSL/TLS support. Must be called before connect. Cannot be used in conjunction with setTlsPSK.
Configure verification of the server hostname in the server certificate. If $value is true, it is impossible
to guarantee that the host you are connecting to is not impersonating your server. Do not use this function in a
real system. Must be called before connect.
Set advanced SSL/TLS options. Must be called before connect.
Configure the client for pre-shared-key based TLS support. Must be called before connect. Cannot be used in
conjunction with setTlsCertificates.
Set the client “last will and testament”, which will be sent on an unclean disconnection from the broker.
Remove a previously-set will. No parameters.
Control the behaviour of the client when it has unexpectedly disconnected in Client::loopForever().
Connect to an MQTT broker.
Disconnect from the broker. No parameters.
Set the connect callback. This is called when the broker sends a CONNACK message in response to a connection.
Set the disconnect callback. This is called when the broker has received the DISCONNECT command and has disconnected the client.
Set the logging callback.
Set the subscribe callback. This is called when the broker responds to a subscription request.
Set the unsubscribe callback. This is called when the broker responds to a unsubscribe request.
Set the message callback. This is called when a message is received from the broker.
Set the publish callback. This is called when a message is published by the client itself.
Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An in flight message is part way through its delivery flow. Attempts to send further messages with publish will result in the messages being queued until the number of in flight messages reduces.
Set the number of seconds to wait before retrying messages. This applies to publishing messages with QoS > 0.
Publish a message on a given topic.
Subscribe to a topic.
Unsubscribe from a topic.
The main network loop for the client. You must call this frequently in order to keep communications between
the client and broker working. If incoming data is present it will then be processed. Outgoing commands,
from e.g. publish, are normally sent immediately that their function is called, but this is not always possible.
Call loop() in an infinite blocking loop. Callbacks will be called as required. This will handle reconnecting
if the connection is lost. Call disconnect in a callback to disconnect and return from the loop. Alternatively,
call exitLoop to exit the loop without disconnecting. You will need to re-enter the loop again afterwards
to maintain the connection.
Exit the loopForever event loop without disconnecting. You will need to re-enter the loop afterwards
in order to maintain the connection.
Details
__construct(string|null $id = null, bool $cleanSession = true)
Construct a new Client instance.
setCredentials(string $username, string $password)
Set the username and password to use on connecting to the broker. Must be called before connect.
int|null
setTlsCertificates(string $caPath, string|null $certFile = null, string|null $keyFile = null, string|null $password = null)
Configure the client for certificate based SSL/TLS support. Must be called before connect. Cannot be used in conjunction with setTlsPSK.
Define the Certificate Authority certificates to be trusted (ie. the server certificate must be signed with one of these certificates) using $caFile. If the server you are connecting to requires clients to provide a certificate, define $certFile and $keyFile with your client certificate and private key. If your private key is encrypted, provide the password as the fourth parameter.
setTlsInsecure(bool $value)
Configure verification of the server hostname in the server certificate. If $value is true, it is impossible
to guarantee that the host you are connecting to is not impersonating your server. Do not use this function in a
real system. Must be called before connect.
int
setTlsOptions(int $certReqs, string|null $tlsVersion = null, string|null $ciphers = null)
Set advanced SSL/TLS options. Must be called before connect.
int
setTlsPSK(string $psk, string $identity, string|null $ciphers = null)
Configure the client for pre-shared-key based TLS support. Must be called before connect. Cannot be used in
conjunction with setTlsCertificates.
setWill(string $topic, string $payload, int $qos = 0, bool $retain = false)
Set the client “last will and testament”, which will be sent on an unclean disconnection from the broker.
Must be called before connect.
clearWill()
Remove a previously-set will. No parameters.
setReconnectDelay(int $reconnectDelay, int $exponentialDelay = 0, bool $exponentialBackoff = false)
Control the behaviour of the client when it has unexpectedly disconnected in Client::loopForever().
The default behaviour if this method is not used is to repeatedly attempt to reconnect with a delay of 1 second until the connection succeeds.
int
connect(string $host, int $port = 1883, int $keepalive = 60, string|null $interface = null)
Connect to an MQTT broker.
disconnect()
Disconnect from the broker. No parameters.
onConnect(callable $callback)
Set the connect callback. This is called when the broker sends a CONNACK message in response to a connection.
(int) $rc, (string) $message function ($rc, $message) }
Response codes: 0 = Success 1 = Connection refused (unacceptable protocol version) 2 = Connection refused (identifier rejected) 3 = Connection refused (broker unavailable) 4-255 = Reserved for future use
onDisconnect(callable $callback)
Set the disconnect callback. This is called when the broker has received the DISCONNECT command and has disconnected the client.
(int) $rc function ($rc) }
Response codes: 0 = requested by client <0 = indicates an unexpected disconnection.
onLog(callable $callback)
Set the logging callback.
(int) $level, (string) $str function ($level, $str) }
Log levels: Client::LOG_DEBUG Client::LOG_INFO Client::LOG_NOTICE Client::LOG_WARNING Client::LOG_ERR
onSubscribe(callable $callback)
Set the subscribe callback. This is called when the broker responds to a subscription request.
(int) $mid, (int) $qosCount function ($mid, $qosCount) }
onUnsubscribe(callable $callback)
Set the unsubscribe callback. This is called when the broker responds to a unsubscribe request.
(int) $mid function ($mid) }
onMessage(callable $callback)
Set the message callback. This is called when a message is received from the broker.
(object) $message function (Mosquitto\Message $message) }
onPublish(callable $callback)
Set the publish callback. This is called when a message is published by the client itself.
Warning: this may be called before the method publish returns the message id, so, you need to create a queue to deal with the MID list.
(int) $mid - the message id returned by publish
function ($mid) }
setMaxInFlightMessages(int $maxInFlightMessages)
Set the number of QoS 1 and 2 messages that can be “in flight” at one time. An in flight message is part way through its delivery flow. Attempts to send further messages with publish will result in the messages being queued until the number of in flight messages reduces.
Set to 0 for no maximum.
setMessageRetry(int $messageRetryPeriod)
Set the number of seconds to wait before retrying messages. This applies to publishing messages with QoS > 0.
May be called at any time.
int
publish(string $topic, string $payload, int $qos = 0, bool $retain = false)
Publish a message on a given topic.
Return the message ID returned by the broker. Warning: the message ID is not unique.
int
subscribe(string $topic, int $qos)
Subscribe to a topic.
Return the message ID of the subscription message, so this can be matched up in the onSubscribe callback.
int
unsubscribe(string $topic, int $qos)
Unsubscribe from a topic.
Return the message ID of the subscription message, so this can be matched up in the onUnsubscribe callback.
loop(int $timeout = 1000)
The main network loop for the client. You must call this frequently in order to keep communications between
the client and broker working. If incoming data is present it will then be processed. Outgoing commands,
from e.g. publish, are normally sent immediately that their function is called, but this is not always possible.
loop will also attempt to send any remaining outgoing messages, which also includes commands that are part
of the flow for messages with QoS > 0.
loopForever(int $timeout = 1000)
Call loop() in an infinite blocking loop. Callbacks will be called as required. This will handle reconnecting
if the connection is lost. Call disconnect in a callback to disconnect and return from the loop. Alternatively,
call exitLoop to exit the loop without disconnecting. You will need to re-enter the loop again afterwards
to maintain the connection.
exitLoop()
Exit the loopForever event loop without disconnecting. You will need to re-enter the loop afterwards
in order to maintain the connection.