README

Firebase push notifications and in-app notifications for Statamic. Ships with an FCM token store, push sender, and helper templates for notification lists.

Features

• Firebase Cloud Messaging (web push) integration
• Per-user notification preferences (email / push / both)
• In-app notifications stored on Statamic users
• Admin manual notification endpoint
• Notification list partials + unread badge modifier
• Service worker + Firebase config endpoint

Installation

1) Require the package

composer require yourcreativepeople/statamic-notifications

2) Publish config, migrations, and assets

php artisan vendor:publish --tag=statamic-notifications-config
php artisan vendor:publish --tag=statamic-notifications-migrations
php artisan vendor:publish --tag=statamic-notifications-assets
php artisan vendor:publish --tag=statamic-notifications-views
php artisan vendor:publish --tag=statamic-notifications-blueprints

3) Run migrations

php artisan migrate

4) Add the notification fields to your user blueprint

• Copy resources/blueprints/vendor/statamic-notifications/user_notifications_fields.yaml into your user blueprint.

Firebase setup (web push)

1) Create a Firebase project at https://console.firebase.google.com. 2) Add a Web App to the project (Project settings -> General -> Your apps). 3) Copy the Firebase config values into your .env:

FIREBASE_API_KEY=...
FIREBASE_AUTH_DOMAIN=...
FIREBASE_PROJECT_ID=...
FIREBASE_STORAGE_BUCKET=...
FIREBASE_MESSAGING_SENDER_ID=...
FIREBASE_APP_ID=...
FIREBASE_VAPID_PUBLIC_KEY=...

4) Generate a VAPID key (Project settings -> Cloud Messaging -> Web configuration). 5) Create a service account:

• Project settings -> Service accounts -> Generate new private key.
• Save the JSON to config/firebase-credentials.json (or update FIREBASE_SERVICE_ACCOUNT).

Front-end setup

1) Ensure the service worker exists at public/firebase-messaging-sw.js.

• This package publishes one that imports /notifications/firebase-config.js.

2) Add the scripts to your base layout (Antlers example):

{{ notifications:scripts }}

3) Add a button to request permission:

<button type="button" data-notifications-enable>Enable Notifications</button>

Templates

This package ships with minimal Antlers templates you can publish and customize:

• resources/views/vendor/statamic-notifications/partials/notifications_list.antlers.html
• resources/views/vendor/statamic-notifications/partials/notification_badge.antlers.html
• resources/views/vendor/statamic-notifications/templates/notifications.antlers.html
• resources/views/vendor/statamic-notifications/templates/admin_notifications.antlers.html

Use in a page:

{{ partial:statamic-notifications::partials/notifications_list title="Notifications" }}

Routes

All routes are configurable in config/statamic-notifications.php. Default endpoints:

• POST /notify
• POST /admin/notify
• POST /api/notifications/token
• POST /api/notifications/clear
• POST /api/notifications/read
• POST /api/notifications/remove
• GET /notifications/firebase-config.js

Security

Set STATAMIC_NOTIFICATIONS_API_KEY to require the header X-Notifications-Key for push endpoints.

Testing / maintenance

• Cleanup duplicate tokens:

  php artisan statamic-notifications:cleanup-tokens
  

Notes

• If you use a CSP, allow https://www.gstatic.com for Firebase scripts.
• Your site must be served over HTTPS for push notifications.