cjpanilag/simple-notifications

Simplified notifications for AWS SNS, FCM Push Notifications, emails, and more.

1.0.1 2023-05-13 12:49 UTC

Requires

• php: ^8.0
• illuminate/support: ~8|~9|~10
• kreait/firebase-php: 6.3.1
• laravel-notification-channels/aws-sns: ^1.4
• laravel-notification-channels/fcm: ~2.0
• luchavez/aws-ses-bounce: ^1.0
• luchavez/starter-kit: ^1.0

Requires (Dev)

• orchestra/testbench: ~6|~7|~8
• phpunit/phpunit: ~9.0
• roave/security-advisories: dev-latest

Suggests

• luchavez/boilerplate-generator: ^1.0
• luchavez/starter-kit: ^1.0

MIT

• Carl Jeffrie Panilag
• James Carlo Luchavez

• laravel
• SimpleNotifications

README

Simplified notifications for AWS SNS, FCM Push Notifications, emails, and more.

Installation

Via Composer

$ composer require cjpanilag/simple-notifications --with-all-dependencies
$ php artisan migrate

After migration, simple-notification will generate two (2) tables namely fcm_tokens & simple_devices. Make sure to remove any conflicting table or attribute in your root project.

Usage

AWS SNS

User Model Configuration

use Cjpanilag\SimpleNotifications\Traits\HasSnsNotifiableTrait;

class User extends Authenticatable
{

    use HasApiTokens, HasFactory, HasSnsNotifiableTrait;
    
    /**
     * Overridden method (optional)
     * By default, `SnsNoticiableTrait` will look
     * for the specific attribute in your model:
     *       `phone`,
     *       `phone_number`,
     *       `full_phone`
     * 
     * @override
     * @param $notification
     * @return string|null
     */
    public function routeNotificationForSns($notification): string|null
    {
        // model attribute
        return $this->specific_mobile_number_attribute;
    }
}

Note: In order to let your Notification know which phone you are sending to, the channel will look for the phone, phone_number or full_phone attribute of the Notifiable model.

Sending SMS to user

// Sending SMS to a User model...
$user = User::first();

simpleNotifications()->sns()
            ->user($user)
            ->content('Message here...')
            ->execute();

// Sending SMS to a specific phone...
simpleNotifications()->sns()
            ->mobile('[phone]')
            ->content('Message here...')
            ->execute();

Sending SMS using content callable

// Sending SMS to a User model...
$user = User::first();

simpleNotifications()->sns()
            ->user($user)
            ->content(fn($user) => "Welcome $user->name") // passing notifiable
            ->execute();

// Sending SMS to a specific phone...
simpleNotifications()->sns()
            ->mobile('[phone]')
            ->content(fn($user) => "Welcome $user->name") // passing notifiable
            ->execute();

Sending SMS using SnsMessage as content

// Sending SMS to a User model...
$user = User::first();

simpleNotifications()->sns()->user($user)->content(function ($user) {
    $snsMessage = new SnsMessage('message here...');

    $snsMessage->sender('FIN-PAY');
    $snsMessage->transactional(true);

    return $snsMessage;
})->execute();

// Sending SMS to a specific phone...
simpleNotifications()->sns()->mobile('[phone]')->content(function ($user) {
    $snsMessage = new SnsMessage('message here...');

    $snsMessage->sender('FIN-PAY');
    $snsMessage->transactional(true);

    return $snsMessage;
})->execute();

Available Methods

method	parameter	return type	description
user	Model	static	assigning user.
content	SnsMessage string callable	static	can be message or a callable function.
mobile	string	static	replacement for user methods.
execute	none	void	will execute the sending.

Note: user or mobile method should not be used at the same time.

Example:

simpleNotifications()->sns()
            ->user($user)               // User already have <mobile number attribute>...
            ->mobile('[phone]')    // Will conflict with User mobile number attribute...
            ->content('Message here...')
            ->execute();

SES MAIL

User Model Configuration

use Cjpanilag\SimpleNotifications\Traits\HasMailNotifiableTrait;

class Model extends Authenticatable
{
    use HasApiTokens, HasFactory, HasMailNotifiableTrait;
    
