PHP Push Notifications (Step-By-Step Example)

Welcome to a tutorial on how to send push notifications in PHP. It is not a secret that web browsers are capable of displaying notifications, but just how can we send push notifications from a PHP server? Read on for the example!

ⓘ 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

Download & Notes PHP Push Useful Bits & Links
The End

 

DOWNLOAD & NOTES

Firstly, here is the download link to the example code as promised.

 

QUICK NOTES

  • Download and unzip into your HTTP folder.
  • A copy of the Web Push library is not included in the zip file. Download your own – composer require minishlink/web-push.
  • Make sure that the PHP OpenSSL extension is enabled.
  • Run 2-vapid-keys.php to generate your own public/private keys.
  • Change the public key in 3-perm-sw.html to your own.
  • Change the subject, public, and private keys to your own in 5-push-server.php.
  • Access 3-perm-sw.html in your browser. Captain Obvious to the rescue, https:// is required for push notifications to work. But http://localhost works fine too, for local testing.
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.

 

 

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.

 

 

PHP PUSH NOTIFICATIONS

All right, let us now get into the example of how to send push notifications in PHP.

 

STEP 1) SERVER SETUP

1A) PHP WEB PUSH LIBRARY

Before we start with the code, let us deal with foundations. First, we need to download the PHP Web Push library.

  • Install Composer package manager if you have not already done so.
  • Open the command line or terminal.
  • Navigate to your HTTP folder. For example, cd d:/http.
  • Run composer require minishlink/web-push.

That’s all. The Web Push library will be downloaded into the vendor/ folder.

 

1B) PHP OPENSSL

Next, enable the OpenSSL extension in PHP. The installation is different depending on your OS and build.

  • Linux
    • It is as simple as sudo apt-get install openssl, or yum install openssl for the CentOS users.
    • Then, php -i | grep -i openssl.
  • Windows – I am using XAMPP and OpenSSL is already included. But a hiccup got me stumped for a while.
    • Start > Search for “system environment” > “Edit the system environment variables” > “Environment variables”.
    • Add a new system variable called OPENSSL_CONF and point it to the openssl.cnf file.
    • By default, it is located at C:\xampp\php\extras\openssl\openssl.cnf.

For all other platforms and troubleshooting, please do your own research. It’s just too much to cover in this mini section.

 

 

STEP 2) GENERATE VAPID KEYS

2-vapid-keys.php
<?php
require "vendor/autoload.php";
use Minishlink\WebPush\VAPID;
print_r(VAPID::createVapidKeys());
D:\http>php 2-vapid-keys.php
Array
(
  [publicKey] => GENERATE-YOUR-OWN
  [privateKey] => GENERATE-YOUR-OWN
)

VAPID stands for Voluntary Application Server Identification. Simply put, generating a pair of public and private keys to prevent your push notifications from getting hijacked.  This script only needs to run once, but you can always run this again to generate a new pair of keys.

P.S. If OpenSSL is not properly installed, createVapidKeys() will return a false.

P.P.S. The private key should only be used on the server side. Do not expose it publicly.

 

STEP 3) CLIENT PAGE

3A) GET PERMISSION TO SHOW NOTIFICATIONS

3-perm-sw.html
// (A) OBTAIN USER PERMISSION
// (A1) ASK FOR PERMISSION
if (Notification.permission === "default") {
  Notification.requestPermission().then((perm) => {
    if (Notification.permission === "granted") {
      regWorker().catch((err) => { console.error(err); } );
    }
    else { alert("Please allow notifications."); }
  });
} 
 
// (A2) GRANTED
else if (Notification.permission === "granted") {
  regWorker().catch((err) => { console.error(err); } );
}

// (A3) DENIED
else { alert("Please allow notifications."); }

Now that we have generated the keys, let’s put them aside for a minute. The first thing we need on the HTML page is to get the user’s permission to display notifications. Yes, we cannot proceed if notifications are blocked.

 

 

3B) REGISTER SERVICE WORKER

