PHPackages                             philippoehrlein/kirby-push-notifications - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail &amp; Notifications](/categories/mail)
4. /
5. philippoehrlein/kirby-push-notifications

ActiveKirby-plugin[Mail &amp; Notifications](/categories/mail)

philippoehrlein/kirby-push-notifications
========================================

Web Push for Kirby: channel-based subscriptions, Panel UI, frontend dialog, hooks and API

1.1.0(5d ago)115MITPHP

Since Mar 15Pushed 4d agoCompare

[ Source](https://github.com/philippoehrlein/Kirby-Push-Notifications)[ Packagist](https://packagist.org/packages/philippoehrlein/kirby-push-notifications)[ RSS](/packages/philippoehrlein-kirby-push-notifications/feed)WikiDiscussions main Synced today

READMEChangelog (5)Dependencies (2)Versions (5)Used By (0)

Kirby Push Notifications
========================

[](#kirby-push-notifications)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)[![Version](https://camo.githubusercontent.com/dd58329e6a923a53561c83ac932237b7ea0b6cc313a12cc4c07d38bef38b6e61/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e312e302d626c7565)](https://camo.githubusercontent.com/dd58329e6a923a53561c83ac932237b7ea0b6cc313a12cc4c07d38bef38b6e61/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e312e302d626c7565)

**Kirby Push Notifications** is a plugin for [Kirby CMS](https://getkirby.com/) that adds Web Push support. Visitors can subscribe to channels (e.g. “Notes”, “News”), and you can send notifications from the Panel or via hooks. Subscriptions are stored in SQLite; sending is powered by the [minishlink/web-push](https://github.com/web-push-libs/web-push-php) library with VAPID authentication.

[![Cover Kirby Push Notifications](.github/kirby-push-notifications-cover.png)](.github/kirby-push-notifications-cover.png)

Features
--------

[](#features)

- 🔔 Visitors subscribe to channels
- 👨‍💻 Editors send notifications from the Panel
- 🚀 Developers automate via hooks

Requirements
------------

[](#requirements)

- Kirby 5.x
- PHP 8.2+
- HTTPS (required for Web Push)

Installation
------------

[](#installation)

### Composer (recommended)

[](#composer-recommended)

In your site root:

```
composer require philippoehrlein/kirby-push-notifications
```

### Manual installation

[](#manual-installation)

1. Download or clone the repo.
2. Copy the `kirby-push-notifications` folder into `site/plugins/`.

The plugin ships with its own `vendor/`, so no `composer install` in the plugin folder is needed.

Configuration
-------------

[](#configuration)

In `site/config/config.php` (or a separate config file):

```
return [
    'philippoehrlein.push-notifications' => [
        'vapid' => [
            'publicKey'  => 'your-vapid-public-key',
            'privateKey' => 'your-vapid-private-key',
            'subject'    => 'https://yourdomain.com',
        ],
        'channels' => [
            'panel' => [
                [
                    'value' => 'note-approval',
                    'text' => 'Note Approval',
                    'info' => 'Get informed when a note is waiting for approval',
                ]
            ],
            'website' => [
                [
                    'value' => 'notes',
                    'text'  => 'Notes',
                    'info'  => 'Receive new notes',
                ],
                [
                    'value' => 'photos',
                    'text'  => 'Photography',
                    'info'  => 'Receive the latest Photo series',
                ],
            ]
        ],
        // optional: change DB location
        // 'db' => [
        //     'name' => 'push_notifications',
        //     'dir'  => 'site/push-notifications',
        // ],
        // optional: Web Push default options (TTL, contentType, batchSize, etc.)
        // 'webPush' => [
        //     'contentType' => 'application/json',
        //     'TTL' => 3600,
        //     'urgency' => null,
        //     'topic' => null,
        //     'batchSize' => 1000,
        //     'requestConcurrency' => 100,
        // ],
    ],
];
```

> Note Defining channels in the plugin options is optional. It is only required if you want to use the built‑in subscription UIs that read channels from the config (like kpn-dialog). If you use the helper script (helper.js), panel buttons or your own custom UI, you can pass channel names directly in your code without configuring them in channels.

#### Alternative: flat channels (no panel/website groups)

[](#alternative-flat-channels-no-panelwebsite-groups)

By default, you can configure channels in two groups (`panel` and `website`) so the Panel groups them visually. Channels in the website group are exposed to the frontend snippet, while panel channels are only available inside the Panel. If you don’t need this distinction, you can also use a flat list of channels.

```
// site/config/config.php
return [
  'philippoehrlein.push-notifications' => [
    'channels' => [
      [
        'value' => 'news',
        'text'  => 'News',
        'info'  => 'General website updates',
      ],
      [
        'value' => 'notes',
        'text'  => 'Notes',
        'info'  => 'New notes and articles',
      ],
    ],
  ],
];
```

### VAPID keys

[](#vapid-keys)

Web Push requires a VAPID key pair. Set `vapid.publicKey`, `vapid.privateKey` and `vapid.subject` (your site URL, e.g. `https://yourdomain.com`). Keep the private key secret.

**Generating keys:** Use the [Create VAPID keys](https://github.com/web-push-libs/web-push-php?tab=readme-ov-file#create-vapid-keys) section in the web-push-php README (OpenSSL in bash or `VAPID::createVapidKeys()` in PHP).

### Option webPush

[](#option-webpush)

Optional: Set global defaults for all push sends with the `webPush` option. Keys: `contentType` (e.g. `application/json`), `TTL` (seconds, e.g. 3600), `urgency`, `topic`, `batchSize`, `requestConcurrency`. Usually `urgency` and `topic` are left `null` here and set per send via the hook payload (see [Payload for send hooks](#payload-for-send-hooks)). You can still set global defaults if needed.

Usage
-----

[](#usage)

There are two main use cases: **website** (visitors subscribe) and **panel** (editors manage or send notifications). Each can be used in a simple way (ready-made UI) or a custom way (your own UI with the same APIs).

---

### Website

[](#website)

#### Simple: Dialog snippet

[](#simple-dialog-snippet)

[![Dialog for subscriptions](.github/kirby-push-notifications-subscribe-frontend.png)](.github/kirby-push-notifications-subscribe-frontend.png)

Use the `kpn-dialog` snippet for a button that opens a subscribe/unsubscribe dialog with channel checkboxes. No custom JS needed.

In a template or snippet:

```

🔔 Notifications

```

Optional: pass data to override defaults or translations:

```

🔔 Notifications

```

#### Custom: helper.js

[](#custom-helperjs)

If you don’t want the dialog (e.g. a single button with fixed channels, or your own UI), use the helper script. Set `window.KPN_CONFIG` (vapidPublicKey, subscribeUrl, unsubscribeUrl, swPath), load `/assets/kpn/helper.js`, then call `window.KPN.subscribe(channels)` and `window.KPN.unsubscribe()`. You stay in control of markup and flow; the helper only handles the Web Push API and the plugin routes.

---

### Panel

[](#panel)

#### Simple: View buttons, button components, dialog

[](#simple-view-buttons-button-components-dialog)

[![Panel dialog for subscriptions](.github/kirby-push-notifications-subscribe-panel.png)](.github/kirby-push-notifications-subscribe-panel.png)

The plugin ships with two **view buttons** (`kpn-subscribe`, `kpn-notification`), two **button components** (`kpn-subscribe-button`, `kpn-notification-button`) and one **dialog** (`kpn-subscribe-dialog`). Register and place them in your Panel blueprints or views where needed. That’s enough to let logged-in users subscribe/unsubscribe and to send a notification (channel, title, body) without building your own UI. See `src/index.js` and `src/components/` for how they’re wired.

[![Panel dialog for sending notifications](.github/kirby-push-notifications-send.png)](.github/kirby-push-notifications-send.png)

#### Custom: Your own UI with hooks and API

[](#custom-your-own-ui-with-hooks-and-api)

Build your own Panel UI and call the **hooks** (subscribe, unsubscribe, send-to-one, send-to-many) and the **Panel API** (e.g. get-channels, get-keys, status, subscribe, unsubscribe). Same backend, full control over the interface.

Example: send a push when a note is published:

```
// site/config/config.php
'hooks' => [
    'page.changeStatus:after' => function ($newPage, $oldPage) {
        if ($newPage->intendedTemplate() === 'note' && $newPage->status() === 'listed') {
            kirby()->trigger('philippoehrlein.push-notifications.send-to-many', [
                'payload' => [
                    'message' => [
                        'title' => kirby()->site()->title()->value(),
                        'body'  => 'New note: ' . $newPage->title()->value(),
                        'data'  => ['url' => $newPage->url()],
                    ],
                    'channel' => 'notes',
                    'options' => ['urgency' => 'normal'],
                ],
            ]);
        }
    },
],
```

---

Hooks
-----

[](#hooks)

HookUse case`philippoehrlein.push-notifications.subscribe`After a subscription is created (payload: endpoint, keys, channel, user\_id).`philippoehrlein.push-notifications.unsubscribe`After unsubscription (payload: endpoint and/or user\_id, channel).`philippoehrlein.push-notifications.send-to-one`Send to one user (payload: user\_id, message, channel, language?, options?).`philippoehrlein.push-notifications.send-to-many`Send to many users or to a full channel (payload: message, user\_ids?, channel?, language?, options?).### Payload for send hooks

[](#payload-for-send-hooks)

For **send-to-one** and **send-to-many**, the payload can include an optional **`options`** array with Web Push options for that send:

- **`urgency`**: Delivery priority – `'very-low'`, `'low'`, `'normal'`, `'high'`. Affects delivery timing and presentation (e.g. sound, vibration).
- **`topic`**: Optional. When set, push services may replace older notifications with the same topic by newer ones (collapse). Whether and when to use e.g. the channel as topic is up to you (e.g. `'topic' => $channel` for one notification per channel).
- **`TTL`**: Optional, time-to-live in seconds for this message.

Example: `'options' => ['urgency' => 'high', 'TTL' => 600]`.

Routes and API
--------------

[](#routes-and-api)

- **Frontend (public):**
    - `POST /push-notifications/subscribe` — Body: `endpoint`, `keys`, `channel`. Param: `lang` (optional).
    - `POST /push-notifications/unsubscribe`
    - `GET /push-notifications-sw.js` (service worker)
    - `GET /assets/kpn/helper.js`
- **Panel API:** `philippoehrlein/push-notifications/*` (subscribe, unsubscribe, get-channels, get-keys, status, etc.).

License
-------

[](#license)

MIT. See [LICENSE](LICENSE) for details.

Support
-------

[](#support)

- Issues: [GitHub Issues](https://github.com/philippoehrlein/kirby-push-notifications/issues)
- Contact:

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance99

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 61.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

5d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/818779cb1d5575b715d8bdde9943d8795aa723a04a0a412a579d5571e74d5b96?d=identicon)[philippoehrlein](/maintainers/philippoehrlein)

---

Top Contributors

[![philipp15h](https://avatars.githubusercontent.com/u/199604090?v=4)](https://github.com/philipp15h "philipp15h (11 commits)")[![philippoehrlein](https://avatars.githubusercontent.com/u/101180105?v=4)](https://github.com/philippoehrlein "philippoehrlein (7 commits)")

---

Tags

kirbykirby-cmskirby-pluginkirby5push-notificationsweb-push

### Embed Badge

![Health badge](/badges/philippoehrlein-kirby-push-notifications/health.svg)

```
[![Health](https://phpackages.com/badges/philippoehrlein-kirby-push-notifications/health.svg)](https://phpackages.com/packages/philippoehrlein-kirby-push-notifications)
```

###  Alternatives

[pelago/emogrifier

Converts CSS styles into inline style attributes in your HTML code

94843.3M89](/packages/pelago-emogrifier)[laravel-notification-channels/webpush

Web Push Notifications driver for Laravel.

7934.2M15](/packages/laravel-notification-channels-webpush)[bentools/webpush-bundle

Send push notifications through Web Push Protocol to your Symfony users.

71268.7k](/packages/bentools-webpush-bundle)[minishlink/web-push-bundle

Symfony Bundle around the WebPush library

56307.8k2](/packages/minishlink-web-push-bundle)[minishlink/web-push-php-example

An example for sending Web Push notifications, using web-push-php

27513.0k](/packages/minishlink-web-push-php-example)[webzop/yii2-notifications

Notifications module for Yii2

71106.0k](/packages/webzop-yii2-notifications)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
