Customer Queue Number System With PHP (Free Download)

Welcome to a tutorial on how to create a customer queue number system with PHP. Need to run an online queue number system? Or maybe in an intranet setting? Well, here’s a simple example built with WebSockets and PHP – Read on!

ⓘ I have included a zip file with all the source code at the start of this tutorial, so you don’t have to copy-paste everything… Or if you just want to dive straight in.

 

 

TABLE OF CONTENTS

 

 

QUICK NOTES

• Install Composer if you have not already done so, run composer require cboden/ratchet to install Ratchet.
• Change the port/URL in 1-server.php and 2-queue.js if not deploying at ws://localhost:8080.
• Run php 1-server.php in the command line.
• Access 3a-admin.html in the browser for the “admin page”, and 4a-board.html for the “queue board”.

If you spot a bug, feel free to comment below. I try to answer short questions too, but it is one person versus the entire world… If you need answers urgently, please check out my list of websites to get help with programming.

 

SCREENSHOT

 

EXAMPLE CODE DOWNLOAD

Click here to download all the example source code, I have released it under the MIT license, so feel free to build on top of it or use it in your own project.

 

 

 

PRELUDE) SETUP OVERVIEW

Before we start, here’s a quick overview of the system structure. There are 3 components:

• 1-server.php Queue management WebSocket server.
• 3a-admin.html This “admin page” issues queue numbers, and advances the queue to the next customer.
• 4a-board.html A “currently serving” display board.

Yes, this example can run on a single device or as many as you want.

• Single device, but requires 2 screens. One for the admin, another for the “now serving”.
• Multiple devices. One to act as the server, as many admin and display boards as you like.

 

PART 1) WEBSOCKET SERVER

1A) COMMAND LINE CHECK

<?php
// (A) COMMAND LINE CHECK
// CREDITS : https://stackoverflow.com/questions/933367/php-how-to-best-determine-if-the-current-invocation-is-from-cli-or-web-server
function is_cli () {
  if (php_sapi_name()==="cli") { return true; } 
  if (defined("STDIN")) { return true; }
  if (array_key_exists("SHELL", $_ENV)) { return true; }
  if (!array_key_exists("REQUEST_METHOD", $_SERVER)) { return true; }
  if (empty($_SERVER["REMOTE_ADDR"]) && !isset($_SERVER["HTTP_USER_AGENT"]) && count($_SERVER["argv"])>0) { return true; }
  return false;
}
if (!is_cli()) { exit("Please run this in the command line."); }

First, this script drives the mechanics behind the queue number system. Take note that it should be run in the command line… The first section makes sure it is so, with some “rather extensive checks”.

 

 

1B) LOAD RATCHET

// (B) LOAD RATCHET
require "vendor/autoload.php";
use Ratchet\MessageComponentInterface;
use Ratchet\ConnectionInterface;
use Ratchet\Server\IoServer;
use Ratchet\Http\HttpServer;
use Ratchet\WebSocket\WsServer;

For you guys who are new:

• Ratchet is a PHP library for WebSockets.
• WebSockets are basically persistent connections.

Long story short, it is very difficult to drive a live queue system using the “connect download disconnect” HTTP. Thus the use of WebSockets.

 

1C) QUEUE CLASS

// (C) QUEUE CLASS
class Queue implements MessageComponentInterface {
  // (C1) PROPERTIES
  private $debug = true; // debug mode
  protected $clients; // connected clients
  private $qt = 0; // total queue number
  private $qn = 0; // current queue number
 
  // (C2) CONSTRUCTOR - INIT LIST OF CLIENTS
  public function __construct () {
    $this->clients = new \SplObjectStorage;
    if ($this->debug) { echo "Queue server started.\r\n"; }
  }
 
  // (C3) ON CLIENT CONNECT - STORE INTO $THIS->CLIENTS
  public function onOpen (ConnectionInterface $conn) {
    $this->clients->attach($conn);
    if ($this->debug) { echo "Client connected: {$conn->resourceId}\r\n"; }
  }
 
  // (C4) ON CLIENT DISCONNECT - REMOVE FROM $THIS->CLIENTS
  public function onClose (ConnectionInterface $conn) {
    $this->clients->detach($conn);
    if ($this->debug) { echo "Client disconnected: {$conn->resourceId}\r\n"; }
  }
 
  // (C5) ON ERROR
  public function onError (ConnectionInterface $conn, \Exception $e) {
    $conn->close();
    if ($this->debug) { echo "Client error: {$conn->resourceId} | {$e->getMessage()}\r\n"; }
  }
 
  // (C6) ON RECEIVING MESSAGE FROM CLIENT
  public function onMessage (ConnectionInterface $from, $msg) {
    if ($this->debug) { echo "Received message from {$from->resourceId}: {$msg}\r\n"; }
    $msg = json_decode($msg, true);
    switch ($msg["r"]) {
      // (C6-1) INVALID REQUEST
      default: break;
 
      // (C6-2) ADMIN - UPDATE QUEUE NUMBER REQUEST
      case "getQ":
        $from->send(json_encode([
          "r" => "putQ",
          "qt" => $this->qt,
          "qn" => $this->qn
        ]));
        break;
 
      // (C6-3) ISSUE A QUEUE NUMBER
      case "issQ":
        $this->qt++;
        $this->putAllQ();
        break;
 
      // (C6-4) NEXT CUSTOMER
      case "nextQ":
        if ($this->qn < $this->qt) {
          $this->qn++;
          $this->putAllQ();
        }
        break;
    }
  }
 
