Add some missing documentation to ActivityPub

plugins/ActivityPub/lib/activitypubqueuehandler.php

@@ -18,19 +18,19 @@
  * ActivityPub queue handler for notice distribution
  *
  * @package   GNUsocial
+ *
  * @author    Bruno Casteleiro <brunoccast@fc.up.pt>
  * @author    Diogo Cordeiro <diogo@fc.up.pt>
  * @copyright 2019-2020 Free Software Foundation, Inc http://www.fsf.org
  * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
  */
-
 defined('GNUSOCIAL') || die();
 
 /**
  * @copyright 2019-2020 Free Software Foundation, Inc http://www.fsf.org
  * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
  */
-class ActivityPubQueueHandler extends QueueHandler
+class activitypubqueuehandler extends QueueHandler
 {
     /**
      * Getter of the queue transport name.
@@ -46,10 +46,13 @@ class ActivityPubQueueHandler extends QueueHandler
      * Notice distribution handler.
      *
      * @param Notice $notice notice to be distributed.
-     * @return bool true on success, false otherwise
+     *
      * @throws HTTP_Request2_Exception
      * @throws InvalidUrlException
      * @throws ServerException
+     *
+     * @return bool true on success, false otherwise
+     *
      * @author Diogo Cordeiro <diogo@fc.up.pt>
      */
     public function handle($notice): bool
@@ -97,6 +100,13 @@ class ActivityPubQueueHandler extends QueueHandler
         return true;
     }
 
+    /**
+     * Handle notice creation and propagation
+     *
+     * @param mixed $profile
+     * @param mixed $notice
+     * @param mixed $other
+     */
     private function handle_create($profile, $notice, $other)
     {
         // Handling a reply?
@@ -166,10 +176,14 @@ class ActivityPubQueueHandler extends QueueHandler
      * Notify remote users when their notices get favourited.
      *
      * @param Profile $profile of local user doing the faving
-     * @param Notice $notice_liked Notice being favored
+     * @param Notice  $notice  Notice being favored
-     * @return bool return value
+     * @param mixed   $other
+     *
      * @throws HTTP_Request2_Exception
      * @throws InvalidUrlException
+     *
+     * @return bool return value
+     *
      * @author Diogo Cordeiro <diogo@fc.up.pt>
      */
     public function onEndFavorNotice(Profile $profile, Notice $notice, $other)
@@ -205,14 +219,65 @@ class ActivityPubQueueHandler extends QueueHandler
         return true;
     }
 
+    /**
+     * Notify remote users when their notices get de-favourited.
+     *
+     * @param Profile $profile of local user doing the de-faving
+     * @param Notice  $notice  Notice being favored
+     * @param mixed   $other
+     *
+     * @throws HTTP_Request2_Exception
+     * @throws InvalidUrlException
+     *
+     * @return bool return value
+     *
+     * @author Diogo Cordeiro <diogo@fc.up.pt>
+     */
+    public function onEndDisfavorNotice(Profile $profile, Notice $notice, $other)
+    {
+        if ($notice->reply_to) {
+            try {
+                $parent_notice = $notice->getParent();
+
+                try {
+                    $other[] = Activitypub_profile::from_profile($parent_notice->getProfile());
+                } catch (Exception $e) {
+                    // Local user can be ignored
+                }
+
+                $other = array_merge(
+                    $other,
+                    Activitypub_profile::from_profile_collection(
+                        $parent_notice->getAttentionProfiles()
+                    )
+                );
+            } catch (NoParentNoticeException $e) {
+                // This is not a reply to something (has no parent)
+            } catch (NoResultException $e) {
+                // Parent author's profile not found! Complain louder?
+                common_log(LOG_ERR, "Parent notice's author not found: " . $e->getMessage());
+            }
+        }
+
+        $postman = new Activitypub_postman($profile, $other);
+        $postman->undo_like($notice);
+
+        return true;
+    }
+
     /**
      * Notify remote users when their notices get deleted
      *
      * @param $user
      * @param $notice
-     * @return bool hook flag
+     * @param mixed $profile
+     * @param mixed $other
+     *
      * @throws HTTP_Request2_Exception
      * @throws InvalidUrlException
+     *
+     * @return bool hook flag
+     *
      * @author Diogo Cordeiro <diogo@fc.up.pt>
      */
     public function onStartDeleteOwnNotice($profile, $notice, $other)

