Merge branch 'trunk' into implement/844

includes/class-activity-dispatcher.php

@@ -160,7 +160,7 @@ public static function send_profile_update( $user_id ) {
 	 */
 	private static function send_activity_to_followers( $activity, $user_id, $wp_object ) {
 		/**
-		 * Filter to prevent sending an Activity to followers.
+		 * Filters whether to send an Activity to followers.
 		 *
 		 * @param bool                        $send_activity_to_followers Whether to send the Activity to followers.
 		 * @param Activity                    $activity                   The ActivityPub Activity.
@@ -172,11 +172,11 @@ private static function send_activity_to_followers( $activity, $user_id, $wp_obj
 		}
 
 		/**
-		 * Filter to modify the Activity before sending it to followers.
+		 * Filters the list of inboxes to send the Activity to.
 		 *
-		 * @param Activity                    $activity  The ActivityPub Activity.
-		 * @param int                         $user_id   The user ID.
-		 * @param \WP_User|WP_Post|WP_Comment $wp_object The WordPress object.
+		 * @param array    $inboxes  The list of inboxes to send to.
+		 * @param int      $user_id  The user ID.
+		 * @param Activity $activity The ActivityPub Activity.
 		 */
 		$inboxes = apply_filters( 'activitypub_send_to_inboxes', array(), $user_id, $activity );
 		$inboxes = array_unique( $inboxes );
@@ -208,15 +208,15 @@ public static function send_post( $id, $type ) {
 		}
 
 		/**
-		 * Action to send an Activity for a Post.
+		 * Fires when an Activity is being sent for any object type.
 		 *
 		 * @param WP_Post $post The WordPress Post.
 		 * @param string  $type The Activity-Type.
 		 */
 		do_action( 'activitypub_send_activity', $post, $type );
 
 		/**
-		 * Action to send a specific Activity for a Post.
+		 * Fires when a specific type of Activity is being sent.
 		 *
 		 * @param WP_Post $post The WordPress Post.
 		 */
@@ -237,15 +237,15 @@ public static function send_comment( $id, $type ) {
 		}
 
 		/**
-		 * Action to send an Activity for a Comment.
+		 * Fires when an Activity is being sent for a Comment.
 		 *
 		 * @param WP_Comment $comment The WordPress Comment.
 		 * @param string     $type    The Activity-Type.
 		 */
 		do_action( 'activitypub_send_activity', $comment, $type );
 
 		/**
-		 * Action to send a specific Activity for a Comment.
+		 * Fires when a specific type of Activity is being sent for a Comment.
 		 *
 		 * @param WP_Comment $comment The WordPress Comment.
 		 */

includes/class-activitypub.php

@@ -555,6 +555,9 @@ private static function register_post_types() {
 		\register_post_type( Extra_Fields::USER_POST_TYPE, $args );
 		\register_post_type( Extra_Fields::BLOG_POST_TYPE, $args );
 
+		/**
+		 * Fires after ActivityPub custom post types have been registered.
+		 */
 		\do_action( 'activitypub_after_register_post_type' );
 	}
 

includes/class-comment.php

@@ -65,6 +65,13 @@ public static function comment_reply_link( $link, $args, $comment ) {
 			esc_attr( wp_json_encode( $attrs ) )
 		);
 
+		/**
+		 * Filters the HTML markup for the ActivityPub remote comment reply container.
+		 *
+		 * @param string $div The HTML markup for the remote reply container. Default is a div
+		 *                    with class 'activitypub-remote-reply' and data attributes for
+		 *                    the selected comment ID and internal comment ID.
+		 */
 		return apply_filters( 'activitypub_comment_reply_link', $div );
 	}
 

includes/class-http.php

@@ -26,6 +26,13 @@ class Http {
 	 * @return array|WP_Error The POST Response or an WP_Error.
 	 */
 	public static function post( $url, $body, $user_id ) {
+		/**
+		 * Fires before an HTTP POST request is made.
+		 *
+		 * @param string $url     The URL endpoint.
+		 * @param string $body    The POST body.
+		 * @param int    $user_id The WordPress User ID.
+		 */
 		\do_action( 'activitypub_pre_http_post', $url, $body, $user_id );
 
 		$date      = \gmdate( 'D, d M Y H:i:s T' );
@@ -35,7 +42,7 @@ public static function post( $url, $body, $user_id ) {
 		$wp_version = get_masked_wp_version();
 
 		/**
-		 * Filter the HTTP headers user agent.
+		 * Filters the HTTP headers user agent string.
 		 *
 		 * @param string $user_agent The user agent string.
 		 */
@@ -84,6 +91,11 @@ public static function post( $url, $body, $user_id ) {
 	 * @return array|WP_Error The GET Response or a WP_Error.
 	 */
 	public static function get( $url, $cached = false ) {
+		/**
+		 * Fires before an HTTP GET request is made.
+		 *
+		 * @param string $url The URL endpoint.
+		 */
 		\do_action( 'activitypub_pre_http_get', $url );
 
 		if ( $cached ) {
@@ -110,14 +122,24 @@ public static function get( $url, $cached = false ) {
 		$wp_version = get_masked_wp_version();
 
 		/**
-		 * Filter the HTTP headers user agent.
+		 * Filters the HTTP headers user agent string.
+		 *
+		 * This filter allows developers to modify the user agent string that is
+		 * sent with HTTP requests.
 		 *
 		 * @param string $user_agent The user agent string.
 		 */
 		$user_agent = \apply_filters( 'http_headers_useragent', 'WordPress/' . $wp_version . '; ' . \get_bloginfo( 'url' ) );
 
+		/**
+		 * Filters the timeout duration for remote GET requests in ActivityPub.
+		 *
+		 * @param int $timeout The timeout value in seconds. Default 100 seconds.
+		 */
+		$timeout = \apply_filters( 'activitypub_remote_get_timeout', 100 );
+
 		$args = array(
-			'timeout'             => apply_filters( 'activitypub_remote_get_timeout', 100 ),
+			'timeout'             => $timeout,
 			'limit_response_size' => 1048576,
 			'redirection'         => 3,
 			'user-agent'          => "$user_agent; ActivityPub",
@@ -164,7 +186,7 @@ public static function get( $url, $cached = false ) {
 	 */
 	public static function is_tombstone( $url ) {
 		/**
-		 * Action before checking if the URL is a tombstone.
+		 * Fires before checking if the URL is a tombstone.
 		 *
 		 * @param string $url The URL to check.
 		 */

includes/class-link.php

@@ -112,6 +112,11 @@ public static function replace_with_links( $result ) {
 			$display_class .= 'ellipsis';
 		}
 
+		/**
+		 * Filters the rel attribute for ActivityPub links.
+		 *
+		 * @param string $rel The rel attribute string. Default 'nofollow noopener noreferrer'.
+		 */
 		$rel = apply_filters( 'activitypub_link_rel', 'nofollow noopener noreferrer' );
 
 		return \sprintf(

includes/class-shortcodes.php

@@ -129,6 +129,7 @@ public static function excerpt( $atts, $content, $tag ) {
 
 		$excerpt = generate_post_summary( $item, $excerpt_length );
 
+		/** This filter is documented in wp-includes/post-template.php */
 		return \apply_filters( 'the_excerpt', $excerpt );
 	}
 
@@ -169,6 +170,7 @@ public static function content( $atts, $content, $tag ) {
 			$content = \get_post_field( 'post_content', $item );
 
 			if ( 'yes' === $atts['apply_filters'] ) {
+				/** This filter is documented in wp-includes/post-template.php */
 				$content = \apply_filters( 'the_content', $content );
 			} else {
 				$content = do_blocks( $content );

includes/collection/class-extra-fields.php

@@ -42,6 +42,15 @@ public static function get_actor_fields( $user_id ) {
 		$query  = new \WP_Query( $args );
 		$fields = $query->posts ?? array();
 
+		/**
+		 * Filters the extra fields for an ActivityPub actor.
+		 *
+		 * This filter allows developers to modify or add custom fields to an actor's
+		 * profile.
+		 *
+		 * @param \WP_Post[] $fields   Array of WP_Post objects representing the extra fields.
+		 * @param int        $user_id  The ID of the user whose fields are being retrieved.
+		 */
 		return apply_filters( 'activitypub_get_actor_extra_fields', $fields, $user_id );
 	}
 

includes/functions.php

@@ -21,6 +21,15 @@
 function get_context() {
 	$context = Activity::JSON_LD_CONTEXT;
 
+	/**
+	 * Filters the ActivityPub JSON-LD context.
+	 *
+	 * This filter allows developers to modify or extend the JSON-LD context used
+	 * in ActivityPub responses. The context defines the vocabulary and terms used
+	 * in the ActivityPub JSON objects.
+	 *
+	 * @param array $context The default ActivityPub JSON-LD context array.
+	 */
 	return \apply_filters( 'activitypub_json_context', $context );
 }
 
@@ -68,6 +77,16 @@ function get_webfinger_resource( $user_id ) {
  * @return array|WP_Error The Actor profile as array or WP_Error on failure.
  */
 function get_remote_metadata_by_actor( $actor, $cached = true ) {
+	/**
+	 * Filters the metadata before it is retrieved from a remote actor.
+	 *
+	 * Passing a non-false value will effectively short-circuit the remote request,
+	 * returning that value instead.
+	 *
+	 * @param mixed  $pre   The value to return instead of the remote metadata.
+	 *                      Default false to continue with the remote request.
+	 * @param string $actor The actor URL.
+	 */
 	$pre = apply_filters( 'pre_get_remote_metadata_by_actor', false, $actor );
 	if ( $pre ) {
 		return $pre;
@@ -414,7 +433,7 @@ function is_post_disabled( $post ) {
 		$disabled = true;
 	}
 
-	/*
+	/**
 	 * Allow plugins to disable posts for ActivityPub.
 	 *
 	 * @param boolean  $disabled True if the post is disabled, false otherwise.
@@ -1312,11 +1331,7 @@ function generate_post_summary( $post, $length = 500 ) {
 	$content = \sanitize_post_field( 'post_excerpt', $post->post_excerpt, $post->ID );
 
 	if ( $content ) {
-		/**
-		 * Filters the post excerpt.
-		 *
-		 * @param string $content The post excerpt.
-		 */
+		/** This filter is documented in wp-includes/post-template.php */
 		return \apply_filters( 'the_excerpt', $content );
 	}
 
@@ -1354,6 +1369,7 @@ function generate_post_summary( $post, $length = 500 ) {
 
 	/*
 	Removed until this is merged: https://github.com/mastodon/mastodon/pull/28629
+	/** This filter is documented in wp-includes/post-template.php
 	return \apply_filters( 'the_excerpt', $content );
 	*/
 	return $content;
@@ -1459,6 +1475,15 @@ function get_content_visibility( $post_id ) {
 		$_visibility = $visibility;
 	}
 
+	/**
+	 * Filters the visibility of a post.
+	 *
+	 * @param string   $_visibility The visibility of the post. Possible values are:
+	 *                              - 'public': Post is public and federated.
+	 *                              - 'quiet_public': Post is public but not federated.
+	 *                              - 'local': Post is only visible locally.
+	 * @param \WP_Post $post        The post object.
+	 */
 	return \apply_filters( 'activitypub_content_visibility', $_visibility, $post );
 }
 
@@ -1512,7 +1537,7 @@ function get_upload_baseurl() {
 	/**
 	 * Filters the upload base URL.
 	 *
-	 * @param string \wp_get_upload_dir()['baseurl'] The upload base URL.
+	 * @param string $upload_dir The upload base URL. Default \wp_get_upload_dir()['baseurl']
 	 */
 	return apply_filters( 'activitypub_get_upload_baseurl', $upload_dir['baseurl'] );
 }

includes/handler/class-follow.php

@@ -55,13 +55,15 @@ public static function handle_follow( $activity ) {
 			$activity['actor']
 		);
 
-		do_action(
-			'activitypub_followers_post_follow',
-			$activity['actor'],
-			$activity,
-			$user_id,
-			$follower
-		);
+		/**
+		 * Fires after a new follower has been added.
+		 *
+		 * @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 \Activitypub\Model\Follower $follower The Follower object containing the new follower's data.
+		 */
+		do_action( 'activitypub_followers_post_follow', $activity['actor'], $activity, $user_id, $follower );
 
 		// Send notification.
 		$notification = new Notification(

includes/handler/class-update.php

@@ -88,6 +88,14 @@ public static function update_interaction( $activity ) {
 			$state = $commentdata;
 		}
 
+		/**
+		 * Fires after an Update activity has been handled.
+		 *
+		 * @param array            $activity The complete Update activity data.
+		 * @param null             $user     Always null for Update activities.
+		 * @param int|array        $state    1 if comment was updated successfully, error data otherwise.
+		 * @param \WP_Comment|null $reaction The updated comment object if successful, null otherwise.
+		 */
 		\do_action( 'activitypub_handled_update', $activity, null, $state, $reaction );
 	}
 

includes/model/class-blog.php

@@ -204,7 +204,11 @@ public static function get_default_username() {
 		/**
 		 * Filters the default blog username.
 		 *
-		 * @param string $host The default username.
+		 * This filter allows developers to modify the default username that is
+		 * generated for the blog, which by default is the site's host name
+		 * without the 'www.' prefix.
+		 *
+		 * @param string $host The default username (site's host name).
 		 */
 		return apply_filters( 'activitypub_default_blog_username', $host );
 	}

includes/rest/class-inbox.php

@@ -85,7 +85,7 @@ public static function user_inbox_get( $request ) {
 		}
 
 		/**
-		 * Action triggered prior to the ActivityPub profile being created and sent to the client.
+		 * Fires before the ActivityPub inbox is created and sent to the client.
 		 */
 		\do_action( 'activitypub_rest_inbox_pre' );
 
@@ -103,14 +103,14 @@ public static function user_inbox_get( $request ) {
 		// phpcs:enable WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
 
 		/**
-		 * Filter the ActivityPub inbox array.
+		 * Filters the ActivityPub inbox data before it is sent to the client.
 		 *
 		 * @param array $json The ActivityPub inbox array.
 		 */
 		$json = \apply_filters( 'activitypub_rest_inbox_array', $json );
 
 		/**
-		 * Action triggered after the ActivityPub profile has been created and sent to the client.
+		 * Fires after the ActivityPub inbox has been created and sent to the client.
 		 */
 		\do_action( 'activitypub_inbox_post' );
 

includes/rest/class-interaction.php

@@ -80,10 +80,26 @@ public static function get( $request ) {
 			case 'Service':
 			case 'Application':
 			case 'Organization':
+				/**
+				 * Filters the URL used for following an ActivityPub actor.
+				 *
+				 * @param string $redirect_url The URL to redirect to.
+				 * @param string $uri          The URI of the actor to follow.
+				 * @param array  $object       The full actor object data.
+				 */
 				$redirect_url = \apply_filters( 'activitypub_interactions_follow_url', $redirect_url, $uri, $object );
 				break;
 			default:
 				$redirect_url = \admin_url( 'post-new.php?in_reply_to=' . $uri );
+				/**
+				 * Filters the URL used for replying to an ActivityPub object.
+				 *
+				 * By default, this redirects to the WordPress post editor with the in_reply_to parameter set.
+				 *
+				 * @param string $redirect_url The URL to redirect to.
+				 * @param string $uri          The URI of the object to reply to.
+				 * @param array  $object       The full object data being replied to.
+				 */
 				$redirect_url = \apply_filters( 'activitypub_interactions_reply_url', $redirect_url, $uri, $object );
 		}