update examples

examples/README.md

@@ -1,6 +1,13 @@
 # Output example
 
-Before running each file be sure to review the four connection parameters in the headers.
+For info on MQTT: https://mntolia.com/fundamentals-mqtt/#4_Advantages_of_MQTT_for_IoT_over_HTTP_UDP
+
+> Before running each file be sure to review the four connection parameters in the headers.
+
+subscribe.php
+--
+This example is to demonstrate using MQTT for a long-running script that will wait for subscribed topics.
+This script is not suitable to be run as web requests, instead should be run on the commandline.
 
 Let `subscribe.php` listening the broker: 
 ```console
@@ -18,8 +25,20 @@ Topic: bluerhinos/phpMQTT/examples/publishtest
 ^C
 ```
 
+publish.php
+---
+This example will publish a message to a topic.
+
 The results shown above corresponds to publisher's two actions:
 ```console
 $ php publish.php
 $ php publish.php
 ```
+
+When run as a web request you it is ok to just `$mqtt->connect()`, `$mqtt->publish()` and `$mqtt->close()`.
+If it is being run as long-running command line script you should run `$mqtt->proc()` regularly in order maintain the connection with the broker.
+
+subscribeAndWaitForMessage.php
+--
+In order to use this library to display messages on a website you can use `$mqtt->subscribeAndWaitForMessage()`, this will subscribe to a topic and then wait for, and return the message.
+If you want messages to appear instantly, you should use retained messages (https://mntolia.com/mqtt-retained-messages-explained-example/)  

examples/publish.php

@@ -1,17 +1,17 @@
 <?php
 
-require("../phpMQTT.php");
+require('../phpMQTT.php');
 
-$server = "localhost";     // change if necessary
+$server = 'localhost';     // change if necessary
 $port = 1883;                     // change if necessary
-$username = "";                   // set your username
-$password = "";                   // set your password
-$client_id = "phpMQTT-publisher"; // make sure this is unique for connecting to sever - you could use uniqid()
+$username = '';                   // set your username
+$password = '';                   // set your password
+$client_id = 'phpMQTT-publisher'; // make sure this is unique for connecting to sever - you could use uniqid()
 
 $mqtt = new Bluerhinos\phpMQTT($server, $port, $client_id);
 
 if ($mqtt->connect(true, NULL, $username, $password)) {
-	$mqtt->publish("bluerhinos/phpMQTT/examples/publishtest", "Hello World! at " . date("r"), 0);
+	$mqtt->publish('bluerhinos/phpMQTT/examples/publishtest', 'Hello World! at ' . date('r'), 0, false);
 	$mqtt->close();
 } else {
     echo "Time out!\n";

examples/subscribe.php

@@ -1,31 +1,32 @@
 <?php
 
-require("../phpMQTT.php");
+require('../phpMQTT.php');
 
 
-$server = "localhost";     // change if necessary
+$server = 'localhost';     // change if necessary
 $port = 1883;                     // change if necessary
-$username = "";                   // set your username
-$password = "";                   // set your password
-$client_id = "phpMQTT-subscriber"; // make sure this is unique for connecting to sever - you could use uniqid()
+$username = '';                   // set your username
+$password = '';                   // set your password
+$client_id = 'phpMQTT-subscriber'; // make sure this is unique for connecting to sever - you could use uniqid()
 
 $mqtt = new Bluerhinos\phpMQTT($server, $port, $client_id);
 if(!$mqtt->connect(true, NULL, $username, $password)) {
 	exit(1);
 }
 
-$topics['bluerhinos/phpMQTT/examples/publishtest'] = array("qos" => 0, "function" => "procmsg");
+$mqtt->debug = true;
+
+$topics['bluerhinos/phpMQTT/examples/publishtest'] = array('qos' => 0, 'function' => 'procMsg');
 $mqtt->subscribe($topics, 0);
 
-while($mqtt->proc()){
-
-}
+while($mqtt->proc()) {
 
+}
 
 $mqtt->close();
 
-function procmsg($topic, $msg){
-		echo "Msg Recieved: " . date("r") . "\n";
+function procMsg($topic, $msg){
+		echo 'Msg Recieved: ' . date('r') . "\n";
 		echo "Topic: {$topic}\n\n";
 		echo "\t$msg\n\n";
 }

examples/subscribeAndWaitForMessage.php

@@ -0,0 +1,18 @@
+<?php
+
+require('../phpMQTT.php');
+
+$server = 'localhost';     // change if necessary
+$port = 1883;                     // change if necessary
+$username = '';                   // set your username
+$password = '';                   // set your password
+$client_id = 'phpMQTT-subscribe-msg'; // make sure this is unique for connecting to sever - you could use uniqid()
+
+$mqtt = new Bluerhinos\phpMQTT($server, $port, $client_id);
+if(!$mqtt->connect(true, NULL, $username, $password)) {
+	exit(1);
+}
+
+echo $mqtt->subscribeAndWaitForMessage('bluerhinos/phpMQTT/examples/publishtest', 0);
+
+$mqtt->close();

phpMQTT.php

@@ -385,9 +385,9 @@ public function close(): void
      * @param $topic
      * @param $content
      * @param int $qos
-     * @param int $retain
+     * @param bool $retain
      */
-    public function publish($topic, $content, $qos = 0, $retain = 0): void
+    public function publish($topic, $content, $qos = 0, $retain = false): void
     {
         $i = 0;
         $buffer = '';
@@ -410,7 +410,7 @@ public function publish($topic, $content, $qos = 0, $retain = 0): void
         if ($qos) {
             $cmd += $qos << 1;
         }
-        if ($retain) {
+        if (empty($retain) === false) {
             ++$cmd;
         }