Skip to content

Improve Following class documentation and method efficiency #2086

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: trunk
Choose a base branch
from
Open

Improve Following class documentation and method efficiency #2086

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ee68cfa
Improve Following class documentation and method efficiency
obenland Aug 21, 2025
bf631f7
Add changelog
matticbot Aug 21, 2025
e555956
Update return type annotations for follow and unfollow
obenland Aug 21, 2025
f8a3075
Merge branch 'fix/following-types' of https://github.com/Automattic/w…
obenland Aug 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/changelog/2086-from-description
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Significance: patch
Type: changed

Improve Following class documentation and optimize count methods for better performance
32 changes: 18 additions & 14 deletions includes/collection/class-following.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
namespace Activitypub\Collection;

use Activitypub\Activity\Activity;
use Activitypub\Http;

use function Activitypub\add_to_outbox;

Expand Down Expand Up @@ -54,14 +53,14 @@ class Following {
/**
* Follow a user.
*
* Please do not use this method directly, use `Activitypub\follow` instead.
* Please do not use this method directly, use `\Activitypub\follow` instead.
*
* @see Activitypub\follow
* @see \Activitypub\follow
*
* @param \WP_Post|int $post The ID of the remote Actor.
* @param int $user_id The ID of the WordPress User.
*
* @return \WP_Post|\WP_Error The ID of the Actor or a WP_Error.
* @return int|false|\WP_Post|\WP_Error The Outbox ID or false on failure, the Actor post or a WP_Error.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pfefferle The possible return values of this method are a bit confusing. It's a WP_Error with an invalid actor, the outbox item ID on success and false on failure, and if we didn't get to adding it to the outbox, the actor post. Would it be possible to limit it to two types?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we do this as part of this PR or in a follow up?

can you file an issue if it should be a follow up?

*/
public static function follow( $post, $user_id ) {
$post = \get_post( $post );
Expand Down Expand Up @@ -146,9 +145,9 @@ public static function reject( $post, $user_id ) {
/**
* Remove a follow request.
*
* Please do not use this method directly, use `Activitypub\unfollow` instead.
* Please do not use this method directly, use `\Activitypub\unfollow` instead.
*
* @see Activitypub\unfollow
* @see \Activitypub\unfollow
*
* @param \WP_Post|int $post The ID of the remote Actor.
* @param int $user_id The ID of the WordPress User.
Expand Down Expand Up @@ -264,7 +263,7 @@ public static function get_following( $user_id, $number = -1, $page = null, $arg
* @return int The total number of followings.
*/
public static function count_following( $user_id ) {
return self::get_following_with_count( $user_id, -1, null, array() )['total'];
return self::get_following_with_count( $user_id, 1 )['total'];
}

/**
Expand Down Expand Up @@ -330,7 +329,7 @@ public static function get_pending( $user_id, $number = -1, $page = null, $args
* @return int The total number of pending followings.
*/
public static function count_pending( $user_id ) {
return self::get_pending_with_count( $user_id, -1, null, array() )['total'];
return self::get_pending_with_count( $user_id, 1 )['total'];
}

/**
Expand All @@ -341,7 +340,12 @@ public static function count_pending( $user_id ) {
* @param int $page Page number.
* @param array $args The WP_Query arguments.
*
* @return \WP_Post[] List of `Following` objects.
* @return array {
* Data about the followings.
*
* @type \WP_Post[] $followers List of `Follower` objects.
* @type int $total Total number of followers.
Copy link
Preview

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation incorrectly refers to 'followers' and 'Follower' objects in a Following class. This should be 'following' and 'Following' objects to match the class context.

Suggested change
* @type int $total Total number of followers.
* @type \WP_Post[] $following List of `Following` objects.
* @type int $total Total number of followings.

Copilot uses AI. Check for mistakes.

Copy link
Preview

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation incorrectly refers to 'followers' when it should be 'following' to match the class context.

Suggested change
* @type int $total Total number of followers.
* @type \WP_Post[] $following List of `Following` objects.
* @type int $total Total number of following.

Copilot uses AI. Check for mistakes.

* }
*/
public static function get_all_with_count( $user_id, $number = -1, $page = null, $args = array() ) {
$defaults = array(
Expand Down Expand Up @@ -380,7 +384,7 @@ public static function get_all_with_count( $user_id, $number = -1, $page = null,
* @return \WP_Post[] List of `Following` objects.
*/
public static function get_all( $user_id ) {
return self::get_all_with_count( $user_id, -1, null, array() )['following'];
return self::get_all_with_count( $user_id )['following'];
}

/**
Expand All @@ -391,7 +395,7 @@ public static function get_all( $user_id ) {
* @return int The total number of all followings.
*/
public static function count_all( $user_id ) {
return self::get_all_with_count( $user_id, -1, null, array() )['total'];
return self::get_all_with_count( $user_id, 1 )['total'];
}

/**
Expand All @@ -403,9 +407,9 @@ public static function count_all( $user_id ) {
*/
public static function count( $user_id ) {
return array(
self::ALL => self::get_all_with_count( $user_id, -1, null, array() )['total'],
self::ACCEPTED => self::get_following_with_count( $user_id, -1, null, array() )['total'],
self::PENDING => self::get_pending_with_count( $user_id, -1, null, array() )['total'],
self::ALL => self::get_all_with_count( $user_id, 1 )['total'],
self::ACCEPTED => self::get_following_with_count( $user_id, 1 )['total'],
self::PENDING => self::get_pending_with_count( $user_id, 1 )['total'],
);
}

Expand Down
4 changes: 2 additions & 2 deletions includes/functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1550,7 +1550,7 @@ function add_to_outbox( $data, $activity_type = null, $user_id = 0, $content_vis
* @param string|int $remote_actor The Actor URL, WebFinger Resource or Post-ID of the remote Actor.
* @param int $user_id The ID of the WordPress User.
*
* @return \WP_Post|\WP_Error The ID of the Outbox item or a WP_Error.
* @return int|false|\WP_Post|\WP_Error The Outbox ID or false on failure, the Actor post or a WP_Error.
*/
function follow( $remote_actor, $user_id ) {
if ( \is_numeric( $remote_actor ) ) {
Expand Down Expand Up @@ -1580,7 +1580,7 @@ function follow( $remote_actor, $user_id ) {
* @param string|int $remote_actor The Actor URL, WebFinger Resource or Post-ID of the remote Actor.
* @param int $user_id The ID of the WordPress User.
*
* @return \WP_Post|\WP_Error The ID of the Outbox item or a WP_Error.
* @return \WP_Post|\WP_Error The Actor post or a WP_Error.
*/
function unfollow( $remote_actor, $user_id ) {
if ( \is_numeric( $remote_actor ) ) {
Expand Down
Loading