  // (C7) PUSH QUEUE UPDATE TO ALL CLIENTS
  public function putAllQ () {
    // (C7-1) QUEUE MESSAGE
    $msg = json_encode([
      "r" => "putQ",
      "qt" => $this->qt,
      "qn" => $this->qn
    ]);
 
    // (C7-2) SEND TO ALL
    foreach ($this->clients as $client) { $client->send($msg); }
  }
}

Oh no. Big scary library.

• (C1 to C5) When a client connects, we store the connection in $this->clients; Remove it when the client disconnects.
• (C6 & C7) This is the “core” of the queue system.
  • (C1) $this->qt Total queue number. $this->qn Current queue number.
  • (C6-3) When the admin issues a queue number, $this->qt++. Push updated queue numbers to all clients.
  • (C6-4) When the admin hits “next customer”, $this->qn++. Push updated queue numbers to all clients.

That’s all.

 

 

1D) START WEBSOCKET SERVER

// (D) WEBSOCKET SERVER START!
$server = IoServer::factory(new HttpServer(new WsServer(new Queue())), 8080); // @CHANGE if not port 8080
$server->run();

Don’t think this needs explanation.

 

PART 2) JAVASCRIPT “WEBSOCKET LIBRARY”

var queue = {
  // (A) PROPERTIES
  host : "ws://localhost:8080", // @CHANGE to your own!
  socket : null, // websocket object
 
  // (B) CONNECT TO WS SERVER
  connect : opt => {
    // (B1) CREATE WEB SOCKET
    queue.socket = new WebSocket(queue.host);
 
    // (B2) READY - CONNECTED TO SERVER
    if (opt.open) { queue.socket.onopen = opt.open; }
 
    // (B3) ON CONNECTION CLOSE
    if (opt.close) { queue.socket.onclose = opt.close; }
 
    // (B4) ON RECEIVING DATA FROM SEREVER
    if (opt.msg) { queue.socket.onmessage = opt.msg; }
 
    // (B5) ON ERROR
    if (opt.error) { queue.socket.onerror = opt.error; }
  },
 
  // (C) SEND MESSAGE
  send : (req, data) => {
    if (data === undefined) { data = null; }
    queue.socket.send(JSON.stringify({ r: req, d: data }));
  }
};

Next, we have a “Javascript library” to work with the PHP WebSocket server. This is more for convenience so that we won’t have duplicated code later on.

 

PART 3) ADMIN PAGE

3A) ADMIN HTML

<!-- (A) SERVER STATUS -->
<div id="server" class="red">Disconnected</div>
 
<!-- (B) CURRENT & TOTAL QUEUE NUMBER -->
<div id="qTotal">
  <div class="qTxt">TOTAL</div>
  <div class="qNum">0</div>
</div>
<div id="qNow">
  <div class="qTxt">NOW</div>
  <div class="qNum">0</div>
</div>
 
<!-- (C) INSTRUCTIONS -->
<div id="instruct">
  Tap on "total" to issue a queue number.<br>
  Tap on "now" to move to the next queue number.
</div>

This should be pretty straightforward, there are only 3 sections on this page.

• <div id="server> The current server status. Is connected or disconnected from the WebSocket server.
• <div id="qTotal"> <div id="qNow"> Total in the queue, and the “now serving” queue number.
• <div id="instruct"> Short instructions.

 

 

3B) ADMIN JAVASCRIPT

var adm = {
  // (A) PROPERTIES
  connected : false, // connected to websocket
  ready : false, // app ready
  hQT : null, // html queue total
  hQN : null, // html queue now
  hSS : null, // html server status

  // (B) ADMIN INIT
  init : () => {
    // (B1) GET HTML ELEMENTS
    adm.hQT = document.querySelector("#qTotal .qNum");
    adm.hQN = document.querySelector("#qNow .qNum");
    adm.hSS = document.getElementById("server");

    // (B2) ATTACH CONTROLS
    document.getElementById("qTotal").onclick = adm.issQ;
    document.getElementById("qNow").onclick = adm.nextQ;

    // (B3) CONNECT TO WEBSOCKET
    queue.connect({
      // (B3-1) ON OPEN/CLOSE/ERROR
      open : e => adm.toggle(true),
      close : e => adm.toggle(false),
      error : e => adm.toggle(false),
 
      // (B3-2) INIT QUEUE NUMBER
      msg : e => {
        try {
          let res = JSON.parse(e.data);
          if (res.r=="putQ") { adm.putQ(res.qt, res.qn); }
        } catch (e) {
          alert("Init error");
          console.error(e);
        }
      }
    });
  },

  // (C) TOGGLE CONNECTION STATUS
  toggle : good => {
    if (good) {
      adm.connected = true;
      adm.sc.className = "green";
      adm.st.innerHTML = "Connected";
      adm.getQ();
    } else {
      adm.connected = false;
      adm.ready = false;
      adm.sc.className = "red";
      adm.st.innerHTML = "Disconnected";
    }
  },

  // (D) REQUEST QUEUE NUMBERS UPDATE FROM SERVER
  getQ : () => { if (adm.connected) {
    queue.send("getQ");
  }},

  // (E) UPDATE HTML QUEUE NUMBERS
  putQ : (qt, qn) => { if (adm.connected) {
    adm.qtn.innerHTML = qt;
    adm.qnn.innerHTML = qn;
    adm.ready = true;
  }},

  // (F) ISSUE QUEUE NUMBER
  issQ : () => { if (adm.ready) {
    queue.send("issQ");
  }},

  // (G) NEXT!
  nextQ : () => { if (adm.ready) {
    queue.send("nextQ");
  }}
};
window.onload = adm.init;

