Filament Notifier

https://github.com/usamamuneerchaudhary/filament-notifier
Admin
A powerful notification system for FilamentPHP that handles multi-channel notifications with...
Tokens:5,300
Snippets:69
Trust Score:9.3
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run the installation command

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Executes the setup process including migrations, configuration publishing, and sample data creation.

```bash
php artisan notifier:install
```

--------------------------------

### Install the package via Composer

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Run this command in your terminal to add the package to your project dependencies.

```bash
composer require usamamuneerchaudhary/filament-notifier
```

--------------------------------

### Access Service Facades

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Utilize provided facades for preferences, analytics, URL tracking, and repository lookups. Ensure composer dump-autoload is run after installation.

```php
use Usamamuneerchaudhary\Notifier\Facades\Preference;
use Usamamuneerchaudhary\Notifier\Facades\Analytics;
use Usamamuneerchaudhary\Notifier\Facades\UrlTracking;
use Usamamuneerchaudhary\Notifier\Facades\NotificationRepo;

// Get user preferences
$preferences = Preference::getUserPreferences($user, 'user.registered');

// Check analytics status
if (Analytics::isEnabled()) {
    Analytics::trackOpen($notification);
}

// Safely redirect URLs
return UrlTracking::safeRedirect('https://example.com');

// Find notification by token
$notification = NotificationRepo::findByToken($token);
```

--------------------------------

### GET /notifier/track/open/{token}

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Tracks an email open event by loading a 1x1 transparent pixel.

```APIDOC
## GET /notifier/track/open/{token}

### Description
Records an email open event when the tracking pixel is loaded. It updates the opened_at timestamp and increments the opens_count.

### Method
GET

### Endpoint
/notifier/track/open/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The unique identifier for the notification tracking session.
```

--------------------------------

### GET /api/notifier/preferences/available

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Retrieves the list of available events and notification channels supported by the system.

```APIDOC
## GET /api/notifier/preferences/available

### Description
Fetches the available events and notification channels configured in the system.

### Method
GET

### Endpoint
/api/notifier/preferences/available

### Response
#### Success Response (200)
- **data** (object) - Contains lists of available events and channel types.
```

--------------------------------

### GET /api/notifier/preferences

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Retrieves a list of all notification preferences for the authenticated user.

```APIDOC
## GET /api/notifier/preferences

### Description
Retrieves all notification preferences for the authenticated user.

### Method
GET

### Endpoint
/api/notifier/preferences

### Response
#### Success Response (200)
- **data** (array) - List of event preferences including event keys, names, groups, descriptions, and channel statuses.
```

--------------------------------

### GET /api/notifier/preferences/{eventKey}

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Retrieves the notification preference settings for a specific event.

```APIDOC
## GET /api/notifier/preferences/{eventKey}

### Description
Retrieves the current preference settings for a specific event identified by its key.

### Method
GET

### Endpoint
/api/notifier/preferences/{eventKey}

### Parameters
#### Path Parameters
- **eventKey** (string) - Required - The unique key of the event.
```

--------------------------------

### GET /notifier/track/click/{token}

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Tracks a link click event and redirects the user to the original URL.

```APIDOC
## GET /notifier/track/click/{token}

### Description
Tracks a link click event, updates the clicked_at timestamp, increments the clicks_count, and performs a safe redirect to the original URL.

### Method
GET

### Endpoint
/notifier/track/click/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The unique identifier for the notification tracking session.

#### Query Parameters
- **url** (string) - Required - The encoded destination URL to redirect to.
```

--------------------------------

### Publish and Run Migrations

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Commands to publish the package's migration files and apply them to the database.

```bash
php artisan vendor:publish --tag=notifier-migrations
```

```bash
php artisan migrate
```

--------------------------------

### Configure notification channels in .env

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Set up environment variables for email, Slack, and SMS providers to enable specific notification channels.

```env
# Email Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="Your App"

# Notifier Package Settings
NOTIFIER_EMAIL_ENABLED=true
NOTIFIER_SLACK_ENABLED=false
NOTIFIER_SMS_ENABLED=false

# Slack Configuration
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_CHANNEL=#notifications

# SMS Configuration (Twilio)
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+1234567890
```

--------------------------------

### Run Package Tests

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Executes the full test suite for the package.

```bash
composer test
```

