Notifications: Review of PR to include path path #4629

- Merged book and chapter name items to a single page path list item
  which has links to parent page/chapter.
- Added permission filtering to page path elements.
- Added page path to also be on comment notifications.
- Updated testing to cover.
- Added new Message Line objects to support.

Done during review of #4629

app/Activity/Notifications/MessageParts/EntityLinkMessageLine.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace BookStack\Activity\Notifications\MessageParts;
+
+use BookStack\Entities\Models\Entity;
+use Illuminate\Contracts\Support\Htmlable;
+use Stringable;
+
+/**
+ * A link to a specific entity in the system, with the text showing its name.
+ */
+class EntityLinkMessageLine implements Htmlable, Stringable
+{
+    public function __construct(
+        protected Entity $entity,
+        protected int $nameLength = 120,
+    ) {
+    }
+
+    public function toHtml(): string
+    {
+        return '<a href="' . e($this->entity->getUrl()) . '">' . e($this->entity->getShortName($this->nameLength)) . '</a>';
+    }
+
+    public function __toString(): string
+    {
+        return "{$this->entity->getShortName($this->nameLength)} ({$this->entity->getUrl()})";
+    }
+}

app/Activity/Notifications/MessageParts/EntityPathMessageLine.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace BookStack\Activity\Notifications\MessageParts;
+
+use BookStack\Entities\Models\Entity;
+use Illuminate\Contracts\Support\Htmlable;
+use Stringable;
+
+/**
+ * A link to a specific entity in the system, with the text showing its name.
+ */
+class EntityPathMessageLine implements Htmlable, Stringable
+{
+    /**
+     * @var EntityLinkMessageLine[]
+     */
+    protected array $entityLinks;
+
+    public function __construct(
+        protected array $entities
+    ) {
+        $this->entityLinks = array_map(fn (Entity $entity) => new EntityLinkMessageLine($entity, 24), $this->entities);
+    }
+
+    public function toHtml(): string
+    {
+        $entityHtmls = array_map(fn (EntityLinkMessageLine $line) => $line->toHtml(), $this->entityLinks);
+        return implode(' &gt; ', $entityHtmls);
+    }
+
+    public function __toString(): string
+    {
+        return implode(' > ', $this->entityLinks);
+    }
+}

app/Activity/Notifications/Messages/BaseActivityNotification.php

@@ -3,8 +3,12 @@
 namespace BookStack\Activity\Notifications\Messages;
 
 use BookStack\Activity\Models\Loggable;
+use BookStack\Activity\Notifications\MessageParts\EntityPathMessageLine;
 use BookStack\Activity\Notifications\MessageParts\LinkedMailMessageLine;
 use BookStack\App\MailNotification;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
+use BookStack\Permissions\PermissionApplicator;
 use BookStack\Translation\LocaleDefinition;
 use BookStack\Users\Models\User;
 use Illuminate\Bus\Queueable;
@@ -44,4 +48,20 @@ abstract class BaseActivityNotification extends MailNotification
             $locale->trans('notifications.footer_reason_link'),
         );
     }
+
+    /**
+     * Build a line which provides the book > chapter path to a page.
+     * Takes into account visibility of these parent items.
+     * Returns null if no path items can be used.
+     */
+    protected function buildPagePathLine(Page $page, User $notifiable): ?EntityPathMessageLine
+    {
+        $permissions = new PermissionApplicator($notifiable);
+
+        $path = array_filter([$page->book, $page->chapter], function (?Entity $entity) use ($permissions) {
+            return !is_null($entity) && $permissions->checkOwnableUserAccess($entity, 'view');
+        });
+
+        return empty($path) ? null : new EntityPathMessageLine($path);
+    }
 }

app/Activity/Notifications/Messages/CommentCreationNotification.php

@@ -3,6 +3,7 @@
 namespace BookStack\Activity\Notifications\Messages;
 
 use BookStack\Activity\Models\Comment;
+use BookStack\Activity\Notifications\MessageParts\EntityLinkMessageLine;
 use BookStack\Activity\Notifications\MessageParts\ListMessageLine;
 use BookStack\Entities\Models\Page;
 use BookStack\Users\Models\User;
@@ -19,14 +20,17 @@ class CommentCreationNotification extends BaseActivityNotification
 
         $locale = $notifiable->getLocale();
 
+        $listLines = array_filter([
+            $locale->trans('notifications.detail_page_name') => new EntityLinkMessageLine($page),
+            $locale->trans('notifications.detail_page_path') => $this->buildPagePathLine($page, $notifiable),
+            $locale->trans('notifications.detail_commenter') => $this->user->name,
+            $locale->trans('notifications.detail_comment') => strip_tags($comment->html),
+        ]);
+
         return $this->newMailMessage($locale)
             ->subject($locale->trans('notifications.new_comment_subject', ['pageName' => $page->getShortName()]))
             ->line($locale->trans('notifications.new_comment_intro', ['appName' => setting('app-name')]))
