[COMPONENTS][Conversation] Documented respective Controller

[PLUGINS][TreeNotes] Documentation added, feedFormatTree explained in detail

components/Conversation/Controller/Conversation.php

@@ -40,14 +40,19 @@ use Symfony\Component\HttpFoundation\Request;
 class Conversation extends FeedController
 {
     /**
-     * Render conversation page
+     * Render conversation page.
      *
-     * @return array
+     * @param int $conversation_id To identify what Conversation is to be rendered
+     *
+     * @throws \App\Util\Exception\ServerException
+     *
+     * @return array Array containing keys: 'notes' (all known notes in the given Conversation), 'should_format' (boolean, stating if onFormatNoteList events may or not format given notes), 'page_title' (used as the title header)
      */
-    public function showConversation(Request $request, int $conversation_id)
+    public function showConversation(Request $request, int $conversation_id): array
     {
         $data  = $this->query(query: "note-conversation:{$conversation_id}");
         $notes = $data['notes'];
+
         return [
             '_template'     => 'collection/notes.html.twig',
             'notes'         => $notes,
@@ -56,7 +61,18 @@ class Conversation extends FeedController
         ];
     }
 
-    public function muteConversation(Request $request, int $conversation_id)
+    /**
+     * Creates form view for Muting Conversation extra action.
+     *
+     * @param int $conversation_id The Conversation id that this action targets
+     *
+     * @throws \App\Util\Exception\NoLoggedInUser
+     * @throws \App\Util\Exception\RedirectException
+     * @throws \App\Util\Exception\ServerException
+     *
+     * @return array Array containing templating where the form is to be rendered, and the form itself
+     */
+    public function muteConversation(Request $request, int $conversation_id): array
     {
         $user = Common::ensureLoggedIn();
         $form = Form::create([

plugins/TreeNotes/TreeNotes.php

@@ -27,68 +27,78 @@ use Symfony\Component\HttpFoundation\Request;
 
 class TreeNotes extends Plugin
 {
-
     /**
      * Formatting notes without taking a direct reply out of context
-     * Show whole conversation in conversation related routes
+     * Show whole conversation in conversation related routes.
-     *
-     * @param array                                     $notes_in
-     * @param array                                     $notes_out
-     * @param \Symfony\Component\HttpFoundation\Request $request
-     *
-     * @return void
      */
     public function onFormatNoteList(array $notes_in, array &$notes_out, Request $request)
     {
         if (str_starts_with($request->get('_route'), 'conversation')) {
-            $parents = $this->conversationFormat($notes_in);
+            $parents   = $this->conversationFormat($notes_in);
             $notes_out = $this->conversationFormatTree($parents, $notes_in);
         } else {
             $notes_out = $this->feedFormatTree($notes_in);
         }
     }
 
+    /**
+     * Formats general Feed view, allowing users to see a Note and its direct replies.
+     * These replies are then, shown independently of parent note, making sure that every single Note is shown at least once to users.
+     *
+     * The list is transversed in reverse to prevent any parent Note from being processed twice. At the same time, this allows all direct replies to be rendered inside the same, respective, parent Note.
+     * Moreover, this implies the Entity\Note::getReplies() query will only be performed once, for every Note.
+     *
+     * @param array $notes The Note list to be formatted, each element has two keys: 'note' (parent/current note), and 'replies' (array of notes in the same format)
+     */
     private function feedFormatTree(array $notes): array
     {
-        $tree = [];
+        $tree  = [];
         $notes = array_reverse($notes);
         foreach ($notes as $note) {
-            if (!is_null($children = $note->getReplies())) {
+            if (!\is_null($children = $note->getReplies())) {
-                $notes = array_filter($notes, fn (Note $n) => !in_array($n, $children));
+                $notes = array_filter($notes, fn (Note $n) => !\in_array($n, $children));
 
                 $tree[] = [
-                    'note' => $note,
+                    'note'      => $note,
-                    'replies' => array_map(
+                    'replies'   => array_map(
-                        function ($n) {
+                        fn ($n) => ['note' => $n, 'replies' => []],
-                            return ['note' => $n, 'replies' => []];
+                        $children,
-                        },
-                        $children
                     ),
                 ];
             } else {
                 $tree[] = ['note' => $note, 'replies' => []];
             }
         }
+
         return array_reverse($tree);
     }
 
-    private function conversationFormat(array $notes_in)
+    /**
+     * Filters given Note list off any children, returning only initial Notes of a Conversation.
+     *
+     * @param array $notes_in Notes to be filtered
+     *
+     * @return array All initial Conversation Notes in given list
+     */
+    private function conversationFormat(array $notes_in): array
     {
         return array_filter($notes_in, static fn (Note $note) => \is_null($note->getReplyTo()));
     }
 
-    private function conversationFormatTree(array $parents, array $notes)
+    private function conversationFormatTree(array $parents, array $notes): array
     {
         $subtree = [];
         foreach ($parents as $p) {
             $subtree[] = $this->conversationFormatSubTree($p, $notes);
         }
+
         return $subtree;
     }
 
     private function conversationFormatSubTree(Note $parent, array $notes)
     {
         $children = array_filter($notes, fn (Note $note) => $note->getReplyTo() === $parent->getId());
+
         return ['note' => $parent, 'replies' => $this->conversationFormatTree($children, $notes)];
     }
 }