PHPackages                             iguazoft/yii2-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. iguazoft/yii2-push-notifications

ActiveYii2-extension

iguazoft/yii2-push-notifications
================================

Web Push Notifications for Yii2 — VAPID-based push with Service Worker support

v1.0.0(1w ago)00MITPHPPHP &gt;=8.0

Since Mar 10Pushed 1w agoCompare

[ Source](https://github.com/dannyrios81/yii2-push-notifications)[ Packagist](https://packagist.org/packages/iguazoft/yii2-push-notifications)[ RSS](/packages/iguazoft-yii2-push-notifications/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

yii2-push-notifications
=======================

[](#yii2-push-notifications)

> Web Push Notifications for Yii2 — send real-time alerts to your users even when they have the browser closed.

Built on the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) with VAPID authentication and Service Workers. No external paid service required — pushes go directly from your server to the browser.

---

Table of Contents
-----------------

[](#table-of-contents)

- [What it does](#what-it-does)
- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [1. Add the subscribe button](#1-add-the-subscribe-button)
    - [2. Send a notification from PHP](#2-send-a-notification-from-php)
    - [3. Console commands](#3-console-commands)
- [Widget reference](#widget-reference)
- [PushManager reference](#pushmanager-reference)
- [HTTP API endpoints](#http-api-endpoints)
- [Browser compatibility](#browser-compatibility)
- [Troubleshooting](#troubleshooting)

---

What it does
------------

[](#what-it-does)

This extension lets you send push notifications to your Yii2 application users **directly from your PHP server**, with no third-party service needed. Notifications appear as native OS alerts with a system sound, even when:

- The browser tab is minimized or in the background
- The browser is open but on a different tab
- The browser is completely closed (the OS must be running)

Typical use cases:

Use caseExampleNew private message*"Juan sent you a message"*Order status update*"Your order #1042 has been shipped"*System alert*"Server CPU usage above 90%"*Scheduled announcement*"Maintenance window starting in 10 minutes"*New comment or mention*"Maria replied to your post"*---

How it works
------------

[](#how-it-works)

```
YOUR SERVER                    BROWSER VENDOR              USER'S BROWSER
     │                               │                            │
     │   1. User clicks "Enable"     │                            │
     │ ◄─────────────────────────────────────────────────────────┤
     │                               │                            │
     │   2. Save subscription        │                            │
     │   (endpoint + keys)           │                            │
     │ ◄─────────────────────────────────────────────────────────┤
     │                               │                            │
     │   3. Yii::$app->push->send()  │                            │
     ├──────────────────────────────►│                            │
     │                               │   4. Forward to browser    │
     │                               ├───────────────────────────►│
     │                               │                            │
     │                               │      5. Service Worker     │
     │                               │         wakes up →         │
     │                               │      showNotification()    │
     │                               │      🔔 + system sound     │

```

The extension handles all the complexity:

- **VAPID authentication** to prove your server's identity
- **Service Worker** that intercepts push events in the background
- **Subscription management** stored in your database
- **Auto-cleanup** of expired subscriptions

---

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

[](#requirements)

RequirementVersionPHP&gt;= 8.0Yii2~2.0PHP extension`gmp` **or** `bcmath`Protocol**HTTPS required** (or `localhost` for development)> **Why HTTPS?** Browsers only allow Service Workers and the Push API on secure origins. For local development, `http://localhost` is treated as secure.

---

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

[](#installation)

### Step 1 — Install via Composer

[](#step-1--install-via-composer)

```
composer require iguazoft/yii2-push-notifications
```

### Step 2 — Generate VAPID keys

[](#step-2--generate-vapid-keys)

VAPID keys are a cryptographic pair that proves to browser vendors that push messages actually come from your server. You generate them once and store them in your config.

```
php yii push/generate-keys
```

Output:

```
✅ VAPID keys generated successfully.

Copy these values into config/web.php:

'vapidPublicKey'  => 'BNa7...long base64 string...Xk=',
'vapidPrivateKey' => 'abc...long base64 string...Z4=',

```

> **Important:** Keep `vapidPrivateKey` secret. Never commit it to version control — use environment variables or a local config file excluded from git.

### Step 3 — Add the component to `config/web.php`

[](#step-3--add-the-component-to-configwebphp)

```
'components' => [
    'push' => [
        'class'          => \iguazoft\push\components\PushManager::class,
        'vapidPublicKey'  => 'YOUR_PUBLIC_KEY_HERE',
        'vapidPrivateKey' => 'YOUR_PRIVATE_KEY_HERE',
        'vapidSubject'    => 'mailto:admin@yoursite.com',
    ],
],
```

> `vapidSubject` must be either a `mailto:` address or a URL. Browser vendors use it to contact you if there is an issue with your push traffic.

### Step 4 — Run the migration

[](#step-4--run-the-migration)

Creates the `push_subscriptions` table in your database.

```
php yii migrate --migrationPath=@vendor/iguazoft/yii2-push-notifications/src/migrations
```

That's it. The extension auto-registers its URL routes and console commands.

---

Usage
-----

[](#usage)

### 1. Add the subscribe button

[](#1-add-the-subscribe-button)

Place the `PushSubscribe` widget anywhere in your layout or view. It renders a button that handles everything: registering the Service Worker, requesting browser permission, and saving the subscription to your server.

**Basic usage:**

```
echo \iguazoft\push\widgets\PushSubscribe::widget();
```

**With custom labels:**

```
echo \iguazoft\push\widgets\PushSubscribe::widget([
    'buttonLabel'     => '🔔 Enable notifications',
    'subscribedLabel' => '🔕 Disable notifications',
    'loadingLabel'    => 'Please wait...',
]);
```

**With custom CSS classes (e.g. Bootstrap or DaisyUI):**

```
echo \iguazoft\push\widgets\PushSubscribe::widget([
    'buttonLabel'   => 'Enable notifications',
    'buttonOptions' => ['class' => 'btn btn-outline-primary btn-sm'],
]);
```

**What the button does step by step:**

1. User clicks the button
2. The browser shows its native "Allow notifications?" prompt
3. If allowed, the browser creates a unique subscription object (endpoint URL + encryption keys)
4. The widget POSTs this to `/push/subscribe` and saves it to your database
5. The button text changes to the `subscribedLabel` value
6. If the user clicks again, the subscription is cancelled and removed

The widget automatically remembers the subscription state on page reload.

---

### 2. Send a notification from PHP

[](#2-send-a-notification-from-php)

Use `Yii::$app->push` anywhere in your application: controllers, models, queue jobs, console commands, event handlers.

**Send to a specific user:**

```
Yii::$app->push->send('New message', 'You have 1 unread message', $userId);
```

**Send to all subscribers:**

```
Yii::$app->push->sendToAll('Announcement', 'Scheduled maintenance at 22:00');
```

**With extra options:**

```
Yii::$app->push->send(
    'Order shipped',
    'Your order #1042 is on its way',
    $userId,
    [
        'icon'  => '/img/logo-192.png',   // notification icon (PNG, min 192×192px)
        'badge' => '/img/badge-72.png',   // small monochrome icon (Android, 72×72px)
        'url'   => '/orders/1042',        // page to open when user clicks
        'tag'   => 'order-1042',          // replaces previous notification with same tag
        'image' => '/img/product.png',    // large image inside the notification
    ]
);
```

**Handling the result:**

```
$result = Yii::$app->push->sendToAll('Flash sale', '50% off everything — today only!');

echo "Sent:   {$result['sent']}\n";
echo "Failed: {$result['failed']}\n";

if (!empty($result['errors'])) {
    foreach ($result['errors'] as $error) {
        Yii::error("Push error: $error", 'push');
    }
}
```

The return value is always an array with three keys:

KeyTypeDescription`sent``int`Number of notifications successfully delivered`failed``int`Number of failed deliveries`errors``string[]`Error messages for failed deliveries> **Tip:** Expired or unregistered subscriptions are automatically deleted from the database when a delivery fails with a 410 Gone response.

**Real-world example — notify on new order in a controller:**

```
public function actionCreate()
{
    $order = new Order();

    if ($order->load(Yii::$app->request->post()) && $order->save()) {

        // Notify the customer
        Yii::$app->push->send(
            'Order received',
            "Order #{$order->id} has been placed successfully.",
            $order->user_id,
            ['url' => "/orders/{$order->id}"]
        );

        // Notify all admins
        foreach (User::find()->where(['role' => 'admin'])->all() as $admin) {
            Yii::$app->push->send(
                'New order',
                "Order #{$order->id} from {$order->user->name}",
                $admin->id,
                ['url' => "/admin/orders/{$order->id}"]
            );
        }

        return $this->redirect(['view', 'id' => $order->id]);
    }

    return $this->render('create', ['model' => $order]);
}
```

---

### 3. Console commands

[](#3-console-commands)

The extension registers a `push` command group automatically in console applications.

**Show subscription statistics:**

```
php yii push/stats
```

```
📊 Active push subscriptions
─────────────────────────────
Total:        1,204
Users:          891
Anonymous:      313

```

**Send to all subscribers:**

```
php yii push/send-all "Title" "Message body"

# With a click URL
php yii push/send-all "Maintenance" "System restart in 5 minutes" "/status"
```

**Send to a specific user by ID:**

```
php yii push/send 42 "Title" "Message body"
php yii push/send 42 "Account alert" "Unusual login detected" "/security"
```

**Generate new VAPID keys:**

```
php yii push/generate-keys
```

**Automate with cron:**

```
# Send a daily digest every day at 8:00 AM
0 8 * * * /usr/bin/php /var/www/myapp/yii push/send-all "Daily digest" "Your summary is ready" "/digest"
```

---

Widget reference
----------------

[](#widget-reference)

Full list of properties for `\iguazoft\push\widgets\PushSubscribe`:

PropertyTypeDefaultDescription`buttonLabel``string``'Activar notificaciones'`Button text when not subscribed`subscribedLabel``string``'Desactivar notificaciones'`Button text when subscribed`loadingLabel``string``'Procesando...'`Button text during processing`buttonOptions``array``[]`HTML attributes for the `` element`containerOptions``array``[]`HTML attributes for the outer ```vapidPublicKey``string`*(auto)*VAPID public key — read automatically from `Yii::$app->push` if not set`swUrl``string``'/push/push/sw'`Service Worker URL (use default unless you remap routes)`subscribeUrl``string``'/push/push/subscribe'`Endpoint to save a subscription`unsubscribeUrl``string``'/push/push/unsubscribe'`Endpoint to remove a subscription`vapidKeyUrl``string``'/push/push/vapid-key'`Endpoint to fetch VAPID public key dynamically**Styling the button with data attributes:**

The button gets the CSS class `push-subscribe-btn` automatically. You can target it in your stylesheet:

```
.push-subscribe-btn {
    /* your styles */
}

.push-subscribe-btn[data-push-active="1"] {
    /* styles when subscribed */
}
```

---

PushManager reference
---------------------

[](#pushmanager-reference)

`\iguazoft\push\components\PushManager` is the Yii2 application component registered as `Yii::$app->push`.

### Properties

[](#properties)

PropertyTypeDefaultDescription`vapidPublicKey``string``''`VAPID public key (Base64 URL-safe)`vapidPrivateKey``string``''`VAPID private key (Base64 URL-safe)`vapidSubject``string``'mailto:admin@example.com'`Contact address for VAPID`ttl``int``0`Message time-to-live in seconds (0 = server maximum)### Methods

[](#methods)

#### `send(string $title, string $body, ?int $userId = null, array $options = []): array`

[](#sendstring-title-string-body-int-userid--null-array-options---array)

Sends a notification to all subscriptions belonging to a user. If `$userId` is `null`, sends to all subscribers (same as `sendToAll`).

```
$result = Yii::$app->push->send('Title', 'Body', $userId, $options);
```

#### `sendToAll(string $title, string $body, array $options = []): array`

[](#sendtoallstring-title-string-body-array-options---array)

Sends a notification to every active subscriber in the database.

```
$result = Yii::$app->push->sendToAll('Title', 'Body', $options);
```

#### `generateVapidKeys(): array`

[](#generatevapidkeys-array)

Generates a new VAPID key pair. Run once during setup.

```
$keys = Yii::$app->push->generateVapidKeys();
// ['publicKey' => '...', 'privateKey' => '...']
```

### Available `$options` keys

[](#available-options-keys)

KeyTypeDescription`url``string`Page to open when the user clicks the notification`icon``string`URL to notification icon (PNG, recommended 192×192px)`badge``string`URL to small monochrome icon shown in Android status bar (72×72px)`image``string`URL to a large image displayed inside the notification`tag``string`Notification identifier — a new notification with the same tag replaces the previous one---

HTTP API endpoints
------------------

[](#http-api-endpoints)

These routes are registered automatically when the extension bootstraps.

MethodURLDescription`GET``/push/sw`Serves the Service Worker JavaScript file`POST``/push/subscribe`Saves a new push subscription`POST``/push/unsubscribe`Removes a push subscription`GET``/push/vapid-key`Returns the VAPID public key as JSON**POST `/push/subscribe` — request body:**

```
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "BNa7...",
    "auth":   "abc..."
  }
}
```

**POST `/push/subscribe` — response:**

```
{ "success": true, "id": 57 }
```

**POST `/push/unsubscribe` — request body:**

```
{ "endpoint": "https://fcm.googleapis.com/fcm/send/..." }
```

---

Browser compatibility
---------------------

[](#browser-compatibility)

BrowserSupportNotesChrome 50+✅Full supportEdge 17+✅Full supportFirefox 44+✅Full supportSamsung Internet 4+✅Full supportSafari 16.4+✅Requires iOS 16.4 or macOS Ventura+Safari &lt; 16.4❌Not supportedIE / Old Edge❌Not supportedThe widget automatically hides itself on unsupported browsers.

---

Troubleshooting
---------------

[](#troubleshooting)

**"Service Worker registration failed"**

- Your app must be served over **HTTPS**. On local development, use `http://localhost` (any other hostname without HTTPS will fail).
- Check that `/push/push/sw` returns a 200 response with `Content-Type: application/javascript`.

**Notifications not arriving**

- Verify VAPID keys are set correctly in `config/web.php`.
- Check that the PHP extension `gmp` or `bcmath` is enabled: `php -m | grep -E 'gmp|bcmath'`.
- Run `php yii push/stats` to confirm subscriptions exist in the database.
- Check browser notification permissions (the browser may have silently blocked them).

**"InvalidConfigException: PushManager requires vapidPublicKey..."**

- You haven't added the `push` component to `config/web.php`. Follow [Step 3 of Installation](#installation).

**Notifications arrive but no sound plays**

- Sound is controlled by the OS and browser notification settings, not by the application. Check your system's notification settings for the browser.
- On Windows, verify that browser notifications are not set to "Banner only" (silent mode) in System → Notifications.

**The subscribe button doesn't appear**

- The user's browser doesn't support the Push API (see [Browser compatibility](#browser-compatibility)).
- The widget hides itself automatically in this case — this is expected behavior.

**Migration fails with "Table already exists"**

- The table `push_subscriptions` already exists. Skip the migration or check for conflicts with existing tables.

---

License
-------

[](#license)

MIT © iguazoft

###  Health Score

37

—

LowBetter than 84% of packages

Maintenance98

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

13d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/625786bd75c11349dbaf4261a0351afe4a8e62ed7c2e133f0cde190fa2767ac5?d=identicon)[dannyrios81](/maintainers/dannyrios81)

---

Top Contributors

[![dannyrios81](https://avatars.githubusercontent.com/u/1534073?v=4)](https://github.com/dannyrios81 "dannyrios81 (1 commits)")

---

Tags

yii2push notificationsservice workerWeb Pushvapid

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/iguazoft-yii2-push-notifications/health.svg)

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

###  Alternatives

[bentools/webpush-bundle

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

71268.7k](/packages/bentools-webpush-bundle)[webzop/yii2-notifications

Notifications module for Yii2

71106.0k](/packages/webzop-yii2-notifications)[pushpad/pushpad-php

Pushpad PHP Library

26134.3k](/packages/pushpad-pushpad-php)[richardfan1126/yii2-js-register

Yii2 widget to register JS into view

1356.4k7](/packages/richardfan1126-yii2-js-register)

PHPackages © 2026

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