BookStack Favourite Change Notification

README.md

BookStack Favourite Change Notification

This guide will show you how to setup BookStack to send an email notification, when an entity changes, to anyone who marked the entity as a favourite.

Installation

Create the files below in your bookstack/themes/custom/ folder.

The favourite_notification.php must be in the folder `themes/custom/resources/lang/en/'. Add other languages as needed.

Add the theme to your .env file:

APP_THEME=custom

Add the namespace to your composer.json autoload section:

{
    "autoload": {
        "psr-4": {
            "Custom\\": "themes/custom/"
        }
    }
}

Finally run composer update to generate the autoload.php.

Usage

1. Favourite an entity (shelf, book, chapter, page)
2. Edit the entity, then save
3. An email will be sent

Reources

• Hacking BookStack
• BookStack theme documentation

Thanks To

This code was sponsored by Aussie Broadband: Australia's Leading nbn™ Internet Provider

favourite_notification.php

<?php
/**
 * Favourite Alert text strings.
 * Is used for all the text within favourite alerts.
 */
return [
    // Emails
    'email_subject' => 'Favourite Notification for :changeType to :entityName',
    'email_greeting' => ':entityName had :changeType on :appName.',
    'email_text' => 'Click the button below to view the :entityType.',
    'email_action' => 'View :entityType',
];

FavouriteNotification.php

<?php

namespace Custom;

use BookStack\Auth\User;
use BookStack\Entities\Models\Entity;
use BookStack\Notifications\MailNotification;
use Illuminate\Notifications\Messages\MailMessage;

class FavouriteNotification extends MailNotification
{
    private string $type;
    private Entity $entity;

    public function __construct(string $type, Entity $entity)
    {
        $this->type = $type;
        $this->entity = $entity;
    }

    /**
     * Get the mail representation of the notification.
     */
    public function toMail(User $notifiable): MailMessage
    {
        $language = setting()->getUser($notifiable, 'language');

        $replace = [
            'appName' => setting('app-name'),
            'entityName' => $this->entity->name,
            'entityType' => class_basename($this->entity),
            'changeType' => $this->type,
        ];

        return $this->newMailMessage()
            ->subject(trans('custom::favourite_notification.email_subject', $replace, $language))
            ->greeting(trans('custom::favourite_notification.email_greeting', $replace, $language))
            ->line(trans('custom::favourite_notification.email_text', $replace, $language))
            ->action(trans('custom::favourite_notification.email_action', $replace, $language), $this->entity->getUrl());
    }
}

functions.php

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use Custom\SendFavouriteNotification;
use Illuminate\Support\Facades\Lang;

Theme::listen(ThemeEvents::APP_BOOT, function ($app) {
    Lang::addNamespace('custom', __DIR__ . '/resources/lang');
});

Theme::listen(ThemeEvents::ACTIVITY_LOGGED, function ($type, $detail) {
    SendFavouriteNotification::dispatch($type, $detail);
});

SendFavouriteNotification.php

<?php

namespace Custom;

use Custom\FavouriteNotification;
use BookStack\Actions\Favourite;
use BookStack\Auth\User;
use BookStack\Entities\Models\Entity;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Support\Facades\Notification;

class SendFavouriteNotification
{
    use Dispatchable;

    private string $type;
    private mixed $detail;

    public function __construct($type, $detail)
    {
        $this->type = $type;
        $this->detail = $detail;
    }

    public function handle(): void
    {
        if ($this->detail instanceof Entity) {
            $users = $this->detail->favourites->map(function (Favourite $favourite) {
                return User::find($favourite->user_id);
            });
            if ($users->count()) {
                Notification::send($users, new FavouriteNotification($this->type, $this->detail));
            }
        }
    }
}

Can't get this working under 22.11 and 23.01. Every action using BookStack is commented with "An unknown error occurred" until I remove/rename themes/custom/function.php. No mail is generated. No entry in webservers error.log.

Hey @rseffner,

Thanks for the feedback. I just tried this and I can replicate the error. The log is in www/storage/logs/laravel.log, and looks like this:

[2023-02-16 22:37:49] production.ERROR: Class "Custom\SendFavouriteNotification" not found {"userId":1,"exception":"[object] (Error(code: 0): Class \"Custom\\SendFavouriteNotification\" not found at /config/www/themes/custom/functions.php:13)

The problem (at least in my test) is that the line was added to composer.json but composer update was not run. I'll update the instructions to include this.

Would it be possible to include the user which initiated the event?

Something like:

Favourite Notification for :changeType to :entityName by :userName

In 23.08 I'm getting this error message:

production.ERROR: Custom\SendFavouriteNotification::Custom{closure}(): Argument #1 ($favourite) must be of type BookStack\Actions\Favourite, BookStack\Activity\Models\Favourite given {"userId":3,"exception":"[object] (TypeError(code: 0): Custom\SendFavouriteNotification::Custom\{closure}(): Argument #1 ($favourite) must be of type BookStack\Actions\Favourite, BookStack\Activity\Models\Favourite given at /config/www/themes/custom/SendFavouriteNotification.php:28)

In my opinion this extension is deprecated through the new built in notification system introduced with BookStack v23.08:

Release v23.08
#4390, #4371, #241