    /**
     * @param $notification
     * @return array|string|null
     */
    public function routeNotificationForMail($notification): array|string|null
    {
        // Define a specific <email attribute>
        return $this->email_address;
    }
}

Note: By default, Notification will send email to User's email attribute.

Sending Mail to user

// Sending mail to a User model...
$user = User::first();

simpleNotifications()->mail()
    ->user($user)
    ->subject('Test Subject 123')
    ->body('test body')
    ->footer('test footer')
    ->actionMessage('PUSH ME!')
    ->actionUrl('http://localhost')
    ->execute();

// Sending mail to a specific email address...
simpleNotifications()->mail()
    ->emailAddress('[e-mail]')
    ->subject('Test Subject 123')
    ->body('test body')
    ->footer('test footer')
    ->actionMessage('PUSH ME!')
    ->actionUrl('http://localhost')
    ->execute();

Sending Mail using MailMessage as content

// Sending mail to a User model...
$user = User::first();

simpleNotifications()->mail()->user($user)->content(function ($user) {
    $mailMessage = new MailMessage();
    $subject = 'test subject 2';

    if ($user) {
        $mailMessage->subject($subject);
    }

    $mailMessage->line('this is a best body number 2')
        ->action('PUSH ME!', 'https://test.com')
        ->line('this is a test footer 2');

    return $mailMessage;
})->execute();

// Sending mail to a specific email address...
```php 
simpleNotifications()->mail()->emailAddress('[e-mail]')->content(function ($user) {
    $mailMessage = new MailMessage();
    $subject = 'test subject 2';

    if ($user) {
        $mailMessage->subject($subject);
    }

    $mailMessage->line('this is a best body number 2')
        ->action('PUSH ME!', 'https://test.com')
        ->line('this is a test footer 2');

    return $mailMessage;
})->execute();

Sending Mail using MailMessage with customized view as content

// Sending mail to a specific email address...
simpleNotifications()->mail()->emailAddress('[e-mail]')->content(function ($user) {
    $mailMessage = new MailMessage();
    
    $mailMessage->view('view.template');

    return $mailMessage;
})->execute();

Available Methods

method	parameter	return type	description
user	Model	static	notifiable.
subject	string	static	email subject.
title	string	static	email title.
footer	string	static	email footer.
actionMessage	string	static	action message.
actionUrl	string	static	action URL.
emailAddress	string	static	replacement for user methods.
execute	none	static	execute notification.

Note: user or emailAddress method should not be used at the same time.

Example:

$user = User::first();

simpleNotifications()->mail()
    ->user($user)                               // user has email attribute
    ->emailAddress('[e-mail]')    // conflict with email attribute
    ->subject('Test Subject 123')
    ->body('test body')
    ->footer('test footer')
    ->actionMessage('PUSH ME!')
    ->actionUrl('http://localhost')
    ->execute();

FCM Notification

Make sure that you already run artisan migrate after installing this package. FCM will use the fcm_tokens table and simple_devices table.

simple_devices table stores users' devices. Each device can have multiple FCM tokens. fcm_tokens table stores the devices' FCM tokens.

Simple Device API

A route will be provided by this package. Check your project level routes/api.php for possible conflicts.

POST /api/device

body

key	description
device_id	required unique
unique_id	required
brand	nullable
type	nullable
name	nullable
manufacturer	nullable
model	nullable
system_name	nullable
system_version	nullable
version	nullable
active	nullable

FCM Token API

A route will be provided by this package. Check your project level routes/api.php for possible conflicts.

POST /api/fcm-token

key	description
device_uuid	required
token	required

Sending FCM Notification to user

$user = User::first();

simpleNotifications()
    ->fcm()
    ->user($user)
    ->data([])
    ->title('Welcome Test')
    ->body('just test')
    ->execute();

Sending FCM Notification using FCM Token

simpleNotifications()
    ->fcm()
    ->token($token)
    ->data([])
    ->title('Welcome Test')
    ->body('just test')
    ->execute();

Available Methods

method	parameter	description
user	Model	notifiable
data	array	notification data
title	string	notification title
body	string	notification message
execute	none	execute send

Change log

Please see the changelog for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Carl Jeffrie Panilag
• All Contributors

License

MIT. Please see the license file for more information.