Yikes. Big scary script once again, but a quick summary:

• (B) init() Runs on page load. Gets all the HTML elements, connect to the WebSocket server, and updates the queue counter.
• (C) toggle() A “helper function” to update HTML “connected to server status”.
• (D) getQ() Get the current queue number from the server.
• (E) putQ() Send the current queue number to the server.
• (F) issQ() Issue a queue number (increment total in the queue by 1).
• (G) nextQ() Next customer (increment now serving by 1).

 

PART 4) NOW SERVING DISPLAY BOARD

4A) DISPLAY BOARD HTML

<!-- (A) CLICK TO START -->
<div id="start" onclick="board.start()">START</div>
 
<!-- (B) DISPLAY BOARD -->
<div id="board">
  <!-- (B1) SERVER STATUS -->
  <div id="server" class="red">Disconnected</div>
 
  <!-- (B2) CURRENT QUEUE NUMBER -->
  <div id="qTxt">NOW SERVING</div>
  <div id="qNum">0</div>
</div>

Pretty much a simplified admin panel.

• <div id="start"> Click on this button to start… It is necessary for the user to click at least once, so we can play the alarm sound on queue advance.
• <div id="server"> Same old “connected to server” status.
• <div id="qNum"> Now serving queue number.

 

 

4B) DISPLAY BOARD JAVASCRIPT

var board = {
  // (A) PROPERTIES
  connected : false, // connected to websocket
  aDD : null, // ding dong audio
  hQN : null, // html queue now
  hSS : null, // html server status

  // (B) ADMIN INIT
  init : () => {
    // (B1) PRELOAD AUDIO
    board.aDD = new Audio("ding-dong.mp3");

    // (B2) GET + TOGGLE HTML ELEMENTS
    board.hSS = document.getElementById("server");
    board.hQN = document.getElementById("qNum");
    document.getElementById("start").style.display = "none";
    document.getElementById("board").style.display = "block";

    // (B3) CONNECT TO WEBSOCKET
    queue.connect({
      // (B3-1) ON OPEN/CLOSE/ERROR
      open : e => board.toggle(true),
      close : e => board.toggle(false),
      error : e => board.toggle(false),
 
      // (B3-2) INIT QUEUE NUMBER
      msg : e => {
        try {
          let res = JSON.parse(e.data);
          if (res.r=="putQ") { board.putQ(res.qn); }
        } catch (e) {
          alert("Init error");
          console.error(e);
        }
      }
    });
  },

  // (C) TOGGLE CONNECTION STATUS
  toggle : good => {
    if (good) {
      board.connected = true;
      board.sc.className = "green";
      board.st.innerHTML = "Connected";
      board.getQ();
    } else {
      board.connected = false;
      board.sc.className = "red";
      board.st.innerHTML = "Disconnected";
    }
  },

  // (D) REQUEST QUEUE NUMBERS UPDATE FROM SERVER
  getQ : () => { if (board.connected) {
    queue.send("getQ");
  }},

  // (E) UPDATE HTML QUEUE NUMBERS
  putQ : qn => { if (board.connected && board.hQN.innerHTML!=qn) {
    board.hQN.innerHTML = qn;
    board.aDD.currentTime = 0;
    board.aDD.play();
  }}
};

window.onload = board.init;

Look no further, this is actually a simplified version of the admin; This only displays the current queue number, nothing else.

 

 

A COUPLE OF IMPROVEMENTS

Yes, this is only a working example and foundation. There are many things you can add and customize to make it better.

• Define your own “reset queue number” algorithm… If not, it will run to very large numbers in due time.
• Probably makes sense to save the current queue number into a database or file. The queue number will not be lost when the server crashes.
• Also possible to tie in an existing user database – Send notifications when the customer’s turn nears.
• Not much of an issue if this example is within an intranet. But various security checks need to be in place if you want to put this online.

 

COMPATIBILITY CHECKS

• Arrow Functions – CanIUse
• Web Socket – CanIUse

A modern “Grade A” browser is required for this example to work correctly.

 

LINKS & REFERENCES

• Ratchet
• WebSocket – MDN