--------------------------------

### Configure Event-Based Notifications

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Define event mappings and their associated channels and templates in the config/notifier.php file.

```php
'events' => [
    'user.registered' => [
        'channels' => ['email', 'slack'],
        'template' => 'welcome-email',
    ],
    'order.completed' => [
        'channels' => ['email', 'sms'],
        'template' => 'order-confirmation',
    ],
],
```

--------------------------------

### Send Notifications via Facade or Service

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Use the Notifier facade or the app service to dispatch notifications with specific event keys and data payloads.

```php
use Usamamuneerchaudhary\Notifier\Facades\Notifier;

// Send a notification using the facade
Notifier::send($user, 'user.registered', [
    'name' => $user->name,
    'email' => $user->email,
]);

// Or using the service directly
$notifier = app('notifier');
$notifier->send($user, 'user.registered', [
    'name' => $user->name,
    'email' => $user->email,
]);
```

--------------------------------

### Implement Dependency Injection

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Inject services directly into controllers to improve testability and maintainability.

```php
use Usamamuneerchaudhary\Notifier\Services\PreferenceService;
use Usamamuneerchaudhary\Notifier\Services\AnalyticsService;

class MyController extends Controller
{
    public function __construct(
        protected PreferenceService $preferenceService,
        protected AnalyticsService $analyticsService
    ) {}

    public function index()
    {
        $preferences = $this->preferenceService->getUserPreferences($user, 'event.key');
        
        if ($this->analyticsService->isEnabled()) {
            // Do something
        }
    }
}
```

--------------------------------

### Develop Custom Channel Drivers

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Implement the ChannelDriverInterface to create custom notification delivery logic.

```php
use Usamamuneerchaudhary\Notifier\Services\ChannelDrivers\ChannelDriverInterface;
use Usamamuneerchaudhary\Notifier\Models\Notification;

class CustomChannelDriver implements ChannelDriverInterface
{
    public function send(Notification $notification): bool
    {
        // Your custom sending logic here
        return true;
    }

    public function validateSettings(array $settings): bool
    {
        // Validate your channel settings
        return !empty($settings['api_key'] ?? null);
    }
}
```

--------------------------------

### Preference Facade Usage

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for retrieving and checking user notification preferences.

```php
use Usamamuneerchaudhary\Notifier\Facades\Preference;

Preference::getUserPreferences($user, string $eventKey): array
Preference::getChannelsForEvent(NotificationEvent $event, ?NotificationPreference $preference): array
Preference::shouldSendToChannel($user, string $channelType, array $preferences): bool
```

--------------------------------

### Configure Event Triggers

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Map application events to notification channels and templates, including optional delivery delays.

```php
'events' => [
    'user.registered' => [
        'channels' => ['email', 'slack'],
        'template' => 'welcome-email',
        'delay' => 0, // Send immediately
    ],
    'order.shipped' => [
        'channels' => ['email', 'sms'],
        'template' => 'order-shipped',
        'delay' => 300, // 5 minutes delay
    ],
],
```

--------------------------------

### Register the plugin in Filament

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Add the plugin to your Filament panel configuration to enable the dashboard and resource management.

```php
use Usamamuneerchaudhary\Notifier\FilamentNotifierPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentNotifierPlugin::make(),
        ]);
}
```

--------------------------------

### Create Notification Templates

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Define templates programmatically using the NotificationTemplate model.

```php
use Usamamuneerchaudhary\Notifier\Models\NotificationTemplate;

NotificationTemplate::create([
    'title' => 'Welcome Email',
    'key' => 'welcome-email',
    'type' => 'email',
    'subject' => 'Welcome to {{app_name}}, {{name}}!',
    'content' => 'Hi {{name}},\n\nWelcome to {{app_name}}! We\'re excited to have you on board.',
    'variables' => [
        'name' => 'User\'s full name',
        'app_name' => 'Application name',
    ],
]);
```

--------------------------------

### Retrieve all user preferences

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Fetches a list of all notification events and the user's current channel subscription status.

```http
GET /api/notifier/preferences
Authorization: Bearer {token}
```

```json
{
  "data": [
    {
      "event_key": "user.registered",
      "event_name": "User Registered",
      "event_group": "User",
      "description": "Sent when a new user registers",
      "channels": {
        "email": true,
        "sms": false,
        "push": true
      }
    }
  ]
}
```

