[PLUGINS][RepeatNote] Added documentation (not for ActivityPub related functions)

plugins/RepeatNote/RepeatNote.php

@@ -1,6 +1,6 @@
 <?php
 
-declare(strict_types = 1);
+declare(strict_types=1);
 
 // {{{ License
 // This file is part of GNU social - https://www.gnu.org/software/social
@@ -21,9 +21,9 @@ declare(strict_types = 1);
 
 namespace Plugin\RepeatNote;
 
+use ActivityPhp\Type\AbstractObject;
 use App\Core\DB\DB;
 use App\Core\Event;
-use function App\Core\I18n\_m;
 use App\Core\Modules\NoteHandlerPlugin;
 use App\Core\Router\RouteLoader;
 use App\Core\Router\Router;
@@ -36,18 +36,42 @@ use App\Util\Formatting;
 use Component\Language\Entity\Language;
 use Component\Posting\Posting;
 use DateTime;
+use Plugin\ActivityPub\Entity\ActivitypubActivity;
 use Plugin\RepeatNote\Entity\NoteRepeat;
-use const SORT_REGULAR;
 use Symfony\Component\HttpFoundation\Request;
+use function App\Core\I18n\_m;
+use const SORT_REGULAR;
 
 class RepeatNote extends NoteHandlerPlugin
 {
+    /**
+     * **Repeats a Note**
+     *
+     * This means the current Actor creates a new Note, cloning the contents of
+     * the original Note provided as an argument.
+     *
+     * Bear in mind that, if it's a repeat, the **reply_to** should be to the
+     * original, and **conversation** ought to be the same.
+     *
+     * In the end, the Activity is created, and a new notification for the
+     * repeat Activity created
+     *
+     * @param \App\Entity\Note $note
+     * @param int              $actor_id
+     * @param string           $source
+     *
+     * @return \App\Entity\Activity|null
+     * @throws \App\Util\Exception\BugFoundException
+     * @throws \App\Util\Exception\ClientException
+     * @throws \App\Util\Exception\DuplicateFoundException
+     * @throws \App\Util\Exception\ServerException
+     */
     public static function repeatNote(Note $note, int $actor_id, string $source = 'web'): ?Activity
     {
         $repeat_entity = DB::findBy('note_repeat', [
                 'actor_id' => $actor_id,
                 'note_id' => $note->getId(),
-        ])[0] ?? null;
+            ])[ 0 ] ?? null;
 
         if (!\is_null($repeat_entity)) {
             return null;
@@ -55,7 +79,7 @@ class RepeatNote extends NoteHandlerPlugin
 
         // If it's a repeat, the reply_to should be to the original, conversation ought to be the same
         $og_id = $note->getId();
-        $extra_args['reply_to'] = $og_id;
+        $extra_args[ 'reply_to' ] = $og_id;
 
         // Create a new note with the same content as the original
         $repeat = Posting::storeLocalNote(
@@ -89,9 +113,25 @@ class RepeatNote extends NoteHandlerPlugin
         return $repeat_activity;
     }
 
+    /**
+     * **Undoes a Repeat**
+     *
+     * Removes the Repeat from NoteRepeat table, and the deletes the Note
+     * clone.
+     *
+     * Finally, creates a new Activity, undoing the repeat, and the respective
+     * Notification is handled.
+     *
+     * @param int    $note_id
+     * @param int    $actor_id
+     * @param string $source
+     *
+     * @return \App\Entity\Activity|null
+     * @throws \App\Util\Exception\ServerException
+     */
     public static function unrepeatNote(int $note_id, int $actor_id, string $source = 'web'): ?Activity
     {
-        $already_repeated = DB::findBy(NoteRepeat::class, ['actor_id' => $actor_id, 'repeat_of' => $note_id])[0] ?? null;
+        $already_repeated = DB::findBy(NoteRepeat::class, ['actor_id' => $actor_id, 'repeat_of' => $note_id])[ 0 ] ?? null;
 
         if (!\is_null($already_repeated)) { // If it was repeated, then we can undo it
             // Find previous repeat activity
@@ -100,13 +140,13 @@ class RepeatNote extends NoteHandlerPlugin
                     'verb' => 'repeat',
                     'object_type' => 'note',
                     'object_id' => $already_repeated->getRepeatOf(),
-            ])[0] ?? null;
+                ])[ 0 ] ?? null;
 
             // Remove the clone note
-            DB::findBy(Note::class, ['id' => $already_repeated->getNoteId()])[0]->delete(actor: Actor::getById($actor_id));
+            DB::findBy(Note::class, ['id' => $already_repeated->getNoteId()])[ 0 ]->delete(actor: Actor::getById($actor_id));
 
             // Remove from the note_repeat table
