Group Accounts - Functions

Here's a list of some useful functions and methods included in the plugin:

Group object

The RCPGA_Group object was introduced in Group Accounts version 2.0. It contains all the information about a group. The following methods are available:

get_group_id()
Returns the ID of the group.

get_owner_id()
Returns the user ID of the owner of the group.

get_owner()
Returns the WP_User object for the owner of the group.

get_membership_id()
Returns the ID of the membership linked to the group. This will be the group owner's membership.

is_active()
Determines whether or not the group is active and returns true or false accordingly. A group is considered active if the associated membership is active.

get_name()
Returns the name of the group.

get_description()
Returns the group description.

get_code()
Returns the group code. Added in version 2.1.

get_seats()
Returns the maximum number of seats available to the group.

get_member_count()
Returns the current number of members in the group.

get_date_created( $formatted = false )
Returns the date the group was created. If $formatted is false then the date is returned in the format Y-m-d H:i:s. If set to true then a display-ready string is returned.

get_members()
Returns the members of the group as an array of RCPGA_Group_Member objects.

update( $args = array() )
Update the group. $args is the array of data you want to update. Example:

$group = rcpga_get_group( 1 );
$group->update( array(
    'name' => 'New Group Name'
) );

add_member( $args )
Adds a new user to the group. Supported arguments:

  • user_email (string) - Required. Email address of the member to add. Can be an existing user or one that doesn't exist yet (in which case a new user account will be created).
  • user_login (string) - Optional. New member's username. Will fall back to the email address if not provided.
  • first_name (string) - Optional. First name of the member.
  • last_name (string) - Optional. Last name of the member.
  • user_pass (string) - Optional. If not provided, a password is randomly generated.
  • role (string) - Optional. Membership role for the new member. Options include: "owner", "admin", "member", and "invited". Default is "invited".
  • send_invite (bool) - Optional. Whether or not to send the invitation email. Default is true.

On success, returns the ID of the newly added group member. On failure, returns a WP_Error object.

Example:

$group = rcpga_get_group( 1 );
$group->add_member( array(
    'user_email' => 'newuser@example.com',
    'role' => 'invited',
    'send_invite' => true
) );

Group functions

These functions were introduced in Group Accounts version 2.0. You must be on 2.0 or higher to use them.

rcpga_get_group( $group_id )
Returns an RCPGA_Group object, or false if the group is not found.

rcpga_get_groups( $args = array() )
Query for groups. Supported arguments (all are optional):

  • owner_id (int) - Filter by owner user ID number.
  • name (string) - Search for a group name.
  • code (string) - Search for a group code. Added in version 2.1.
  • date_created_query (array) - Filter by the date the group was created. See WP_Date_Query for supported format.
  • number (int) - Maximum number of results. Default 20.
  • offset (int) - Number of groups to offset the query. Default 0.
  • orderby (string) - How to order results. Accepts: "group_id", "owner_id", "name", "seats", "member_count", and "date_created". Default "group_id".
  • order (string) - How to order results. Accepts: "ASC" and "DESC". Default "DESC".
  • search (string) - Search.

Returns an array of RCPGA_Group objects.

rcpga_count_groups( $args =  array() )
Count the number of groups. Accepts same arguments as rcpga_get_groups()

rcpga_add_group( $args = array() )
Adds a new group. Supported arguments:

  • owner_id (int) - Required. User ID of the group owner.
  • membership_id (int) - Optional. ID of the associated membership record. This should be the owner's membership. Warning: If not supplied then the group will not be fully active/usable.
  • name (string) - Required. Name of the group.
  • description (string) - Optional. Group description.
  • seats (int) - Optional. Maximum number of seats. If omitted, the number is auto determined based on membership level settings (if membership_id is supplied).
  • member_count (int) - Optional. Current member count. Default is 1 (includes the owner).

Returns the ID of the newly created group on success, or WP_Error on failure.

Group Meta

This was introduced in Group Accounts version 2.1. You must be on 2.1 or higher to use these functions.

RCPGA\Groups\get_meta( $group_id, $key = '', $single = false )
Retrieves a meta field for a group. Works just like get_post_meta().