--------------------------------

### Preference Facade

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for managing and checking user notification preferences.

```APIDOC
## Preference Facade

### getUserPreferences($user, string $eventKey): array
Retrieves preferences for a specific user and event.

### getChannelsForEvent(NotificationEvent $event, ?NotificationPreference $preference): array
Determines the channels enabled for a specific event.

### shouldSendToChannel($user, string $channelType, array $preferences): bool
Checks if a notification should be sent to a specific channel based on preferences.
```

--------------------------------

### Configure Notification Channels

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Define enabled channels and their respective driver settings within the notifier configuration file.

```php
// config/notifier.php
'channels' => [
    'email' => [
        'enabled' => true,
        'driver' => 'smtp',
        'from_address' => 'noreply@example.com',
        'from_name' => 'Your App',
    ],
    'slack' => [
        'enabled' => true,
        'webhook_url' => env('SLACK_WEBHOOK_URL'),
        'channel' => '#notifications',
    ],
    'sms' => [
        'enabled' => true,
        'driver' => 'twilio',
        'account_sid' => env('TWILIO_ACCOUNT_SID'),
        'auth_token' => env('TWILIO_AUTH_TOKEN'),
        'phone_number' => env('TWILIO_PHONE_NUMBER'),
    ],
],
```

--------------------------------

### Send Test Notifications

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Commands to trigger test notifications with optional custom data and channel selection.

```bash
# Send a test notification
php artisan notifier:test user.registered --user=1

# Send with custom data
php artisan notifier:test user.registered --user=1 --data="name=John Doe" --data="app_name=Test App"

# Send to specific channel
php artisan notifier:test user.registered --user=1 --channel=email
```

--------------------------------

### UrlTracking Facade Usage

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for handling URL redirection and rewriting for tracking purposes.

```php
use Usamamuneerchaudhary\Notifier\Facades\UrlTracking;

UrlTracking::safeRedirect(string $url): RedirectResponse
UrlTracking::rewriteUrlsForTracking(string $content, string $token): string
```

--------------------------------

### Retrieve available events and channels

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Lists all system-defined notification events and available communication channels.

```http
GET /api/notifier/preferences/available
Authorization: Bearer {token}
```

```json
{
  "data": {
    "events": [
      {
        "key": "user.registered",
        "name": "User Registered",
        "group": "User",
        "description": "Sent when a new user registers",
        "default_channels": ["email"]
      }
    ],
    "channels": [
      {
        "type": "email",
        "title": "Email",
        "icon": "heroicon-o-envelope"
      },
      {
        "type": "sms",
        "title": "SMS",
        "icon": "heroicon-o-device-phone-mobile"
      }
    ]
  }
}
```

--------------------------------

### Analytics Facade

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for tracking notification opens and clicks.

```APIDOC
## Analytics Facade

### isEnabled(): bool
Checks if analytics tracking is enabled.

### isOpenTrackingEnabled(): bool
Checks if open tracking is enabled.

### isClickTrackingEnabled(): bool
Checks if click tracking is enabled.

### generateTrackingPixel(string $trackingToken): string
Generates a tracking pixel URL.

### trackOpen(Notification $notification): void
Records an open event for a notification.

### trackClick(Notification $notification): void
Records a click event for a notification.
```

--------------------------------

### Analytics Facade Usage

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for managing and tracking notification analytics like opens and clicks.

```php
use Usamamuneerchaudhary\Notifier\Facades\Analytics;

Analytics::isEnabled(): bool
Analytics::isOpenTrackingEnabled(): bool
Analytics::isClickTrackingEnabled(): bool
Analytics::generateTrackingPixel(string $trackingToken): string
Analytics::trackOpen(Notification $notification): void
Analytics::trackClick(Notification $notification): void
```

--------------------------------

### UrlTracking Facade

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for handling URL redirection and tracking rewrites.

```APIDOC
## UrlTracking Facade

### safeRedirect(string $url): RedirectResponse
Performs a safe redirect.

### rewriteUrlsForTracking(string $content, string $token): string
Rewrites URLs within content to include tracking tokens.
```

--------------------------------

### Schedule Notifications

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Queue notifications for future delivery using the schedule method with a Carbon instance.

