Refactor notification system to use action hooks instead

.github/changelog/2223-from-description

@@ -0,0 +1,4 @@
+Significance: minor
+Type: changed
+
+Standardized notification handling with new hooks for better extensibility and consistency.

includes/class-notification.php

@@ -9,6 +9,8 @@
 
 /**
  * Notification class.
+ *
+ * @deprecated unreleased Use action hooks like 'activitypub_handled_{type}' instead.
  */
 class Notification {
 	/**
@@ -48,6 +50,8 @@ class Notification {
 	 * @param int    $target   The WordPress User-Id.
 	 */
 	public function __construct( $type, $actor, $activity, $target ) {
+		\_deprecated_class( __CLASS__, 'unreleased', 'Use action hooks like "activitypub_handled_{type}" instead.' );
+
 		$this->type   = $type;
 		$this->actor  = $actor;
 		$this->object = $activity;
@@ -60,18 +64,7 @@ public function __construct( $type, $actor, $activity, $target ) {
 	public function send() {
 		$type = \strtolower( $this->type );
 
-		/**
-		 * Action to send ActivityPub notifications.
-		 *
-		 * @param Notification $instance The notification object.
-		 */
-		do_action( 'activitypub_notification', $this );
-
-		/**
-		 * Type-specific action to send ActivityPub notifications.
-		 *
-		 * @param Notification $instance The notification object.
-		 */
-		do_action( "activitypub_notification_{$type}", $this );
+		\do_action_deprecated( 'activitypub_notification', array( $this ), 'unreleased', "activitypub_handled_{$type}" );
+		\do_action_deprecated( "activitypub_notification_{$type}", array( $this ), 'unreleased', "activitypub_handled_{$type}" );
 	}
 }

includes/handler/class-accept.php

@@ -10,7 +10,6 @@
 use Activitypub\Collection\Following;
 use Activitypub\Collection\Outbox;
 use Activitypub\Collection\Remote_Actors;
-use Activitypub\Notification;
 
 use function Activitypub\object_to_uri;
 
@@ -22,19 +21,8 @@ class Accept {
 	 * Initialize the class, registering WordPress hooks.
 	 */
 	public static function init() {
-		\add_action(
-			'activitypub_inbox_accept',
-			array( self::class, 'handle_accept' ),
-			10,
-			2
-		);
-
-		\add_filter(
-			'activitypub_validate_object',
-			array( self::class, 'validate_object' ),
-			10,
-			3
-		);
+		\add_action( 'activitypub_inbox_accept', array( self::class, 'handle_accept' ), 10, 2 );
+		\add_filter( 'activitypub_validate_object', array( self::class, 'validate_object' ), 10, 3 );
 	}
 
 	/**
@@ -60,16 +48,18 @@ public static function handle_accept( $accept, $user_id ) {
 			return;
 		}
 
-		Following::accept( $actor_post, $user_id );
-
-		// Send notification.
-		$notification = new Notification(
-			'accept',
-			$actor_post->guid,
-			$accept,
-			$user_id
-		);
-		$notification->send();
+		$reaction = Following::accept( $actor_post, $user_id );
+		$success  = ! \is_wp_error( $reaction );
+
+		/**
+		 * Fires after an ActivityPub Accept activity has been handled.
+		 *
+		 * @param array      $accept   The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param bool       $success  Whether the follow request was accepted successfully.
+		 * @param mixed      $reaction The result of accepting the follow request (contextual object).
+		 */
+		\do_action( 'activitypub_handled_accept', $accept, $user_id, $success, $reaction );
 	}
 
 	/**

includes/handler/class-announce.php

@@ -23,12 +23,7 @@ class Announce {
 	 * Initialize the class, registering WordPress hooks.
 	 */
 	public static function init() {
-		\add_action(
-			'activitypub_inbox_announce',
-			array( self::class, 'handle_announce' ),
-			10,
-			3
-		);
+		\add_action( 'activitypub_inbox_announce', array( self::class, 'handle_announce' ), 10, 3 );
 	}
 
 	/**
@@ -114,13 +109,13 @@ public static function maybe_save_announce( $activity, $user_id ) {
 		}
 
 		/**
-		 * Fires after an Announce has been saved.
+		 * Fires after an ActivityPub Announce activity has been handled.
 		 *
-		 * @param array $activity The activity-object.
-		 * @param int   $user_id  The id of the local blog-user.
-		 * @param mixed $state    The state of the reaction.
-		 * @param mixed $reaction The reaction.
+		 * @param array      $activity The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param mixed      $state    The state/result of the operation (e.g., comment ID, WP_Error, or status).
+		 * @param mixed|null $reaction The WP_Comment object of the created announce/repost comment, or null if creation failed.
 		 */
-		do_action( 'activitypub_handled_announce', $activity, $user_id, $state, $reaction );
+		\do_action( 'activitypub_handled_announce', $activity, $user_id, $state, $reaction );
 	}
 }

