README

Laravel package for integrating with ntfy.sh notification service. This package provides a broadcaster implementation for Laravel Broadcasting and a notification channel for Laravel Notifications.

Features

• Laravel Broadcasting driver for ntfy
• Laravel Notification channel for ntfy
• Support for all ntfy features (priority, tags, attachments, actions, etc.)
• Multiple authentication methods (Bearer, Basic, Digest, API Key)
• Configurable SSL verification
• Rate limiting support
• Helper methods for common use cases

Installation

Install the package via Composer:

composer require uzinfo/ntfy-laravel

The service provider will be automatically registered.

Configuration

Environment Variables

Add the following variables to your .env file:

# Basic ntfy configuration
NTFY_BASE_URL=https://ntfy.sh
NTFY_TOKEN=your-token-here
NTFY_KEY=your-key-here
NTFY_AUTH=bearer
NTFY_VERIFY=true

# For broadcasting
BROADCAST_DRIVER=ntfy

Publishing Configuration

Publish the configuration files:

# Publish ntfy configuration
php artisan vendor:publish --tag=ntfy-config

# Publish broadcasting configuration (optional)
php artisan vendor:publish --tag=ntfy-broadcasting

Usage

Broadcasting Events

Create a broadcastable event:

<?php

namespace App\Events;

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class NotificationEvent implements ShouldBroadcast
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(
        public string $message,
        public int $userId,
        public ?string $title = null
    ) {}

    public function broadcastOn()
    {
        return new Channel('user.' . $this->userId);
    }

    public function broadcastWith()
    {
        return [
            'message' => $this->message,
            'title' => $this->title,
            'priority' => 4,
            'tags' => ['notification', 'alert'],
        ];
    }
}

Dispatch the event:

event(new NotificationEvent('Hello World!', 123, 'Important Message'));

Direct Ntfy Usage

Use the Ntfy class directly:

use UzInfo\NtfyLaravel\Ntfy;

$ntfy = new Ntfy();

// Simple notification
$ntfy->send('my-topic', 'Hello World!');

// With options
$ntfy->send('my-topic', 'Hello World!', [
    'title' => 'Important',
    'priority' => 5,
    'tags' => ['warning', 'urgent'],
    'click' => 'https://example.com',
    'icon' => 'https://example.com/icon.png'
]);

// Helper methods
$ntfy->urgent('my-topic', 'Critical alert!');
$ntfy->low('my-topic', 'Minor update');
$ntfy->markdown('my-topic', '**Bold** and *italic* text');
$ntfy->attach('my-topic', 'Check this file', 'https://example.com/file.pdf');

Laravel Notifications

Create a notification:

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use UzInfo\NtfyLaravel\NtfyChannel;
use UzInfo\NtfyLaravel\NtfyMessage;

class OrderShipped extends Notification
{
    public function via($notifiable)
    {
        return [NtfyChannel::class];
    }

    public function toNtfy($notifiable)
    {
        return NtfyMessage::create('Your order has been shipped!')
            ->title('Order Update')
            ->priority(4)
            ->tags(['package', 'shipped'])
            ->click('https://example.com/track/123')
            ->icon('📦');
    }
}

Add to your notifiable model:

class User extends Model
{
    public function routeNotificationForNtfy()
    {
        return 'user-' . $this->id;
    }
}

Send the notification:

$user->notify(new OrderShipped());

Authentication Methods

The package supports multiple authentication methods:

Bearer Token

NTFY_AUTH=bearer
NTFY_TOKEN=your-bearer-token

Basic Authentication

NTFY_AUTH=basic
NTFY_KEY=username
NTFY_TOKEN=password

Digest Authentication

NTFY_AUTH=digest
NTFY_KEY=username
NTFY_TOKEN=password

API Key

NTFY_AUTH=key
NTFY_KEY=your-api-key

No Authentication

NTFY_AUTH=null

Configuration Options

Priority Levels

• 1: Min priority
• 2: Low priority
• 3: Default priority (default)
• 4: High priority
• 5: Max/Urgent priority

Common Tags

You can use emoji shortcodes or custom strings:

• warning, alert, fire
• point_right, tada, package
• Custom strings like urgent, system

Actions

$actions = [
    [
        'action' => 'view',
        'label' => 'Open App',
        'url' => 'https://example.com'
    ],
    [
        'action' => 'http',
        'label' => 'Update Status',
        'url' => 'https://api.example.com/update',
        'method' => 'POST'
    ]
];

$ntfy->actions('my-topic', 'Message with actions', $actions);

Rate Limiting

The package includes built-in rate limiting configuration:

// config/ntfy.php
'rate_limit' => [
    'enabled' => true,
    'max_requests' => 60,
    'per_minutes' => 1,
],

Testing

The package includes comprehensive tests. Run them with:

composer test

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This package is open-sourced software licensed under the MIT license.

Credits

• UzInfo
• ntfy.sh for the amazing notification service
• Laravel for the framework

Support

If you discover any security vulnerabilities, please email security@example.com instead of using the issue tracker.

For bugs and feature requests, please use the GitHub issues.