RCPGA\Groups\add_meta( $group_id, $meta_key, $meta_value, $unique = false )
Adds a meta data field to a group. Works just like add_post_meta().

RCPGA\Groups\update_meta( $group_id, $meta_key, $meta_value, $prev_value = '' )
Updates a meta field for a group. Works just like update_post_meta().

RCPGA\Groups\delete_meta( $group_id, $meta_key, $meta_value = '' )
Removes meta data from a group. Works just like delete_post_meta().

Group member object

The  RCPGA_Group_Member object was introduced in Group Accounts version 2.0. It contains all the information about a specific group member. The following methods are available:

get_id()
Returns the group member's unique ID. This is NOT their user ID.

get_user_id()
Returns the group member's user ID number.

get_group_id()
Returns the ID of the group this member is in.

get_role()
Returns the member's role within the group. Will be one of: "owner", "admin", "member", "invited".

get_date_added( $formatted = false )
Returns the date the member was added to the group. If $formatted is false, then the date is returned in Y-m-d H:i:s format. If true, it's returned in a display-ready format.

update( $data = array() )
Updates the group member's record.

remove()
Removes this member from the group.

resend_invite()
Re-sends the invitation email.

Group member functions

These functions were introduced in Group Accounts version 2.0. You must be on 2.0 or higher to use them.

rcpga_get_group_member( $user_id, $group_id )
Retrieves a user's group member record for a specific group. On success, an RCPGA_Group_Member object is returned. On failure, false is returned.

rcpga_get_group_member_by_id( $id )
Retrieves an RCPGA_Group_Member object by the unique ID.

rcpga_get_group_members( $args = array() )
Query for group member records. Supported arguments (all optional):

  • user_id (int) - Filter by user ID number.
  • user_id__in (array) - An array of user IDs to filter by.
  • group_id (int) - Filter by group ID.
  • group_id__in (array) - Array of group IDs to include.
  • role (string) - Filter by role within the group.
  • number (int) - Maximum number of records to return. Default 20.
  • offset (int) - Number of offset the query by. Default 0.
  • orderby (string) - What to order the results by. Accepts: "id", "user_id", "group_id", "role", and "date_created". Default "id".
  • order (string) - How to order the results. Accepts: "ASC" and "DESC". Default "DESC".

This example gets all the group memberships for the current user, where their role is "member" or "admin". Then for each group membership, the group owner's user ID is identified.

// Get all group memberships where the current user is "member" or "admin".
$group_memberships = rcpga_get_group_members( array(
	'user_id'  => get_current_user_id(),
	'role__in' => array( 'member', 'admin' )
) );
foreach ( $group_memberships as $group_membership ) {
	$group = $group_membership->get_group();
	if ( $group instanceof RCPGA_Group ) {
		// This is the user ID of the group owner.
		$group_owner_user_id = $group->get_owner_id();
	}
}

rcpga_count_group_members( $args = array() )
Counts the number of group members. Uses the same arguments as rcpga_get_group_members().

rcpga_delete_all_members_of_group( $group_id )
Deletes all members in the provided group.

rcpga_user_is_group_member( $user_id = 0, $role = '' )
Determines if the supplied user is a member of any group. $user_id defaults to the currently logged in user if not provided. Set $role if you want to check for a specific role. For example:

Checks if the current user is a member of any group, without any role restrictions:

 $is_group_member = rcpga_user_is_group_member( get_current_user_id() );

Checks if the current user is an "admin" of any group:

 $is_admin_group_member = rcpga_user_is_group_member( get_current_user_id(), 'admin' );

rcpga_user_is_member_of_group( $user_id, $group_id )
Determines if the supplied user is a member of the supplied group.

Misc functions

rcpga_send_group_invite( $user_id )
Sends the group invitation link to a given user.

rcpga_get_level_group_seats_allowed( $level_id )
Returns the number of seats allowed for the specified membership level.

rcpga_is_level_group_accounts_enabled( $level_id )
Checks if group accounts are enabled for a membership level. Returns true if so, or false if not.

rcpga_get_group_enabled_levels()
Returns an array of all membership level IDs that have group accounts enabled.


Deprecated functions

The below functions were deprecated in version 2.0.