3-perm-sw.html
// (B) REGISTER SERVICE WORKER
async function regWorker () {
  // (B1) YOUR PUBLIC KEY - CHANGE TO YOUR OWN!
  const publicKey = "YOUR-PUBLIC-KEY";
 
  // (B2) REGISTER SERVICE WORKER
  const reg = await navigator.serviceWorker.register("4-sw.js", { scope: "/" });
 
  // (B3) SUBSCRIBE TO PUSH SERVER
  const sub = await reg.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: publicKey
  });
 
  // (B4) TEST PUSH NOTIFICATION
  var data = new FormData();
  data.append("sub", JSON.stringify(sub));
  fetch("5-push-server.php", {
    method: "POST",
    body : data
  })
  .then(res => res.text())
  .then(txt => { console.log(txt); });
}

Once we have the user’s permission to display notifications, the next step is to register a service worker. For those who have never heard of it, a service worker is simply Javascript that runs in the background. Even when the user is not on the website itself. A couple of important points here:

  • (B1) A gentle reminder to change the public key to your own.
  • (B2) Register 4-sw.js as a service worker.
  • (B3 & B4) Take extra note of these.
    • (B3) sub = await reg.pushManager.subscribe() Pass in the public key and subscribe the service worker to the push server.
    • (B4) Immediately send sub to the server, and request for a test push notification.

 

STEP 4) SERVICE WORKER

4-sw.js
// (A) INSTANT WORKER ACTIVATION
self.addEventListener("install", (evt) => {
  self.skipWaiting();
});
 
// (B) LISTEN TO PUSH
self.addEventListener("push", (evt) => {
  const data = evt.data.json();
  console.log("Push", data);
  self.registration.showNotification(data.title, {
    body: data.body,
    icon: data.icon,
    image: data.image
  });
});

Well, this should be pretty self-explanatory. This service worker displays push notifications received from the server.

 

 

STEP 5) PHP PUSH SERVER

5-push-server.php
// (A) LOAD WEB PUSH LIBRARY
require "vendor/autoload.php";
use Minishlink\WebPush\Subscription;
use Minishlink\WebPush\WebPush;

// (B) GET SUBSCRIPTION
$sub = Subscription::create(json_decode($_POST["sub"], true));

// (C) NEW WEB PUSH OBJECT - CHANGE TO YOUR OWN!
$push = new WebPush(["VAPID" => [
  "subject" => "your@email.com",
  "publicKey" => "YOUR-PUBLIC-KEY",
  "privateKey" => "YOUR-PRIVATE-KEY"
]]);

// (D) SEND TEST PUSH NOTIFICATION
$result = $push->sendOneNotification($sub, json_encode([
  "title" => "Welcome!",
  "body" => "Yes, it works!",
  "icon" => "i-loud.png",
  "image" => "i-zap.png"
]));
$endpoint = $result->getRequest()->getUri()->__toString();

// (E) SHOW RESULT - OPTIONAL
if ($result->isSuccess()) {
  echo "Successfully sent {$endpoint}.";
} else {
  echo "Send failed {$endpoint}: {$result->getReason()}";
}

Following up on the fetch call in step 3B, this PHP script will handle the push notification.

  • (A) Load the Web Push library. Captain Obvious saves the day once again.
  • (B) Remember that the Javascript will send over a “subscribed service worker”? That’s that.
  • (C to E) We simply send a test push notification to the “subscribed service worker”.

The end. Congratulations, you have just sent out your first push message.

 

 

USEFUL BITS & LINKS

That’s all for the tutorial, and here is a small section on some extras and links that may be useful to you.

 

NOT HOW IT USUALLY WORKS…

Of course, this simplified example is not how a production server works.

  • In 3-per-sw.html (B3), we should send the “subscribed service worker” to the server and save it into a database first.
  • At a later date, we manually call 5-push-server.php. This script will retrieve all subscribers from the database, and mass send out the push notifications.

 

I DENIED PERMISSION TO SHOW NOTIFICATIONS

Once denied, the browser will never prompt for permission again. The only way is to click on the icon next to the URL bar, and manually enable the notications.

 

COMPATIBILITY CHECKS

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

 

LINKS & REFERENCES

 

THE END

Thank you for reading, and we have come to the end. I hope that it has helped you to better understand, and if you want to share anything with this guide, please feel free to comment below. Good luck and happy coding!

Leave a Comment

Your email address will not be published.