-            DB::remove(DB::findBy(NoteRepeat::class, ['note_id' => $already_repeated->getNoteId()])[0]);
+            DB::remove(DB::findBy(NoteRepeat::class, ['note_id' => $already_repeated->getNoteId()])[ 0 ]);
 
             // Log an activity
             $undo_repeat_activity = Activity::create([
@@ -128,13 +168,13 @@ class RepeatNote extends NoteHandlerPlugin
                     'verb' => 'repeat',
                     'object_type' => 'note',
                     'object_id' => $note_id,
-            ])[0] ?? null)) {
+                ])[ 0 ] ?? null)) {
                 return DB::findBy('activity', [
                         'actor_id' => $actor_id,
                         'verb' => 'undo',
                         'object_type' => 'activity',
                         'object_id' => $already_repeated_activity->getId(),
-                ])[0] ?? null; // null if not undoed
+                    ])[ 0 ] ?? null; // null if not undoed
             } else {
                 // or it's an attempt to undo something that wasn't repeated in the first place,
                 return null;
@@ -142,18 +182,24 @@ class RepeatNote extends NoteHandlerPlugin
         }
     }
 
+
     /**
-     * Filters repeats out of Conversations, and replaces a repeat with the original Note on Actor feed
+     * Filters repeats out of Conversations, and replaces a repeat with the
+     * original Note on Actor feed
+     *
+     * @param \App\Entity\Actor|null                    $actor
+     * @param array                                     $notes
+     * @param \Symfony\Component\HttpFoundation\Request $request
      *
      * @return bool
      */
-    public function onFilterNoteList(?Actor $actor, array &$notes, Request $request)
+    public function onFilterNoteList(?Actor $actor, array &$notes, Request $request): bool
     {
         // Replaces repeat with original note on Actor feed
         // it's pretty cool
         if (str_starts_with($request->get('_route'), 'actor_view_')) {
             $notes = array_map(
-                fn (Note $note) => NoteRepeat::isNoteRepeat($note)
+                fn(Note $note) => NoteRepeat::isNoteRepeat($note)
                     ? Note::getById(NoteRepeat::getByPK($note->getId())->getRepeatOf())
                     : $note,
                 $notes,
@@ -162,14 +208,19 @@ class RepeatNote extends NoteHandlerPlugin
         }
 
         // Filter out repeats altogether
-        $notes = array_filter($notes, fn (Note $note) => !NoteRepeat::isNoteRepeat($note));
+        $notes = array_filter($notes, fn(Note $note) => !NoteRepeat::isNoteRepeat($note));
         return Event::next;
     }
 
+
     /**
      * HTML rendering event that adds the repeat form as a note
      * action, if a user is logged in
      *
+     * @param \Symfony\Component\HttpFoundation\Request $request
+     * @param \App\Entity\Note                          $note
+     * @param array                                     $actions
+     *
      * @return bool                                     Event hook
      */
     public function onAddNoteActions(Request $request, Note $note, array &$actions): bool
@@ -186,7 +237,7 @@ class RepeatNote extends NoteHandlerPlugin
         ])) !== [] ? 1 : 0;
 
         // Generating URL for repeat action route
-        $args              = ['note_id' => $is_repeat === 0 ? $note->getId() : $note_repeat[0]->getRepeatOf()];
+        $args = ['note_id' => $is_repeat === 0 ? $note->getId() : $note_repeat[ 0 ]->getRepeatOf()];
         $type = Router::ABSOLUTE_PATH;
         $repeat_action_url = $is_repeat
             ? Router::url('repeat_remove', $args, $type)
@@ -207,8 +258,14 @@ class RepeatNote extends NoteHandlerPlugin
         return Event::next;
     }
 
+
     /**
-     * Append on note information about user actions.
+     * Appends in Note information stating who and what user actions were
+     * performed.
+     *
+     * @param array $vars   Contains the Note currently being rendered
+     * @param array $result Rendered String containing anchors for Actors that
+     *                      repeated the Note
      *
      * @return array|bool
      */
@@ -218,7 +275,7 @@ class RepeatNote extends NoteHandlerPlugin
         // if user is the one who repeated, append on end "you repeated this, remove repeat?"
         $check_user = !\is_null(Common::user());
 
-        $note = $vars['note'];
+        $note = $vars[ 'note' ];
 
         $complementary_info = '';
         $repeat_actor = [];
@@ -263,6 +320,20 @@ class RepeatNote extends NoteHandlerPlugin
         return $result;
     }
 