Groups

rcpga_group_accounts()->groups->get_owner_id( $group_id = 0 )

Returns the ID number of the owner of a group.

rcpga_group_accounts()->groups->get_group_by_owner( $owner_id )

Pass in the user ID number of a group owner to get information about the group they own.

rcpga_group_accounts()->groups->is_group_active( $group_id = 0 )

Checks if a group is active. This returns TRUE if the group owner still has an active subscription, or FALSE if they do not.

rcpga_group_accounts()->groups->get_groups( $args = array() )

Query for groups. Default arguments are:

  • 'number' (int) - 20
  • 'offset' (int) - 0
  • 'status' (string) - '' (empty string)
  • 'order' (string) - 'DESC'
  • 'orderby' (string) - 'group_id'
  • 'where' (string) - '' (empty string) (include a WHERE clause in the query)

rcpga_group_accounts()->groups->add( $args = array() )

Insert a new group. Arguments include:

  • 'owner_id' (int) - User ID number of the owner. Required.
  • 'description' (string) - Group description.
  • 'name' (string) - Name of the group.
  • 'seats' (int) - Maximum number of seats. Default 0.
  • 'member_count' (int) - Current member count. Default 0.
  • 'date_created' (string) - Date the group was created, in MySQL format. Default is current date/time.

rcpga_group_accounts()->groups->update( $group_id, $args = array() )

Update group information. $args contains the same information as adding a group.

Group Members

rcpga_group_accounts()->members->get_members( $group_id, $args = array() )

Retrieves an array of members for a given group. Default values for $args are as follows:

  • number (int) - 20
  • offset (int) - 0

rcpga_group_accounts()->members->is_group_owner( $user_id = 0 )

Checks if a given user is the owner of a group. $user_id can be omitted to check the current user. Example:

if ( rcpga_group_accounts()->members->is_group_owner() ) {
    // Current user is a group owner.
} else {
    // Current user is not a group owner.
}

rcpga_group_accounts()->members->is_group_admin( $user_id = 0 )

Checks if a given user is a group admin. $user_id can be omitted to check the current user.

if ( rcpga_group_accounts()->members->is_group_admin() ) {
    // Current user is a group admin.
} else {
    // Current user is not a group admin.
}

rcpga_group_accounts()->members->is_group_member( $user_id = 0 )

Checks if a given user is a group member. $user_id can be omitted to check the current user.

if ( rcpga_group_accounts()->members->is_group_member() ) {
    // Current user is a group member.
} else {
    // Current user is not a group member.
}

rcpga_group_accounts()->members->get_role( $user_id = 0 )

Returns the group role of a given user. Returns a role name ("owner", "admin", "member", "invited") or false if the user is not in a group. $user_id can be omitted to check the current user.

rcpga_group_accounts()->members->get_group_name( $user_id = 0 )

Returns the name of the given member's group (or false if none exists). $user_id can be omitted to check the current user.

rcpga_group_accounts()->members->get_group_id( $user_id = 0 )

Returns the ID number of the given member's group (or  false if none exists). $user_id can be omitted to check the current user.

rcpga_group_accounts()->members->add( $args = array() )

Adds a new member to a group. Available arguments to be used in $args:

  • user_id (int) - ID of the user being added.
  • group_id (int) - ID of the group to add the user to.
  • role (string) - The new user's role (options: owner, admin, member, invited).
  • date_added (string) - Date the user was added to the group in MySQL format.

rcpga_group_accounts()->members->remove( $user_id )

Removes a user from any group they belong to.

rcpga_group_accounts()->members->remove_all_from_group( $group_id )

Removes all members from a specific group. This is often used when deleting a group.

Misc.

rcpga_add_member_to_group( $args )

Adds a member to a group. If the user does not exist then it is created. Available arguments:

  • user_email (string) - Email if the user to add.
  • group_id (int) - ID number of the group to add the user to.
  • send_invite (bool) - Whether or not to send the invitation email (default is true).

Returns the ID of the user on success or a WP_Error object on failure.

Example:

rcpga_add_member_to_group( array(
    'user_email'  => 'janedoe@example.com',
    'group_id'    => 5,
    'send_invite' => false
) );