includes/handler/class-create.php

@@ -22,19 +22,8 @@ class Create {
 	 * Initialize the class, registering WordPress hooks.
 	 */
 	public static function init() {
-		\add_action(
-			'activitypub_inbox_create',
-			array( self::class, 'handle_create' ),
-			10,
-			3
-		);
-
-		\add_filter(
-			'activitypub_validate_object',
-			array( self::class, 'validate_object' ),
-			10,
-			3
-		);
+		\add_action( 'activitypub_inbox_create', array( self::class, 'handle_create' ), 10, 3 );
+		\add_filter( 'activitypub_validate_object', array( self::class, 'validate_object' ), 10, 3 );
 	}
 
 	/**
@@ -80,12 +69,12 @@ public static function handle_create( $activity, $user_id, $activity_object = nu
 		}
 
 		/**
-		 * Fires after a Create activity has been handled.
+		 * Fires after an ActivityPub Create activity has been handled.
 		 *
-		 * @param array                      $activity The activity-object.
-		 * @param int                        $user_id  The id of the local blog-user.
-		 * @param \WP_Comment|\WP_Error      $state    The comment object or WP_Error.
-		 * @param \WP_Comment|\WP_Error|null $reaction The reaction object or WP_Error.
+		 * @param array      $activity The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param mixed      $state    The state/result of the operation (e.g., comment ID, WP_Error, or status).
+		 * @param mixed|null $reaction The WP_Comment object of the created comment, or null if creation failed.
 		 */
 		\do_action( 'activitypub_handled_create', $activity, $user_id, $state, $reaction );
 	}

includes/handler/class-delete.php