+    /**
+     * Connects the following Routes to their respective Controllers:
+     *
+     * - **repeat_add**
+     *  page containing the Note the user wishes to Repeat and a button to
+     *  confirm it wishes to perform the action
+     *
+     * - **repeat_remove**
+     *  same as above, except that it undoes the aforementioned action
+     *
+     * @param \App\Core\Router\RouteLoader $r
+     *
+     * @return bool Event hook
+     */
     public function onAddRoute(RouteLoader $r): bool
     {
         // Add/remove note to/from repeats
@@ -272,15 +343,36 @@ class RepeatNote extends NoteHandlerPlugin
         return Event::next;
     }
 
-    // ActivityPub
+    /*
+     * ActivityPub handling and processing for Repeat start
+     */
 
-    private function activitypub_handler(Actor $actor, \ActivityPhp\Type\AbstractObject $type_activity, mixed $type_object, ?\Plugin\ActivityPub\Entity\ActivitypubActivity &$ap_act): bool
+    /**
+     * Handler for the Repeat Activity
+     *
+     * @param \App\Entity\Actor                                   $actor
+     * @param \ActivityPhp\Type\AbstractObject                    $type_activity
+     * @param mixed                                               $type_object
+     * @param \Plugin\ActivityPub\Entity\ActivitypubActivity|null $ap_act
+     *
+     * @return bool
+     * @throws \App\Util\Exception\BugFoundException
+     * @throws \App\Util\Exception\ClientException
+     * @throws \App\Util\Exception\DuplicateFoundException
+     * @throws \App\Util\Exception\NoSuchActorException
+     * @throws \App\Util\Exception\ServerException
+     * @throws \Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\RedirectionExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\ServerExceptionInterface
+     * @throws \Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface
+     */
+    private function activitypub_handler(Actor $actor, AbstractObject $type_activity, mixed $type_object, ?ActivitypubActivity &$ap_act): bool
     {
         if (!\in_array($type_activity->get('type'), ['Announce', 'Undo'])) {
             return Event::next;
         }
         if ($type_activity->get('type') === 'Announce') { // Repeat
-            if ($type_object instanceof \ActivityPhp\Type\AbstractObject) {
+            if ($type_object instanceof AbstractObject) {
                 if ($type_object->get('type') === 'Note') {
                     $note = \Plugin\ActivityPub\Util\Model\Note::fromJson($type_object);
                     $note_id = $note->getId();
@@ -294,7 +386,7 @@ class RepeatNote extends NoteHandlerPlugin
                 return Event::next;
             }
         } else { // Undo Repeat
-            if ($type_object instanceof \ActivityPhp\Type\AbstractObject) {
+            if ($type_object instanceof AbstractObject) {
                 $ap_prev_repeat_act = \Plugin\ActivityPub\Util\Model\Activity::fromJson($type_object);
                 $prev_repeat_act = $ap_prev_repeat_act->getActivity();
                 if ($prev_repeat_act->getVerb() === 'repeat' && $prev_repeat_act->getObjectType() === 'note') {
@@ -320,7 +412,7 @@ class RepeatNote extends NoteHandlerPlugin
         }
         if (!\is_null($activity)) {
             // Store ActivityPub Activity
-            $ap_act = \Plugin\ActivityPub\Entity\ActivitypubActivity::create([
+            $ap_act = ActivitypubActivity::create([
                 'activity_id' => $activity->getId(),
                 'activity_uri' => $type_activity->get('id'),
                 'created' => new DateTime($type_activity->get('published') ?? 'now'),
@@ -331,12 +423,12 @@ class RepeatNote extends NoteHandlerPlugin
         return Event::stop;
     }
 
-    public function onNewActivityPubActivity(Actor $actor, \ActivityPhp\Type\AbstractObject $type_activity, \ActivityPhp\Type\AbstractObject $type_object, ?\Plugin\ActivityPub\Entity\ActivitypubActivity &$ap_act): bool
+    public function onNewActivityPubActivity(Actor $actor, AbstractObject $type_activity, AbstractObject $type_object, ?ActivitypubActivity &$ap_act): bool
     {
         return $this->activitypub_handler($actor, $type_activity, $type_object, $ap_act);
     }
 
-    public function onNewActivityPubActivityWithObject(Actor $actor, \ActivityPhp\Type\AbstractObject $type_activity, mixed $type_object, ?\Plugin\ActivityPub\Entity\ActivitypubActivity &$ap_act): bool
+    public function onNewActivityPubActivityWithObject(Actor $actor, AbstractObject $type_activity, mixed $type_object, ?ActivitypubActivity &$ap_act): bool
     {
         return $this->activitypub_handler($actor, $type_activity, $type_object, $ap_act);
     }