sfneal/post-office

Email suite for Laravel applications with extended Mailable & Notification functionality

2.2.0 2024-04-23 18:22 UTC

Requires

• php: ^8.0|^8.1|^8.2|^8.3
• laravel/framework: ^8.75|^9.0|^10.0
• sfneal/queueables: ^2.0

Requires (Dev)

• orchestra/testbench: ^7.40|^8.0|9.0
• phpunit/phpunit: ^9.6|^10.0|^11.0
• scrutinizer/ocular: ^1.8
• sfneal/mock-models: ^0.5.0 || ^0.11.0
• sfneal/users: ^1.0|^2.0

MIT

• Stephen Neal

• post-office
• sfneal

README

Email suite for Laravel applications with extended Mailable & Notification functionality

Installation

You can install the package via composer:

composer require sfneal/post-office

To modify the post-office config file & views, publish the ServiceProvider with the following command.

php artisan vendor:publish --provider="Sfneal\PostOffice\Providers\PostOfficeServiceProvider"

Usage

Creating a Mailable & sending it using the SendMail job.

First create a Mailable extension & implement applicable mailable interfaces.

use Sfneal\PostOffice\Mailables\Interfaces\CallToAction;
use Sfneal\PostOffice\Mailables\Interfaces\Email;
use Sfneal\PostOffice\Mailables\Interfaces\Greeting;
use Sfneal\PostOffice\Mailables\Interfaces\Message;
use Sfneal\PostOffice\Mailables\Interfaces\Title;
use Sfneal\PostOffice\Mailables\Mailable;
use Sfneal\PostOffice\Mailables\Traits\UserMailable;
use Sfneal\Users\Models\User;

class InvoiceUnpaidMailable extends Mailable implements Greeting, Email, Title, Message, CallToAction
{
    /**
     * @var User
     */
    private $user;

    /**
     * @var int
     */
    private $invoice_id;

    /**
     * InvoicePaidMailable constructor.
     *
     * @param User $user
     * @param int $invoice_id
     */
    public function __construct(User $user, int $invoice_id)
    {
        $this->user = $user;
        $this->invoice_id = $invoice_id;
        parent::__construct(
            $this->getGreeting(),
            $this->getEmail(),
            $this->getTitle(),
            $this->getMessages(),
            $this->getCallToAction()
        );
    }
    
    /**
     * @return string First line of email
     */
    public function getGreeting(): string
    {
        return "Hi {$this->user->first_name}";
    }

    /**
     * Email recipient.
     *
     * @return string
     */
    public function getEmail(): string
    {
        return $this->user->email;
    }

    /**
     * Retrieve the Mailable's subject/title.
     *
     * @return string
     */
    public function getTitle(): string
    {
        return "Unpaid Invoice: #{$this->invoice_id}";
    }

    /**
     * Retrieve an array of messages to include in a mailable.
     *
     * @return array
     */
    public function getMessages(): array
    {
        return [
            'You have one or more unpaid invoices.  Please send use money asap!',
            "If your invoice is not paid within 30 days we're going to send a team of ninja's to your last known location.",
        ];
    }

    /**
     * Call to Action button in the body of the email.
     *
     * @return array
     */
    public function getCallToAction(): array
    {
        return [
            'url' => 'https://google.com',
            'text' => 'Pay Invoice',
        ];
    }
}

Next, instantiate your Mailable & pass it as the $mailable parameter to the SendMail job. SendMail can be dispatched to the Job queue or executed synchronously.

$mailable = new InvoiceUnpaidMailable($user, $invoice_id);

// Dispatch SendMail job to the queue
SendMail::dispatch($user->email, $mailable);

// Execute the SendMail synchronously
SendMail::dispatchSync($user->email, $mailable);

// Execute the SendMail synchronously without using Queueable static methods
$sent = (new SendMail($user->email, $mailable))->handle();

Creating a Notification & sending it using the Notification facade

First create a Notification extension that defines your notification.

use Sfneal\PostOffice\Notifications\Notification;
use Sfneal\Users\Models\User;

class InvoiceUnpaidNotification extends Notification
{
    /**
     * @var User
     */
    public $user;

    /**
     * @var int
     */
    public $invoice_id;

    /**
     * InvoicePaidMailable constructor.
     *
     * @param User $user
     * @param int $invoice_id
     */
    public function __construct(User $user, int $invoice_id)
    {
        $this->user = $user;
        $this->invoice_id = $invoice_id;
        parent::__construct();
    }

    /**
     * Get the mail representation of the notification.
     *
     * @param mixed $notifiable
     * @return InvoiceUnpaidMailable
     */
    public function toMail($notifiable): InvoiceUnpaidMailable
    {
        return (new InvoiceUnpaidMailable($this->user, $this->invoice_id))->to($notifiable->email);
    }

    /**
     * Get the array representation of the notification.
     *
     * @param mixed $notifiable
     * @return array
     */
    public function toArray($notifiable): array
    {
        return [
            'user_id' => $this->user->getKey(),
            'invoice_id' => $this->invoice_id,
        ];
    }
}

Send the Notification using either the send() or sendNow() methods.

$notification = new InvoiceUnpaidNotification($user, $invoice_id);

// Send using the Job queue
$notification->send($user);

// Send synchronously
$notification->sendNow($user);

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

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

Credits

• Stephen Neal
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

PHP Package Boilerplate

This package was generated using the PHP Package Boilerplate.