-            ->line(new ListMessageLine([
-                $locale->trans('notifications.detail_page_name') => $page->name,
-                $locale->trans('notifications.detail_commenter') => $this->user->name,
-                $locale->trans('notifications.detail_comment') => strip_tags($comment->html),
-            ]))
+            ->line(new ListMessageLine($listLines))
             ->action($locale->trans('notifications.action_view_comment'), $page->getUrl('#comment' . $comment->local_id))
             ->line($this->buildReasonFooterLine($locale));
     }

app/Activity/Notifications/Messages/PageCreationNotification.php

@@ -2,9 +2,9 @@
 
 namespace BookStack\Activity\Notifications\Messages;
 
+use BookStack\Activity\Notifications\MessageParts\EntityLinkMessageLine;
 use BookStack\Activity\Notifications\MessageParts\ListMessageLine;
 use BookStack\Entities\Models\Page;
-use BookStack\Entities\Models\Chapter;
 use BookStack\Users\Models\User;
 use Illuminate\Notifications\Messages\MailMessage;
 
@@ -14,32 +14,19 @@ class PageCreationNotification extends BaseActivityNotification
     {
         /** @var Page $page */
         $page = $this->detail;
-        $book = $page->book;
-        $chapterId = $page->chapter_id;
-        $chapter = $chapterId ? Chapter::find($chapterId) : null;
 
         $locale = $notifiable->getLocale();
 
-        $listMessageData = [
-            $locale->trans('notifications.detail_page_name') => $page->name,
-            '' => '',
-        ];
-
-        if ($chapter) {
-            $listMessageData += [
-                $locale->trans('notifications.detail_chapter_name') => $chapter->name,
-            ];
-        }
-    
-        $listMessageData += [
-            $locale->trans('notifications.detail_book_name') => $book->name,
+        $listLines = array_filter([
+            $locale->trans('notifications.detail_page_name') => new EntityLinkMessageLine($page),
+            $locale->trans('notifications.detail_page_path') => $this->buildPagePathLine($page, $notifiable),
             $locale->trans('notifications.detail_created_by') => $this->user->name,
-        ];
+        ]);
 
         return $this->newMailMessage($locale)
             ->subject($locale->trans('notifications.new_page_subject', ['pageName' => $page->getShortName()]))
-            ->line($locale->trans('notifications.new_page_intro', ['appName' => setting('app-name')], $locale))
-            ->line(new ListMessageLine($listMessageData))
+            ->line($locale->trans('notifications.new_page_intro', ['appName' => setting('app-name')]))
+            ->line(new ListMessageLine($listLines))
             ->action($locale->trans('notifications.action_view_page'), $page->getUrl())
             ->line($this->buildReasonFooterLine($locale));
     }

app/Activity/Notifications/Messages/PageUpdateNotification.php

@@ -2,9 +2,9 @@
 
 namespace BookStack\Activity\Notifications\Messages;
 
+use BookStack\Activity\Notifications\MessageParts\EntityLinkMessageLine;
 use BookStack\Activity\Notifications\MessageParts\ListMessageLine;
 use BookStack\Entities\Models\Page;
-use BookStack\Entities\Models\Chapter;
 use BookStack\Users\Models\User;
 use Illuminate\Notifications\Messages\MailMessage;
 
@@ -14,32 +14,19 @@ class PageUpdateNotification extends BaseActivityNotification
     {
         /** @var Page $page */
         $page = $this->detail;
-        $book = $page->book;
-        $chapterId = $page->chapter_id;
-        $chapter = $chapterId ? Chapter::find($chapterId) : null;
 
         $locale = $notifiable->getLocale();
 
-        $listMessageData = [
-            $locale->trans('notifications.detail_page_name') => $page->name,
-            '' => '',
-        ];
-    
-        if ($chapter) {
-            $listMessageData += [
-                $locale->trans('notifications.detail_chapter_name') => $chapter->name,
-            ];
-        }
-    
-        $listMessageData += [
-            $locale->trans('notifications.detail_book_name') => $book->name,
+        $listLines = array_filter([
+            $locale->trans('notifications.detail_page_name') => new EntityLinkMessageLine($page),
+            $locale->trans('notifications.detail_page_path') => $this->buildPagePathLine($page, $notifiable),
             $locale->trans('notifications.detail_updated_by') => $this->user->name,
-        ];
+        ]);
 
         return $this->newMailMessage($locale)
             ->subject($locale->trans('notifications.updated_page_subject', ['pageName' => $page->getShortName()]))
             ->line($locale->trans('notifications.updated_page_intro', ['appName' => setting('app-name')]))
-            ->line(new ListMessageLine($listMessageData))
+            ->line(new ListMessageLine($listLines))
             ->line($locale->trans('notifications.updated_page_debounce'))
             ->action($locale->trans('notifications.action_view_page'), $page->getUrl())
             ->line($this->buildReasonFooterLine($locale));