This is an extension to allow using the Eclipse Mosquitto™ MQTT client library with PHP. See the examples/ directory for usage.

Thanks to Sara Golemon this extension now supports PHP 7. I would be grateful if anyone using PHP 7 could test it and let me know how it works out.

• PHP 5.3+
• libmosquitto 1.2.x or later
• Linux or Mac OS X. I do not have a Windows machine handy, though patches or pull requests are of course very welcome!

If you've used a pre-built package to install Mosquitto, you need to make sure you have the development headers installed. On Red Hat-derived systems, this is probably called libmosquitto-devel, and on Debian-based systems it will be libmosquitto-dev.

You may obtain this package using PECL:

pecl install Mosquitto-alpha

Alternatively, you can use the normal extension build process:

phpize
./configure --with-mosquitto=/path/to/libmosquitto
make
make install

Then add extension=mosquitto.so to your php.ini.

The --with-mosquitto argument is optional, and only required if your libmosquitto install cannot be found.

The underlying library is based on callbacks and asynchronous operation. As such, you have to call the loop() method of the Client frequently to permit the library to handle the messages in its queues. Also, you should use the callback functions to ensure that you only attempt to publish after the client has connected, etc. For example, here is how you would correctly publish a QoS=2 message:

<?php

$c = new Mosquitto\Client;
$c->onConnect(function() use ($c) {
    $c->publish('mgdm/test', 'Hello', 2);
});

$c->connect('test.mosquitto.org');

for ($i = 0; $i < 100; $i++) {
    // Loop around to permit the library to do its work
    $c->loop(1);
}

echo "Finished\n";

The classes in this extension are namespaced.

This is the actual Mosquitto client.

1. __construct - create a new client
2. setCredentials - set the credentials to use on connection
3. setTlsCertificates - set the TLS certificate sources
4. setTlsInsecure - Set verification of the server hostname in TLS certificates
5. setTlsOptions - Set advanced TLS options
6. setTlsPSK - Configure the client for pre-shared-key based TLS support.
7. setWill - set the client will, to be delivered if disconnected uncleanly
8. clearWill - clear a previously-set will
9. setReconnectDelay - set the behaviour if disconnected uncleanly
10. connect - connect to an MQTT broker
11. disconnect - disconnect from an MQTT broker
12. onConnect - set the connect callback
13. onDisconnect - set the disconnect callback
14. onLog - set the logging callback
15. onSubscribe - set the subscribe callback
16. onMessage - set the callback fired when a message is received
17. onPublish - set the callback fired when a message is published
18. setMaxInFlightMessages - set the number of QoS 1 and 2 messages that can be "in flight" at once
19. setMessageRetry - set the number of seconds to wait before retrying messages
20. publish - publish a message to a broker
21. subscribe - subscribe to a topic
22. unsubscribe - unsubscribe from a topic
23. loop - The main network loop
24. loopForever - run loop() in an infinite blocking loop

Creates 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().

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, or you will have to enter the password at the command line.

Configure verification of the server hostname in the server certificate. If value is set to 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. Must be called before connect().

Remove a previously-set will. No parameters.

Control the behaviour of the client when it has unexpectedly disconnected in 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.

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.

The callback should take parameters of the form:

Response codes are as follows:

Set the disconnect callback. This is called when the broker has received the DISCONNECT command and has disconnected the client.

The callback should take parameters of the form:

Set the logging callback.

The callback should take parameters of the form:

The level can be one of:

• Mosquitto\Client::LOG_DEBUG
• Mosquitto\Client::LOG_INFO
• Mosquitto\Client::LOG_NOTICE
• Mosquitto\Client::LOG_WARNING
• Mosquitto\Client::LOG_ERR

Set the subscribe callback. This is called when the broker responds to a subscription request.

The callback should take parameters of the form:

This function needs to return the granted QoS for each subscription, but currently cannot.

Set the unsubscribe callback. This is called when the broker responds to a unsubscribe request.

The callback should take parameters of the form:

Set the message callback. This is called when a message is received from the broker.

The callback should take parameters of the form:

Set the publish callback, This is called when a message is publish by the client itself.

Warning: this may be called before the method Mosquitto\Client::publish return the message id, so, you need to create a queue to deal with the mid list

The callback should take parameters of the form:

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.

Set the number of seconds to wait before retrying messages. This applies to publish messages with QoS>0. May be called at any time.

Publish a message on a given topic.

return int the message id in broker system Warning the message id is not unique

Subscribe to a topic.

Returns the message ID of the subscription message, so this can be matched up in the onSubscribe callback.

Unsubscribe from a topic.

Returns the message ID of the subscription message, so this can be matched up in the onUnsubscribe callback.

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.

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 return from the loop.

Note: exceptions thrown in callbacks do not currently cause the loop to exit. To work around this, use loop() and wrap your own loop structure around it such as a while().

Represents a message received from a broker. All data is represented as properties.

This class has two static methods.

Returns true if the supplied topic matches the supplied description, and otherwise false.

Tokenise a topic or subscription string into an array of strings representing the topic hierarchy.

This is an exception that may be thrown by many of the operations in the Client object.

• Arginfo
• Logging callbacks
• TLS support
• Tests