```php
use Carbon\Carbon;

// Schedule a notification for later
$notifier->schedule($user, 'reminder.email', Carbon::now()->addDays(7), [
    'task_name' => 'Complete project review',
]);
```

--------------------------------

### NotifierManager Methods

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for sending, scheduling, and registering notification events and channels.

```APIDOC
## NotifierManager Methods

### send($user, string $eventKey, array $data = [])
Sends a notification to a user based on an event key.

### sendNow($user, string $eventKey, array $data = [])
Sends a notification immediately, bypassing the queue.

### sendToChannel($user, string $eventKey, string $channelType, array $data = [])
Sends a notification to a specific channel type.

### schedule($user, string $eventKey, Carbon $scheduledAt, array $data = [])
Schedules a notification for a future time.

### registerChannel(string $type, $handler)
Registers a custom channel driver.

### registerEvent(string $key, array $config)
Registers an event configuration.

### getRegisteredChannels()
Retrieves all registered channel types.

### getRegisteredEvents()
Retrieves all registered event keys.
```

--------------------------------

### NotificationRepo Facade Usage

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Method for retrieving notifications by their unique token.

```php
use Usamamuneerchaudhary\Notifier\Facades\NotificationRepo;

NotificationRepo::findByToken(string $token): ?Notification
```

--------------------------------

### Retrieve preference for a specific event

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Fetches the current channel configuration for a single event identified by its key.

```http
GET /api/notifier/preferences/{eventKey}
Authorization: Bearer {token}
```

```http
GET /api/notifier/preferences/user.registered
```

```json
{
  "data": {
    "event_key": "user.registered",
    "event_name": "User Registered",
    "event_group": "User",
    "description": "Sent when a new user registers",
    "channels": {
      "email": true,
      "sms": false
    }
  }
}
```

--------------------------------

### PUT /api/notifier/preferences/{eventKey}

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Updates the notification channel preferences for a specific event.

```APIDOC
## PUT /api/notifier/preferences/{eventKey}

### Description
Updates the user's notification channel settings for the specified event.

### Method
PUT

### Endpoint
/api/notifier/preferences/{eventKey}

### Parameters
#### Path Parameters
- **eventKey** (string) - Required - The unique key of the event.

#### Request Body
- **channels** (object) - Required - Map of channel types to boolean values.
- **settings** (object) - Optional - Additional event settings.

### Response
#### Success Response (200)
- **data** (object) - The updated preference object.
- **message** (string) - Confirmation message.
```

--------------------------------

### NotificationRepo Facade

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Methods for retrieving notifications by token.

```APIDOC
## NotificationRepo Facade

### findByToken(string $token): ?Notification
Finds a notification record by its unique token.
```

--------------------------------

### Cleanup Analytics Commands

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Commands to remove old analytics data based on the configured retention period.

```bash
# Clean up analytics data older than retention period
php artisan notifier:cleanup-analytics

# Dry run to see what would be cleaned
php artisan notifier:cleanup-analytics --dry-run
```

--------------------------------

### Cleanup Analytics Data

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Commands to remove or preview the removal of analytics data based on retention settings.

```bash
# Clean up old analytics data
php artisan notifier:cleanup-analytics

# Preview what would be cleaned (dry run)
php artisan notifier:cleanup-analytics --dry-run
```

--------------------------------

### Link Click Tracking Endpoint

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

The endpoint used to track link clicks and perform secure redirects.

```http
GET /notifier/track/click/{token}?url={encoded_url}
```

--------------------------------

### Email Open Tracking Endpoint

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

The endpoint used by the tracking pixel to record email open events.

```http
GET /notifier/track/open/{token}
```

--------------------------------

### Update preference for an event

Source: https://github.com/usamamuneerchaudhary/filament-notifier/blob/main/README.md

Updates the notification channels for a specific event. Returns a 403 error if the administrator has disabled user overrides.

```http
PUT /api/notifier/preferences/{eventKey}
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "channels": {
    "email": true,
    "sms": true,
    "push": false
  },
  "settings": {}
}
```

```json
{
  "data": {
    "event_key": "user.registered",
    "event_name": "User Registered",
    "channels": {
      "email": true,
      "sms": true,
      "push": false
    }
  },
  "message": "Preferences updated successfully."
}
```
Tokens:
Raw