Skip to content

Commit ac4d591

Browse files
obenlandobenland
authored
Docs: Add missing hook documentation (#1099)
1 parent 6a7de00 commit ac4d591

19 files changed

+178
-43
lines changed

‎includes/class-activity-dispatcher.php

+9-9
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ public static function send_profile_update( $user_id ) {
160160
*/
161161
private static function send_activity_to_followers( $activity, $user_id, $wp_object ) {
162162
/**
163-
* Filter to prevent sending an Activity to followers.
163+
* Filters whether to send an Activity to followers.
164164
*
165165
* @param bool $send_activity_to_followers Whether to send the Activity to followers.
166166
* @param Activity $activity The ActivityPub Activity.
@@ -172,11 +172,11 @@ private static function send_activity_to_followers( $activity, $user_id, $wp_obj
172172
}
173173

174174
/**
175-
* Filter to modify the Activity before sending it to followers.
175+
* Filters the list of inboxes to send the Activity to.
176176
*
177-
* @param Activity $activity The ActivityPub Activity.
178-
* @param int $user_id The user ID.
179-
* @param \WP_User|WP_Post|WP_Comment $wp_object The WordPress object.
177+
* @param array $inboxes The list of inboxes to send to.
178+
* @param int $user_id The user ID.
179+
* @param Activity $activity The ActivityPub Activity.
180180
*/
181181
$inboxes = apply_filters( 'activitypub_send_to_inboxes', array(), $user_id, $activity );
182182
$inboxes = array_unique( $inboxes );
@@ -208,15 +208,15 @@ public static function send_post( $id, $type ) {
208208
}
209209

210210
/**
211-
* Action to send an Activity for a Post.
211+
* Fires when an Activity is being sent for any object type.
212212
*
213213
* @param WP_Post $post The WordPress Post.
214214
* @param string $type The Activity-Type.
215215
*/
216216
do_action( 'activitypub_send_activity', $post, $type );
217217

218218
/**
219-
* Action to send a specific Activity for a Post.
219+
* Fires when a specific type of Activity is being sent.
220220
*
221221
* @param WP_Post $post The WordPress Post.
222222
*/
@@ -237,15 +237,15 @@ public static function send_comment( $id, $type ) {
237237
}
238238

239239
/**
240-
* Action to send an Activity for a Comment.
240+
* Fires when an Activity is being sent for a Comment.
241241
*
242242
* @param WP_Comment $comment The WordPress Comment.
243243
* @param string $type The Activity-Type.
244244
*/
245245
do_action( 'activitypub_send_activity', $comment, $type );
246246

247247
/**
248-
* Action to send a specific Activity for a Comment.
248+
* Fires when a specific type of Activity is being sent for a Comment.
249249
*
250250
* @param WP_Comment $comment The WordPress Comment.
251251
*/

‎includes/class-activitypub.php

+3
Original file line numberDiff line numberDiff line change
@@ -555,6 +555,9 @@ private static function register_post_types() {
555555
\register_post_type( Extra_Fields::USER_POST_TYPE, $args );
556556
\register_post_type( Extra_Fields::BLOG_POST_TYPE, $args );
557557

558+
/**
559+
* Fires after ActivityPub custom post types have been registered.
560+
*/
558561
\do_action( 'activitypub_after_register_post_type' );
559562
}
560563

‎includes/class-comment.php

+7
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,13 @@ public static function comment_reply_link( $link, $args, $comment ) {
6565
esc_attr( wp_json_encode( $attrs ) )
6666
);
6767

68+
/**
69+
* Filters the HTML markup for the ActivityPub remote comment reply container.
70+
*
71+
* @param string $div The HTML markup for the remote reply container. Default is a div
72+
* with class 'activitypub-remote-reply' and data attributes for
73+
* the selected comment ID and internal comment ID.
74+
*/
6875
return apply_filters( 'activitypub_comment_reply_link', $div );
6976
}
7077

‎includes/class-http.php

+26-4
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ class Http {
2626
* @return array|WP_Error The POST Response or an WP_Error.
2727
*/
2828
public static function post( $url, $body, $user_id ) {
29+
/**
30+
* Fires before an HTTP POST request is made.
31+
*
32+
* @param string $url The URL endpoint.
33+
* @param string $body The POST body.
34+
* @param int $user_id The WordPress User ID.
35+
*/
2936
\do_action( 'activitypub_pre_http_post', $url, $body, $user_id );
3037

3138
$date = \gmdate( 'D, d M Y H:i:s T' );
@@ -35,7 +42,7 @@ public static function post( $url, $body, $user_id ) {
3542
$wp_version = get_masked_wp_version();
3643

3744
/**
38-
* Filter the HTTP headers user agent.
45+
* Filters the HTTP headers user agent string.
3946
*
4047
* @param string $user_agent The user agent string.
4148
*/
@@ -84,6 +91,11 @@ public static function post( $url, $body, $user_id ) {
8491
* @return array|WP_Error The GET Response or a WP_Error.
8592
*/
8693
public static function get( $url, $cached = false ) {
94+
/**
95+
* Fires before an HTTP GET request is made.
96+
*
97+
* @param string $url The URL endpoint.
98+
*/
8799
\do_action( 'activitypub_pre_http_get', $url );
88100

89101
if ( $cached ) {
@@ -110,14 +122,24 @@ public static function get( $url, $cached = false ) {
110122
$wp_version = get_masked_wp_version();
111123

112124
/**
113-
* Filter the HTTP headers user agent.
125+
* Filters the HTTP headers user agent string.
126+
*
127+
* This filter allows developers to modify the user agent string that is
128+
* sent with HTTP requests.
114129
*
115130
* @param string $user_agent The user agent string.
116131
*/
117132
$user_agent = \apply_filters( 'http_headers_useragent', 'WordPress/' . $wp_version . '; ' . \get_bloginfo( 'url' ) );
118133

134+
/**
135+
* Filters the timeout duration for remote GET requests in ActivityPub.
136+
*
137+
* @param int $timeout The timeout value in seconds. Default 100 seconds.
138+
*/
139+
$timeout = \apply_filters( 'activitypub_remote_get_timeout', 100 );
140+
119141
$args = array(
120-
'timeout' => apply_filters( 'activitypub_remote_get_timeout', 100 ),
142+
'timeout' => $timeout,
121143
'limit_response_size' => 1048576,
122144
'redirection' => 3,
123145
'user-agent' => "$user_agent; ActivityPub",
@@ -164,7 +186,7 @@ public static function get( $url, $cached = false ) {
164186
*/
165187
public static function is_tombstone( $url ) {
166188
/**
167-
* Action before checking if the URL is a tombstone.
189+
* Fires before checking if the URL is a tombstone.
168190
*
169191
* @param string $url The URL to check.
170192
*/

‎includes/class-link.php

+5
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,11 @@ public static function replace_with_links( $result ) {
112112
$display_class .= 'ellipsis';
113113
}
114114

115+
/**
116+
* Filters the rel attribute for ActivityPub links.
117+
*
118+
* @param string $rel The rel attribute string. Default 'nofollow noopener noreferrer'.
119+
*/
115120
$rel = apply_filters( 'activitypub_link_rel', 'nofollow noopener noreferrer' );
116121

117122
return \sprintf(

‎includes/class-shortcodes.php

+2
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ public static function excerpt( $atts, $content, $tag ) {
129129

130130
$excerpt = generate_post_summary( $item, $excerpt_length );
131131

132+
/** This filter is documented in wp-includes/post-template.php */
132133
return \apply_filters( 'the_excerpt', $excerpt );
133134
}
134135

@@ -169,6 +170,7 @@ public static function content( $atts, $content, $tag ) {
169170
$content = \get_post_field( 'post_content', $item );
170171

171172
if ( 'yes' === $atts['apply_filters'] ) {
173+
/** This filter is documented in wp-includes/post-template.php */
172174
$content = \apply_filters( 'the_content', $content );
173175
} else {
174176
$content = do_blocks( $content );

‎includes/collection/class-extra-fields.php

+9
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,15 @@ public static function get_actor_fields( $user_id ) {
4242
$query = new \WP_Query( $args );
4343
$fields = $query->posts ?? array();
4444

45+
/**
46+
* Filters the extra fields for an ActivityPub actor.
47+
*
48+
* This filter allows developers to modify or add custom fields to an actor's
49+
* profile.
50+
*
51+
* @param \WP_Post[] $fields Array of WP_Post objects representing the extra fields.
52+
* @param int $user_id The ID of the user whose fields are being retrieved.
53+
*/
4554
return apply_filters( 'activitypub_get_actor_extra_fields', $fields, $user_id );
4655
}
4756

‎includes/functions.php

+32-7
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,15 @@
2121
function get_context() {
2222
$context = Activity::JSON_LD_CONTEXT;
2323

24+
/**
25+
* Filters the ActivityPub JSON-LD context.
26+
*
27+
* This filter allows developers to modify or extend the JSON-LD context used
28+
* in ActivityPub responses. The context defines the vocabulary and terms used
29+
* in the ActivityPub JSON objects.
30+
*
31+
* @param array $context The default ActivityPub JSON-LD context array.
32+
*/
2433
return \apply_filters( 'activitypub_json_context', $context );
2534
}
2635

@@ -68,6 +77,16 @@ function get_webfinger_resource( $user_id ) {
6877
* @return array|WP_Error The Actor profile as array or WP_Error on failure.
6978
*/
7079
function get_remote_metadata_by_actor( $actor, $cached = true ) {
80+
/**
81+
* Filters the metadata before it is retrieved from a remote actor.
82+
*
83+
* Passing a non-false value will effectively short-circuit the remote request,
84+
* returning that value instead.
85+
*
86+
* @param mixed $pre The value to return instead of the remote metadata.
87+
* Default false to continue with the remote request.
88+
* @param string $actor The actor URL.
89+
*/
7190
$pre = apply_filters( 'pre_get_remote_metadata_by_actor', false, $actor );
7291
if ( $pre ) {
7392
return $pre;
@@ -414,7 +433,7 @@ function is_post_disabled( $post ) {
414433
$disabled = true;
415434
}
416435

417-
/*
436+
/**
418437
* Allow plugins to disable posts for ActivityPub.
419438
*
420439
* @param boolean $disabled True if the post is disabled, false otherwise.
@@ -1312,11 +1331,7 @@ function generate_post_summary( $post, $length = 500 ) {
13121331
$content = \sanitize_post_field( 'post_excerpt', $post->post_excerpt, $post->ID );
13131332

13141333
if ( $content ) {
1315-
/**
1316-
* Filters the post excerpt.
1317-
*
1318-
* @param string $content The post excerpt.
1319-
*/
1334+
/** This filter is documented in wp-includes/post-template.php */
13201335
return \apply_filters( 'the_excerpt', $content );
13211336
}
13221337

@@ -1354,6 +1369,7 @@ function generate_post_summary( $post, $length = 500 ) {
13541369

13551370
/*
13561371
Removed until this is merged: https://github.com/mastodon/mastodon/pull/28629
1372+
/** This filter is documented in wp-includes/post-template.php
13571373
return \apply_filters( 'the_excerpt', $content );
13581374
*/
13591375
return $content;
@@ -1459,6 +1475,15 @@ function get_content_visibility( $post_id ) {
14591475
$_visibility = $visibility;
14601476
}
14611477

1478+
/**
1479+
* Filters the visibility of a post.
1480+
*
1481+
* @param string $_visibility The visibility of the post. Possible values are:
1482+
* - 'public': Post is public and federated.
1483+
* - 'quiet_public': Post is public but not federated.
1484+
* - 'local': Post is only visible locally.
1485+
* @param \WP_Post $post The post object.
1486+
*/
14621487
return \apply_filters( 'activitypub_content_visibility', $_visibility, $post );
14631488
}
14641489

@@ -1512,7 +1537,7 @@ function get_upload_baseurl() {
15121537
/**
15131538
* Filters the upload base URL.
15141539
*
1515-
* @param string \wp_get_upload_dir()['baseurl'] The upload base URL.
1540+
* @param string $upload_dir The upload base URL. Default \wp_get_upload_dir()['baseurl']
15161541
*/
15171542
return apply_filters( 'activitypub_get_upload_baseurl', $upload_dir['baseurl'] );
15181543
}

‎includes/handler/class-follow.php

+9-7
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,15 @@ public static function handle_follow( $activity ) {
5555
$activity['actor']
5656
);
5757

58-
do_action(
59-
'activitypub_followers_post_follow',
60-
$activity['actor'],
61-
$activity,
62-
$user_id,
63-
$follower
64-
);
58+
/**
59+
* Fires after a new follower has been added.
60+
*
61+
* @param string $actor The URL of the actor (follower) who initiated the follow.
62+
* @param array $activity The complete activity data of the follow request.
63+
* @param int $user_id The ID of the WordPress user being followed.
64+
* @param \Activitypub\Model\Follower $follower The Follower object containing the new follower's data.
65+
*/
66+
do_action( 'activitypub_followers_post_follow', $activity['actor'], $activity, $user_id, $follower );
6567

6668
// Send notification.
6769
$notification = new Notification(

‎includes/handler/class-update.php

+8
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,14 @@ public static function update_interaction( $activity ) {
8888
$state = $commentdata;
8989
}
9090

91+
/**
92+
* Fires after an Update activity has been handled.
93+
*
94+
* @param array $activity The complete Update activity data.
95+
* @param null $user Always null for Update activities.
96+
* @param int|array $state 1 if comment was updated successfully, error data otherwise.
97+
* @param \WP_Comment|null $reaction The updated comment object if successful, null otherwise.
98+
*/
9199
\do_action( 'activitypub_handled_update', $activity, null, $state, $reaction );
92100
}
93101

‎includes/model/class-blog.php

+5-1
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,11 @@ public static function get_default_username() {
204204
/**
205205
* Filters the default blog username.
206206
*
207-
* @param string $host The default username.
207+
* This filter allows developers to modify the default username that is
208+
* generated for the blog, which by default is the site's host name
209+
* without the 'www.' prefix.
210+
*
211+
* @param string $host The default username (site's host name).
208212
*/
209213
return apply_filters( 'activitypub_default_blog_username', $host );
210214
}

‎includes/rest/class-inbox.php

+3-3
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ public static function user_inbox_get( $request ) {
8585
}
8686

8787
/**
88-
* Action triggered prior to the ActivityPub profile being created and sent to the client.
88+
* Fires before the ActivityPub inbox is created and sent to the client.
8989
*/
9090
\do_action( 'activitypub_rest_inbox_pre' );
9191

@@ -103,14 +103,14 @@ public static function user_inbox_get( $request ) {
103103
// phpcs:enable WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
104104

105105
/**
106-
* Filter the ActivityPub inbox array.
106+
* Filters the ActivityPub inbox data before it is sent to the client.
107107
*
108108
* @param array $json The ActivityPub inbox array.
109109
*/
110110
$json = \apply_filters( 'activitypub_rest_inbox_array', $json );
111111

112112
/**
113-
* Action triggered after the ActivityPub profile has been created and sent to the client.
113+
* Fires after the ActivityPub inbox has been created and sent to the client.
114114
*/
115115
\do_action( 'activitypub_inbox_post' );
116116

‎includes/rest/class-interaction.php

+16
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,26 @@ public static function get( $request ) {
8080
case 'Service':
8181
case 'Application':
8282
case 'Organization':
83+
/**
84+
* Filters the URL used for following an ActivityPub actor.
85+
*
86+
* @param string $redirect_url The URL to redirect to.
87+
* @param string $uri The URI of the actor to follow.
88+
* @param array $object The full actor object data.
89+
*/
8390
$redirect_url = \apply_filters( 'activitypub_interactions_follow_url', $redirect_url, $uri, $object );
8491
break;
8592
default:
8693
$redirect_url = \admin_url( 'post-new.php?in_reply_to=' . $uri );
94+
/**
95+
* Filters the URL used for replying to an ActivityPub object.
96+
*
97+
* By default, this redirects to the WordPress post editor with the in_reply_to parameter set.
98+
*
99+
* @param string $redirect_url The URL to redirect to.
100+
* @param string $uri The URI of the object to reply to.
101+
* @param array $object The full object data being replied to.
102+
*/
87103
$redirect_url = \apply_filters( 'activitypub_interactions_reply_url', $redirect_url, $uri, $object );
88104
}
89105

0 commit comments

Comments
 (0)