PHPackages                             glueful/notiva - 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 & Notifications](/categories/mail)
4. /
5. glueful/notiva

ActiveGlueful-extension[Mail & Notifications](/categories/mail)

glueful/notiva
==============

Push notifications for Glueful (FCM, APNs, Web Push)

v0.8.4(2mo ago)021MITPHPPHP ^8.3

Since Oct 14Pushed 2mo agoCompare

[ Source](https://github.com/glueful/notiva)[ Packagist](https://packagist.org/packages/glueful/notiva)[ Docs](https://github.com/glueful/notiva)[ RSS](/packages/glueful-notiva/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (13)Used By (0)

Notiva (Push Notifications) for Glueful
=======================================

[](#notiva-push-notifications-for-glueful)

Overview
--------

[](#overview)

Notiva provides a unified, multi-channel push notification layer for the Glueful Framework. It supports FCM (HTTP v1), direct APNs, and Web Push (VAPID), with a clean routing model, optional per‑device registration endpoints, and configuration via environment variables.

Features
--------

[](#features)

- ✅ Unified push API (FCM, APNs, Web Push)
- ✅ FCM HTTP v1 with Android options
- ✅ Direct APNs via pushok (token or certificate)
- ✅ Web Push via VAPID (minishlink/web-push)
- ✅ Device registry: register, list, revoke/delete
- ✅ Config-driven behavior (env + merged config)
- ✅ Secure, typed responses and logging

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

[](#requirements)

- PHP 8.3+
- Glueful Framework 1.22.0+
- OpenSSL PHP extension
- Optional libraries:
    - FCM: built-in over Glueful HTTP client (no extra package)
    - APNs: `edamov/pushok`
    - Web Push: `minishlink/web-push`

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

[](#installation)

```
composer require glueful/notiva

# Rebuild extension cache
php glueful extensions:cache

# Enable in development
php glueful extensions:enable Notiva

# Run migrations for push_devices
php glueful migrate run

# Verify
php glueful extensions:list
php glueful extensions:info Notiva
```

Verify Installation
-------------------

[](#verify-installation)

Check discovery and provider wiring:

```
php glueful extensions:list
php glueful extensions:info Notiva
php glueful extensions:why Glueful\\Extensions\\Notiva\\NotivaServiceProvider
```

Run database migrations (if not auto-run):

```
php glueful migrate run
```

Quick endpoint checks (replace placeholders):

```
API_BASE=http://localhost:8000
TOKEN=""
USER_UUID=""

# 1) Register an FCM device
curl -s -X POST "$API_BASE/notiva/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_uuid": "'$USER_UUID'",
    "provider": "fcm",
    "platform": "android",
    "device_token": "fcm-token-example"
  }' | jq .

# 2) List devices
curl -s "$API_BASE/notiva/devices?user_uuid=$USER_UUID" \
  -H "Authorization: Bearer $TOKEN" | jq .

# 3) Unregister device by provider+token (soft revoke)
curl -s -X DELETE "$API_BASE/notiva/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_uuid": "'$USER_UUID'",
    "provider": "fcm",
    "device_token": "fcm-token-example"
  }' | jq .

# 4) Unregister device by UUID (hard delete)
DEVICE_UUID=""
curl -s -X DELETE "$API_BASE/notiva/devices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_uuid": "'$USER_UUID'",
    "uuid": "'$DEVICE_UUID'",
    "force": true
  }' | jq .
```

Getting Started
---------------

[](#getting-started)

- Require the extension in your Glueful app and register the provider `Glueful\Extensions\Notiva\NotivaServiceProvider`.
- Configure `config/notiva.php` (published in the extension) or set the relevant env vars:
    - `NOTIVA_FCM_ENABLED`
    - HTTP v1 only: `NOTIVA_FCM_CREDENTIALS` (service account JSON or path) and `NOTIVA_FCM_PROJECT`
    - `NOTIVA_APNS_ENABLED`, `NOTIVA_APNS_P8_PATH`, `NOTIVA_APNS_KEY_ID`, `NOTIVA_APNS_TEAM_ID`, `NOTIVA_APNS_BUNDLE_ID`
    - `NOTIVA_WEBPUSH_ENABLED`, `NOTIVA_VAPID_PUBLIC_KEY`, `NOTIVA_VAPID_PRIVATE_KEY`, `NOTIVA_VAPID_SUBJECT`

Endpoints
---------

[](#endpoints)

- Base prefix: `/notiva`
- All endpoints require auth and apply rate limiting.

1. Register device

- `POST /notiva/devices` (60/min)
- Body (JSON or form): `user_uuid` (required), `provider` (`fcm|apns|webpush`, required), `platform`, `device_token` (for fcm/apns), `subscription` (for webpush), `device_id`, `notifiable_type`, `notifiable_id`, `app_id`, `bundle_id`, `locale`, `timezone`

### Device registration field guidance

[](#device-registration-field-guidance)

- `notifiable_type` (optional): The model/entity type that owns this device when you use polymorphic notification targets. Send a stable class or type name used by your app (for example `App\\Models\\User`, `merchant`, `tenant_user`). Use this when a device may belong to different actor types, not just a single user table.
- `notifiable_id` (optional): The identifier for the `notifiable_type` record. This should match the primary identifier your app uses for that type (for example a UUID, nanoid, or string ID). Send this together with `notifiable_type`.
- `app_id` (optional): Your client application identifier for analytics/routing across multiple apps that share one backend. Examples: `parp-mobile`, `parp-web`, `admin-console`. This is an application-level label, not an OS package/bundle identifier.
- `bundle_id` (optional, recommended for iOS/APNs): The platform package identifier for the app build that registered the device. Examples: `com.parp.app` (iOS/macOS bundle id) or `com.parp.android` (Android package/applicationId). For APNs, this should typically match the app topic/bundle used to send notifications.

Send these fields when you need tenant/app/device segmentation, multi-app support, or polymorphic ownership. If you only target authenticated users in a single app, you can omit `notifiable_type`, `notifiable_id`, and `app_id`.

2. List devices

- `GET /notiva/devices` (100/min)
- Query: `user_uuid` (required), `provider` (optional), `platform` (optional)

3. Unregister device

- `DELETE /notiva/devices` (20/min)
- Body/Query: `user_uuid` (required) and either `uuid` OR (`provider` + `device_token`)
- Optional: `force=true` to hard delete instead of revoke

Notifiable Contract
-------------------

[](#notifiable-contract)

Implement `routeNotificationFor('push')` on your notifiable entity to return tokens/subscriptions:

```
// Examples of supported shapes
return [
  'fcm' => ['fcm-token-1', 'fcm-token-2'],
  'apns' => ['apns-token-1'],
  'webpush' => [
    ['endpoint' => '...', 'keys' => ['p256dh' => '...', 'auth' => '...']],
  ],
];

```

Notes
-----

[](#notes)

- Channels supported: FCM HTTP v1, direct APNs (pushok), and Web Push (minishlink/web-push).
- Graceful fallbacks: if APNs/Web Push libraries are not installed or config is missing, those channels are skipped with logs; others continue.
- Device registry: includes migration for `push_devices` and secure endpoints to register/list/unregister.
- Middleware: endpoints ship with `auth` and `rate_limit` middleware; adjust per your needs.

FCM HTTP v1
-----------

[](#fcm-http-v1)

- Notiva uses FCM HTTP v1 exclusively.
- Require `NOTIVA_FCM_CREDENTIALS` and `NOTIVA_FCM_PROJECT`.
- The service account JSON must include `client_email` and `private_key`.
- Tokens are sent individually to `projects/{project}/messages:send` and results aggregated.

Web Push Setup
--------------

[](#web-push-setup)

- Install library: `composer require minishlink/web-push`
- Configure VAPID keys in env or config:
    - `NOTIVA_WEBPUSH_ENABLED=true`
    - `NOTIVA_VAPID_PUBLIC_KEY=...`
    - `NOTIVA_VAPID_PRIVATE_KEY=...`
    - `NOTIVA_VAPID_SUBJECT=mailto:you@example.com` (or your site origin)
- Notifiable should return subscriptions from `routeNotificationFor('push')`:

```
return [
  'webpush' => [
    [
      'endpoint' => 'https://fcm.googleapis.com/fcm/send/XXX',
      'keys' => [
        'p256dh' => 'BASE64_PUBLIC_KEY',
        'auth' => 'BASE64_AUTH'
      ]
    ]
  ]
];

```

- Supported payload fields for Web Push (client-side Notification options):
    - `title`, `body`, `icon`, `image`, `badge`
    - `data` (object), `tag`
    - `renotify` (bool), `requireInteraction` (bool)
    - `actions` (array of `{action, title, icon}`)
    - Delivery options: `ttl` (seconds), `urgency` (`very-low|low|normal|high`)

APNs Setup
----------

[](#apns-setup)

- Install library: `composer require edamov/pushok`
- Recommended (token-based) configuration:
    - `NOTIVA_APNS_ENABLED=true`
    - `NOTIVA_APNS_P8_PATH=/path/to/AuthKey_XXXX.p8`
    - `NOTIVA_APNS_KEY_ID=XXXX`
    - `NOTIVA_APNS_TEAM_ID=YYYY`
    - `NOTIVA_APNS_BUNDLE_ID=com.example.app`
    - `NOTIVA_APNS_SANDBOX=true` (development) or `false` (production)
- Certificate-based (fallback):
    - `NOTIVA_APNS_ENABLED=true`
    - `NOTIVA_APNS_CERT=/path/to/cert.pem`
    - `NOTIVA_APNS_PASSPHRASE=optional`
    - `NOTIVA_APNS_BUNDLE_ID=com.example.app`
    - `NOTIVA_APNS_SANDBOX=true|false`
- Notifiable should return APNs tokens from `routeNotificationFor('push')`:

```
return [
  'apns' => ['apns-token-1', 'apns-token-2']
];

```

- Supported payload fields for APNs:
    - `title`, `body`, `sound`, `badge`, `category`, `data` (object)
    - `apns_push_type` (e.g., `alert`, `background`)
    - `apns_priority` (`10` immediate, `5` background)
    - `collapse_id` (to coalesce notifications)
- Notes:
    - APNs topic is set from `NOTIVA_APNS_BUNDLE_ID`.
    - `NOTIVA_APNS_SANDBOX` selects api.sandbox.push.apple.com vs api.push.apple.com.

Usage (PHP)
-----------

[](#usage-php)

Direct push via the Notiva channel using ChannelManager:

```