plugins/ActivityPub/lib/discoveryhints.php

@@ -18,6 +18,7 @@
  * ActivityPub implementation for GNU social
  *
  * @package   GNUsocial
+ *
  * @author    Evan Prodromou
  * @author    Brion Vibber
  * @author    James Walker
@@ -26,13 +27,16 @@
  * @author    Diogo Cordeiro
  * @copyright 2010-2019 Free Software Foundation, Inc http://www.fsf.org
  * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
- * @link      http://www.gnu.org/software/social/
+ *
+ * @see      http://www.gnu.org/software/social/
  */
-
 defined('GNUSOCIAL') || die();
 
-class DiscoveryHints
+class discoveryhints
 {
+    /**
+     * Find discovery hints in XML XRD (Extensible Resource Descriptor)
+     */
     public static function fromXRD(XML_XRD $xrd)
     {
         $hints = [];
@@ -74,16 +78,23 @@ class DiscoveryHints
             }
         } catch (HTTP_Request2_Exception $e) {
             // Any HTTPClient error that might've been thrown
-            common_log(LOG_ERR, __METHOD__ . ':'.$e->getMessage());
+            common_log(LOG_ERR, __METHOD__ . ':' . $e->getMessage());
             return null;
         }
 
         return self::hcardHints(
             $response->getBody(),
             $response->getEffectiveUrl()
+
         );
     }
 
+    /**
+     * ??????
+     *
+     * @param mixed $body
+     * @param mixed $url
+     */
     public static function hcardHints($body, $url)
     {
         $hcard = self::_hcard($body, $url);
@@ -123,6 +134,12 @@ class DiscoveryHints
         return $hints;
     }
 
+    /**
+     * ?????????
+     *
+     * @param mixed $body
+     * @param mixed $url
+     */
     public static function _hcard($body, $url)
     {
         $mf2 = new Mf2\Parser($body, $url);

plugins/ActivityPub/scripts/fix_subscriptions.php

@@ -19,16 +19,16 @@
  * ActivityPub implementation for GNU social
  *
  * @package   GNUsocial
+ *
  * @author    Diogo Cordeiro <diogo@fc.up.pt>
  * @copyright 2018-2019 Free Software Foundation, Inc http://www.fsf.org
  * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
  */
-
 define('INSTALLDIR', dirname(__DIR__, 3));
 define('PUBLICDIR', INSTALLDIR . DIRECTORY_SEPARATOR . 'public');
 
 $shortoptions = 'i:af';
-$longoptions = ['id=', 'all', 'force'];
+$longoptions  = ['id=', 'all', 'force'];
 
 $helptext = <<<END_OF_HELP
 fix_subsriptions.php [options]
@@ -39,10 +39,10 @@ For every ActivityPub subscription, re-send Follow activity.
 
 END_OF_HELP;
 
-require_once INSTALLDIR.'/scripts/commandline.inc';
+require_once INSTALLDIR . '/scripts/commandline.inc';
 
 if (have_option('i', 'id')) {
-    $id = get_option_value('i', 'id');
+    $id   = get_option_value('i', 'id');
     $user = User::getByID($id);
     fix_subscriptions($user->getProfile());
     exit(0);
@@ -52,7 +52,7 @@ if (have_option('i', 'id')) {
 }
 
 $user = new User();
-$cnt = $user->find();
+$cnt  = $user->find();
 while ($user->fetch()) {
     fix_subscriptions($user->getProfile());
 }
@@ -61,11 +61,14 @@ unset($user);
 
 printfnq("Done.\n");
 
+/**
+ * Validate and fix the `subscription` table
+ */
 function fix_subscriptions(Profile $profile)
 {
     // Collect every remote AP subscription
-    $aprofiles = [];
+    $aprofiles      = [];
-    $subs = Subscription::getSubscribedIDs($profile->getID(), 0, null);
+    $subs           = Subscription::getSubscribedIDs($profile->getID(), 0, null);
     $subs_aprofiles = Activitypub_profile::multiGet('profile_id', $subs);
     foreach ($subs_aprofiles->fetchAll() as $ap) {
         $aprofiles[$ap->getID()] = $ap;