@@ -21,7 +21,7 @@ class Delete {
 	 * Initialize the class, registering WordPress hooks.
 	 */
 	public static function init() {
-		\add_action( 'activitypub_inbox_delete', array( self::class, 'handle_delete' ) );
+		\add_action( 'activitypub_inbox_delete', array( self::class, 'handle_delete' ), 10, 2 );
 		\add_filter( 'activitypub_defer_signature_verification', array( self::class, 'defer_signature_verification' ), 10, 2 );
 		\add_action( 'activitypub_delete_actor_interactions', array( self::class, 'delete_interactions' ) );
 
@@ -33,9 +33,12 @@ public static function init() {
 	 * Handles "Delete" requests.
 	 *
 	 * @param array $activity The delete activity.
+	 * @param int   $user_id  The local user ID.
 	 */
-	public static function handle_delete( $activity ) {
+	public static function handle_delete( $activity, $user_id ) {
 		$object_type = $activity['object']['type'] ?? '';
+		$state       = null;
+		$reaction    = null;
 
 		switch ( $object_type ) {
 			/*
@@ -48,7 +51,7 @@ public static function handle_delete( $activity ) {
 			case 'Organization':
 			case 'Service':
 			case 'Application':
-				self::maybe_delete_follower( $activity );
+				$state = self::maybe_delete_follower( $activity );
 				break;
 
 			/*
@@ -95,6 +98,16 @@ public static function handle_delete( $activity ) {
 				// Maybe handle Delete Activity for other Object Types.
 				break;
 		}
+
+		/**
+		 * Fires after an ActivityPub Delete activity has been handled.
+		 *
+		 * @param array      $activity The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param mixed      $state    The state/result of the operation (e.g., comment ID, WP_Error, or status).
+		 * @param mixed|null $reaction The result of the delete operation (e.g., WP_Comment object or deletion status).
+		 */
+		\do_action( 'activitypub_handled_delete', $activity, $user_id, $state, $reaction );
 	}
 
 	/**
@@ -107,9 +120,11 @@ public static function maybe_delete_follower( $activity ) {
 
 		// Verify that Actor is deleted.
 		if ( ! is_wp_error( $follower ) && Tombstone::exists( $activity['actor'] ) ) {
-			Remote_Actors::delete( $follower->ID );
+			$state = Remote_Actors::delete( $follower->ID );
 			self::maybe_delete_interactions( $activity );
 		}
+
+		return $state ?? null;
 	}
 
 	/**

includes/handler/class-follow.php

@@ -10,7 +10,6 @@
 use Activitypub\Activity\Activity;
 use Activitypub\Collection\Actors;
 use Activitypub\Collection\Followers;
-use Activitypub\Notification;
 
 use function Activitypub\add_to_outbox;
 
@@ -23,7 +22,7 @@ class Follow {
 	 */
 	public static function init() {
 		\add_action( 'activitypub_inbox_follow', array( self::class, 'handle_follow' ), 10, 2 );
-		\add_action( 'activitypub_followers_post_follow', array( self::class, 'queue_accept' ), 10, 4 );
+		\add_action( 'activitypub_handled_follow', array( self::class, 'queue_accept' ), 10, 4 );
 	}
 
 	/**
@@ -44,46 +43,39 @@ public static function handle_follow( $activity, $user_id ) {
 			$activity['actor']
 		);
 
-		if ( \is_wp_error( $remote_actor ) ) {
-			return $remote_actor;
+		if ( ! \is_wp_error( $remote_actor ) ) {
+			$remote_actor = \get_post( $remote_actor );
 		}
 
-		$remote_actor = \get_post( $remote_actor );
+		\do_action_deprecated( 'activitypub_followers_post_follow', array( $activity['actor'], $activity, $user_id, $remote_actor ), 'unreleased', 'activitypub_handled_follow' );
 
 		/**
-		 * Fires after a new follower has been added.
+		 * Fires after a Follow activity has been handled.
 		 *
-		 * @param string             $actor        The URL of the actor (follower) who initiated the follow.
-		 * @param array              $activity     The complete activity data of the follow request.
-		 * @param int                $user_id      The ID of the WordPress user being followed.
-		 * @param \WP_Post|\WP_Error $remote_actor The Actor object containing the new follower's data.
+		 * @param array      $activity     The ActivityPub activity data.
+		 * @param int|null   $user_id      The local user ID, or null if not applicable.
+		 * @param mixed      $remote_actor The WP_Post object of the remote actor/follower, or WP_Error if failed.
+		 * @param mixed|null $remote_actor The WP_Post object of the remote actor/follower (duplicate parameter).
 		 */
-		do_action( 'activitypub_followers_post_follow', $activity['actor'], $activity, $user_id, $remote_actor );
-
-		// Send notification.
-		$notification = new Notification(
-			'follow',
-			$remote_actor->guid,
-			$activity,
-			$user_id
-		);
-		$notification->send();
+		\do_action( 'activitypub_handled_follow', $activity, $user_id, $remote_actor, $remote_actor );
 	}
 
 	/**
 	 * Send Accept response.
 	 *
-	 * @param string             $actor           The Actor URL.
-	 * @param array              $activity_object The Activity object.
-	 * @param int                $user_id         The ID of the WordPress User.
-	 * @param \WP_Post|\WP_Error $remote_actor    The Actor object.
+	 * @param array      $activity_object The ActivityPub activity data.
+	 * @param int|null   $user_id         The local user ID, or null if not applicable.
+	 * @param mixed      $status          The WP_Post object of the remote actor/follower, or WP_Error if failed.
+	 * @param mixed|null $remote_actor    The WP_Post object of the remote actor/follower (duplicate parameter).
 	 */
-	public static function queue_accept( $actor, $activity_object, $user_id, $remote_actor ) {
+	public static function queue_accept( $activity_object, $user_id, $status, $remote_actor ) {
 		if ( \is_wp_error( $remote_actor ) ) {
 			// Impossible to send a "Reject" because we can not get the Remote-Inbox.
 			return;
 		}
 
+		$actor = $activity_object['actor'];
+
 		// Only send minimal data.
 		$activity_object = array_intersect_key(
 			$activity_object,

includes/handler/class-inbox.php

@@ -61,12 +61,12 @@ public static function handle_inbox_requests( $data, $user_id, $type, $activity
 		$id = Inbox_Collection::add( $activity, $user_id );
 
 		/**
-		 * Fires after an inbox item has been handled.
+		 * Fires after an ActivityPub Inbox activity has been handled.
 		 *
-		 * @param array              $data     The data array.
-		 * @param int                $user_id  The ID of the local blog user.
-		 * @param \WP_Error|int      $id       The ID of the inbox item.
-		 * @param Activity|\WP_Error $activity The Activity object.
+		 * @param array      $data     The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param mixed      $id       The ID of the inbox item that was created, or WP_Error if failed.
+		 * @param mixed|null $activity The Activity object or WP_Error from processing the inbox request.
 		 */
 		\do_action( 'activitypub_handled_inbox', $data, $user_id, $id, $activity );
 	}

includes/handler/class-like.php

@@ -54,14 +54,14 @@ public static function handle_like( $like, $user_id ) {
 		}
 
 		/**
-		 * Fires after a Like has been handled.
+		 * Fires after an ActivityPub Like activity has been handled.
 		 *
-		 * @param array $like     The Activity array.
-		 * @param int   $user_id  The ID of the local blog user.
-		 * @param mixed $state    The state of the reaction.
-		 * @param mixed $reaction The reaction object.
+		 * @param array      $like     The ActivityPub activity data.
+		 * @param int|null   $user_id  The local user ID, or null if not applicable.
+		 * @param mixed      $state    The state/result of the operation (e.g., comment ID, WP_Error, or status).
+		 * @param mixed|null $reaction The WP_Comment object of the created like comment, or null if creation failed.
 		 */
-		do_action( 'activitypub_handled_like', $like, $user_id, $state, $reaction );
+		\do_action( 'activitypub_handled_like', $like, $user_id, $state, $reaction );
 	}
 
 	/**