Ticket #3961: 3961.1.patch

src/bp-core/admin/bp-core-admin-schema.php

@@ -202 +202 @@
                                 slug varchar(200) NOT NULL,
                                 description longtext NOT NULL,
                                 status varchar(10) NOT NULL DEFAULT 'public',
+                                parent_id bigint(20) NOT NULL DEFAULT 0,
                                 enable_forum tinyint(1) NOT NULL DEFAULT '1',
                                 date_created datetime NOT NULL,
                                 KEY creator_id (creator_id),
-                                KEY status (status)
+                                KEY status (status),
+                                KEY parent_id (parent_id)
                         ) {$charset_collate};";
 
         $sql[] = "CREATE TABLE {$bp_prefix}bp_groups_members (

src/bp-core/admin/bp-core-admin-settings.php

@@ -192 +192 @@
 }
 
 /**
+ * Allow hierarchical groups.
+ *
+ * @since 2.7.0
+ *
+ */
+function bp_admin_setting_callback_allow_hierarchical_groups() {
+?>
+
+        <input id="bp_allow_hierarchical_groups" name="bp_allow_hierarchical_groups" type="checkbox" value="1" <?php checked(bp_allow_hierarchical_groups() ); ?> />
+        <label for="bp_allow_hierarchical_groups"><?php _e( 'Allow hierarchical groups', 'buddypress' ); ?></label>
+        <p class="description"><?php _e( 'Allow groups to be associated with a parent group.', 'buddypress' ); ?></p>
+
+<?php
+}
+
+/**
  * 'Enable group avatars' field markup.
  *
  * @since 2.3.0

src/bp-core/bp-core-caps.php

@@ -277 +277 @@
                 $blog_id = bp_get_root_blog_id();
         }
 
-        $args   = array( $blog_id, $capability, $args );
-        $retval = call_user_func_array( 'current_user_can_for_blog', $args );
+        $retval = call_user_func_array( 'current_user_can_for_blog', array( $blog_id, $capability, $args ) );
 
         /**
          * Filters whether or not the current user has a given capability.
@@ -319 +318 @@
         }
 
         $switched = is_multisite() ? switch_to_blog( $site_id ) : false;
-        $args     = array( $user_id, $capability, $args );
-        $retval   = call_user_func_array( 'user_can', $args );
+        $retval   = call_user_func_array( 'user_can', array( $user_id, $capability, $args ) );
 
         /**
          * Filters whether or not the specified user has a given capability on a given site.

src/bp-core/bp-core-options.php

@@ -719 +719 @@
 }
 
 /**
+ * Are hierarchical groups allowed?
+ *
+ * @since 2.7.0
+ *
+ * @param bool $default Optional. Fallback value if not found in the database.
+ *                      Default: false.
+ * @return bool True if hierarchical groups are allowed, otherwise false.
+ */
+function bp_allow_hierarchical_groups( $default = false ) {
+
+        /**
+         * Filters whether or not hierarchical groups are allowed.
+         *
+         * @since 2.7.0
+         *
+         * @param bool $value Whether or not hierarchical groups are allowed.
+         */
+        return (bool) apply_filters( 'bp_allow_hierarchical_groups', (bool) bp_get_option( 'bp_allow_hierarchical_groups', $default ) );
+}
+
+/**
  * Should the old BuddyBar be forced in place of the WP admin bar?
  *
  * @since 1.6.0

src/bp-core/bp-core-template.php

@@ -2786 +2786 @@
 }
 
 /**
+ * Is the current page a group's subgroup directory?
+ *
+ * Eg http://example.com/groups/mygroup/hierarchy/.
+ *
+ * @since 2.7.0
+ *
+ * @return bool True if the current page is a group's directory of subgroups.
+ */
+function bp_is_group_subgroups() {
+        return (bool) ( bp_is_groups_component() && bp_is_current_action( 'hierarchy' ) );
+}
+
+/**
  * Is the current page a group's Invites page?
  *
  * Eg http://example.com/groups/mygroup/send-invites/.

src/bp-core/bp-core-update.php

@@ -508 +508 @@
  * 2.7.0 update routine.
  *
  * - Add email unsubscribe salt.
+ * - Add `parent_id` column to groups table.
  *
  * @since 2.7.0
  */
 function bp_update_to_2_7() {
         bp_add_option( 'bp-emails-unsubscribe-salt', base64_encode( wp_generate_password( 64, true, true ) ) );
+
+        /*
+         * Also handled by `bp_core_install()`.
+         * Add `parent_id` column to groups table.
+         */
+        if ( bp_is_active( 'groups' ) ) {
+                bp_core_install_groups();
+        }
 }
 
 /**

src/bp-core/classes/class-bp-admin.php

@@ -429 +429 @@
                         add_settings_field( 'bp_restrict_group_creation', __( 'Group Creation', 'buddypress' ), 'bp_admin_setting_callback_group_creation',   'buddypress', 'bp_groups' );
                         register_setting( 'buddypress', 'bp_restrict_group_creation', 'intval' );
 
+                        // Allow hierarchical groups.
+                        add_settings_field( 'bp_allow_hierarchical_groups', __( 'Hierarchical Groups', 'buddypress' ), 'bp_admin_setting_callback_allow_hierarchical_groups',   'buddypress', 'bp_groups' );
+                        register_setting( 'buddypress', 'bp_allow_hierarchical_groups', 'intval' );
+
                         // Allow group avatars.
                         add_settings_field( 'bp-disable-group-avatar-uploads', __( 'Group Photo Uploads', 'buddypress' ), 'bp_admin_setting_callback_group_avatar_uploads', 'buddypress', 'bp_groups' );
                         register_setting( 'buddypress', 'bp-disable-group-avatar-uploads', 'intval' );

src/bp-groups/bp-groups-actions.php

@@ -205 +205 @@
                         elseif ( 'hidden' == $_POST['group-status'] )
                                 $group_status = 'hidden';
 
-                        if ( !$bp->groups->new_group_id = groups_create_group( array( 'group_id' => $bp->groups->new_group_id, 'status' => $group_status, 'enable_forum' => $group_enable_forum ) ) ) {
+                        // Hierarchical groups: Setting the parent ID.
+                        $parent_id = 0;
+                        if ( bp_allow_hierarchical_groups() && isset( $_POST['parent-id'] ) ) {
+                                $parent_id = intval( $_POST['parent-id'] );
+                        }
+
+                        if ( !$bp->groups->new_group_id = groups_create_group( array( 'group_id' => $bp->groups->new_group_id, 'status' => $group_status, 'enable_forum' => $group_enable_forum, 'parent_id' => $parent_id ) ) ) {
                                 bp_core_add_message( __( 'There was an error saving group details. Please try again.', 'buddypress' ), 'error' );
                                 bp_core_redirect( trailingslashit( bp_get_groups_directory_permalink() . 'create/step/' . bp_get_groups_current_create_step() ) );
                         }
@@ -566 +572 @@
         ) );
 }
 add_action( 'bp_actions', 'groups_action_group_feed' );
+
+/**
+ * Update orphaned child groups when the parent is deleted.
+ *
+ * @since 2.7.0
+ *
+ * @param BP_Groups_Group $group Instance of the group item being deleted.
+ */
+function bp_update_orphaned_groups_on_group_delete( $group ) {
+        // Get child groups and set the parent to the deleted parent's parent.
+        $grandparent_group_id = ! empty( $group->parent_id ) ? $group->parent_id : 0;
+        $children = bp_groups_get_child_groups( $group->id );
+
+        foreach ( $children as $cgroup ) {
+                $child_group = groups_get_group( array( 'group_id' => $cgroup->id ) );
+                $child_group->parent_id = $grandparent_group_id;
+                $child_group->save();
+        }
+}
+add_action( 'bp_groups_delete_group', 'bp_update_orphaned_groups_on_group_delete', 10, 2 );
+
+/**
+ * Save a group's allowed_subgroup_creators setting as group metadata.
+ *
+ * @since 2.7.0
+ *
+ * @param int    $group_id   ID of the group to update.
+ */
+function bp_groups_settings_save_allowed_subgroups_creators( $group_id ) {
+        if ( bp_allow_hierarchical_groups() &&
+                 isset( $_POST['allowed-subgroup-creators'] ) &&
+                 in_array( $_POST['allowed-subgroup-creators'], array( 'noone', 'admin', 'mod', 'member' ) ) ) {
+                groups_update_groupmeta( $group_id, 'allowed_subgroup_creators', $_POST['allowed-subgroup-creators'] );
+        }
+}
+add_action( 'groups_group_settings_edited', 'bp_groups_settings_save_allowed_subgroups_creators' );
+add_action( 'bp_group_admin_edit_after', 'bp_groups_settings_save_allowed_subgroups_creators' );
+
+/**
+ * Save a group's allowed_subgroup_creators setting from the create group screen.
+ *
+ * @since 2.7.0
+ */
+function bp_groups_create_step_save_allowed_subgroups_creators() {
+        $group_id = buddypress()->groups->new_group_id;
+        bp_groups_settings_save_allowed_subgroups_creators( $group_id );
+}
+add_action( 'groups_create_group_step_save_group-settings', 'bp_groups_create_step_save_allowed_subgroups_creators' );

src/bp-groups/bp-groups-admin.php

@@ -278 +278 @@
                 $allowed_invite_status = apply_filters( 'groups_allowed_invite_status', array( 'members', 'mods', 'admins' ) );
                 $invite_status         = in_array( $_POST['group-invite-status'], (array) $allowed_invite_status ) ? $_POST['group-invite-status'] : 'members';
 
-                if ( !groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status ) ) {
+                // Set a parent group ID.
+                $parent_id = ( isset( $_POST['parent-id'] ) ) ? (int) $_POST['parent-id'] : 0;
+
+                if ( !groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status, $parent_id ) ) {
                         $error = $group_id;
                 }
 
@@ -826 +829 @@
                 </fieldset>
         </div>
 
+        <?php if ( bp_allow_hierarchical_groups() ) : ?>
+                <div class="bp-groups-settings-section" id="bp-groups-settings-section-group-hierarchy">
+                        <fieldset>
+                                <legend><?php _e( 'Parent Group', 'buddypress' ); ?></legend>
+
+                                <?php
+                                $current_parent_group_id = bp_groups_get_parent_group_id( $item->id );
+                                $possible_parent_groups = bp_groups_get_possible_parent_groups( $item->id, bp_loggedin_user_id() );
+                                if ( $possible_parent_groups ) :
+                                        ?>
+                                        <select name="parent-id">
+                                                <option value="0" <?php selected( 0, $current_parent_group_id ); ?>><?php echo _x( 'None selected', 'The option that sets a group to be a top-level group and have no parent.', 'buddypress' ); ?></option>
+                                        <?php foreach ( $possible_parent_groups as $possible_parent_group ) {
+                                                ?>
+                                                <option value="<?php echo $possible_parent_group->id; ?>" <?php selected( $current_parent_group_id, $possible_parent_group->id ); ?>><?php echo $possible_parent_group->name; ?></option>
+                                                <?php
+                                        }
+                                        ?>
+                                        </select>
+                                        <?php
+                                else :
+                                        ?>
+                                        <p><?php echo __( 'There are no groups available to be a parent to this group.', 'buddypress' ); ?></p>
+                                        <?php
+                                endif;
+                                ?>
+                        </fieldset>
+
+                        <fieldset>
+
+                                <legend><?php _e( 'Which members of this group are allowed to create subgroups?', 'buddypress' ); ?></legend>
+
+                                <?php
+                                $subgroup_creators = groups_get_groupmeta( $item->id, 'allowed_subgroup_creators' );
+                                if ( ! $subgroup_creators ) {
+                                        $subgroup_creators = 'noone';
+                                }
+                                ?>
+                                <ul>
+                                        <li><label for="allowed-subgroup-creators-members"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-members" value="member" <?php checked( $subgroup_creators, 'member' ); ?> /> <?php _e( 'All group members', 'buddypress' ); ?></label></li>
+
+                                        <li><label for="allowed-subgroup-creators-mods"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-mods" value="mod" <?php checked( $subgroup_creators, 'mod' ); ?> /> <?php _e( 'Group admins and mods only', 'buddypress' ); ?></label></li>
+
+                                        <li><label for="allowed-subgroup-creators-admins"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-admins" value="admin" <?php checked( $subgroup_creators, 'admin' ); ?> /> <?php _e( 'Group admins only', 'buddypress' ); ?></label></li>
+
+                                        <li><label for="allowed-subgroup-creators-noone"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-noone" value="noone" <?php checked( $subgroup_creators, 'noone' ); ?> /> <?php _e( 'No one', 'buddypress' ); ?></label></li>
+                                </ul>
+                        </fieldset>
+                </div>
+        <?php endif; ?>
 <?php
 }
 

src/bp-groups/bp-groups-cache.php

@@ -70 +70 @@
  */
 function bp_groups_delete_group_cache( $group_id = 0 ) {
         wp_cache_delete( $group_id, 'bp_groups' );
+        wp_cache_delete( 'last_changed', 'bp_groups' );
 }
 add_action( 'groups_delete_group',     'bp_groups_delete_group_cache' );
 add_action( 'groups_update_group',     'bp_groups_delete_group_cache' );

src/bp-groups/bp-groups-filters.php

@@ -346 +346 @@
 
         return $avatar;
 }
+
+
+/**
+ * Determine whether the current user can create a subgroup of a particular group.
+ *
+ * @since 2.7.0
+ *
+ * @param bool   $retval     Whether or not the current user has the capability.
+ * @param string $capability The capability being checked for.
+ * @param int    $site_id    Site ID. Defaults to the BP root blog.
+ * @param array  $args       Array of extra arguments passed.
+ *
+ * @return bool
+ */
+function bp_groups_current_user_can_create_subgroups( $retval, $capability, $site_id, $args ) {
+        if ( 'create_subgroups' != $capability ) {
+                return $retval;
+        }
+
+        $user_id = bp_loggedin_user_id();
+        return bp_groups_user_can_create_subgroups( $retval, $user_id, $capability, $site_id, $args );
+}
+add_filter( 'bp_current_user_can', 'bp_groups_current_user_can_create_subgroups', 10, 4 );
+
+/**
+ * Determine whether a specific user can create a subgroup of a particular group.
+ *
+ * @since 2.7.0
+ *
+ * @param bool   $retval     Whether or not the current user has the capability.
+ * @param int    $user_id    ID of user to check.
+ * @param string $capability The capability being checked for.
+ * @param int    $site_id    Site ID. Defaults to the BP root blog.
+ * @param array  $args       Array of extra arguments passed.
+ *
+ * @return bool
+ */
+function bp_groups_user_can_create_subgroups( $retval, $user_id, $capability, $site_id, $args ) {
+        if ( 'create_subgroups' != $capability ) {
+                return $retval;
+        }
+
+        if ( ! bp_allow_hierarchical_groups() ) {
+                return false;
+        }
+
+        // We need to know which group is in question.
+        if ( empty( $args['group_id'] ) ) {
+                return false;
+        }
+        $group_id = (int) $args['group_id'];
+
+        // Possible settings for the group meta setting 'allowed_subgroup_creators'
+        $creator_setting = groups_get_groupmeta( $group_id, 'allowed_subgroup_creators' );
+        switch ( $creator_setting ) {
+                case 'admin' :
+                        $retval = groups_is_user_admin( $user_id, $group_id );
+                        break;
+
+                case 'mod' :
+                        $retval = ( groups_is_user_mod( $user_id, $group_id ) ||
+                                                groups_is_user_admin( $user_id, $group_id ) );
+                        break;
+
+                case 'member' :
+                        $retval = groups_is_user_member( $user_id, $group_id );
+                        break;
+
+                case 'noone' :
+                default :
+                        // @TODO: This seems weird, but I can imagine situations where only site admins should be able to associate groups.
+                        $retval = bp_user_can( $user_id, 'bp_moderate' );
+                        break;
+        }
+
+        return $retval;
+}
+add_filter( 'bp_user_can', 'bp_groups_user_can_create_subgroups', 10, 5 );

src/bp-groups/bp-groups-functions.php

@@ -87 +87 @@
  *     @type string   $slug         The group slug.
  *     @type string   $status       The group's status. Accepts 'public', 'private' or
  *                                  'hidden'. Defaults to 'public'.
+ *     @type int      $parent_id    The ID of the parent group. Default: 0.
  *     @type int      $enable_forum Optional. Whether the group has a forum enabled.
  *                                  If the legacy forums are enabled for this group
  *                                  or if a bbPress forum is enabled for the group,
@@ -105 +106 @@
                 'description'  => '',
                 'slug'         => '',
                 'status'       => 'public',
+                'parent_id'    => 0,
                 'enable_forum' => 0,
                 'date_created' => bp_core_current_time()
         );
@@ -151 +153 @@
         $group->description  = $description;
         $group->slug         = $slug;
         $group->status       = $status;
+        $group->parent_id    = $parent_id;
         $group->enable_forum = (int) $enable_forum;
         $group->date_created = $date_created;
 
@@ -270 +273 @@
  *                                   to the group. 'members', 'mods', or 'admins'.
  * @return bool True on success, false on failure.
  */
-function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false ) {
+function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false, $parent_id = false ) {
 
         $group = groups_get_group( array( 'group_id' => $group_id ) );
         $group->enable_forum = $enable_forum;
@@ -285 +288 @@
         // Now update the status.
         $group->status = $status;
 
+        // Update the parent ID if necessary.
+        if ( false !== $parent_id ) {
+                $group->parent_id = $parent_id;
+        }
+
         if ( !$group->save() )
                 return false;
 
@@ -703 +711 @@
                 'user_id'            => false,          // Pass a user_id to limit to only groups that this user is a member of.
                 'include'            => false,          // Only include these specific groups (group_ids).
                 'exclude'            => false,          // Do not include these specific groups (group_ids).
+                'parent_id'          => false,          // Get groups that are children of the specified group(s).
                 'search_terms'       => false,          // Limit to groups that match these search terms.
                 'group_type'         => '',
                 'group_type__in'     => '',
@@ -722 +731 @@
                 'user_id'            => $r['user_id'],
                 'include'            => $r['include'],
                 'exclude'            => $r['exclude'],
+                'parent_id'          => $r['parent_id'],
                 'search_terms'       => $r['search_terms'],
                 'group_type'         => $r['group_type'],
                 'group_type__in'     => $r['group_type__in'],
@@ -2393 +2403 @@
         bp_groups_set_group_type( $group_id, '' );
 }
 add_action( 'groups_delete_group', 'bp_remove_group_type_on_group_delete' );
+
+// Hierarchical groups
+
+/**
+ * Get the child groups for a specific group.
+ *
+ * To return all child groups, leave the $user_id parameter empty. To return
+ * only those child groups visible to a specific user, specify a $user_id.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return array Array of group objects.
+ */
+function bp_groups_get_child_groups( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        // @TODO: Do we need to check whether the specified user can see the parent group in question?
+
+        // Check the cache first.
+        $last_changed = wp_cache_get( 'last_changed', 'bp_groups' );
+        if ( false === $last_changed ) {
+                $last_changed = microtime();
+                wp_cache_set( 'last_changed', $last_changed, 'bp_groups' );
+        }
+
+        $cache_key = 'bp_groups_child_groups_of_' . $group_id . '_' . $last_changed;
+        $children  = wp_cache_get( $cache_key, 'bp_groups' );
+
+        if ( false === $children ) {
+                // Fetch all child groups.
+                $child_args = array(
+                        'parent_id' => $group_id,
+                        'show_hidden' => true,
+                );
+                $children = groups_get_groups( $child_args );
+                $children = $children['groups'];
+
+                // Set the cache to avoid duplicate requests.
+                wp_cache_set( $cache_key, $children, 'bp_groups' );
+        }
+
+        // If a user ID has been specified, we filter hidden groups accordingly.
+        if ( false !== $user_id && ! bp_user_can( $user_id, 'bp_moderate' ) ) {
+                foreach ( $children as $k => $group ) {
+                        // Check whether the user should be able to see this group.
+                        // @TODO: Use group capabilities for this when possible.
+                        if ( 'hidden' == $group->status && ! groups_is_user_member( $user_id, $group->id ) ) {
+                                unset( $children[$k] );
+                        }
+                }
+        }
+
+        return $children;
+}
+
+/**
+ * Get the child group IDs for a specific group.
+ *
+ * To return all child groups, leave the $user_id parameter empty. To return
+ * only those child groups visible to a specific user, specify a $user_id.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return array Array of group IDs.
+ */
+function bp_groups_get_child_group_ids( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        $child_groups    = bp_groups_get_child_groups( $group_id, $user_id );
+        $child_group_ids = wp_list_pluck( $child_groups, 'id' );
+
+        // Convert IDs to integers.
+        return array_map( 'intval', $child_group_ids );
+}
+
+/**
+ * Does a specific group have child groups?
+ *
+ * To check for the actual existence of child groups, leave the $user_id
+ * parameter empty. To check whether any exist that are visible to a user,
+ * supply a $user_id.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return bool True if true, false if not.
+ */
+function bp_groups_has_children( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 finds all top-level groups, which could be
+         * intentional. Try to find the current group only when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return false;
+                }
+        }
+
+        $children = bp_groups_get_child_groups( $group_id, $user_id );
+        return ! empty ( $children ) ? true : false;
+}
+
+/**
+ * Get all groups that are descendants of a specific group.
+ *
+ * To return all descendent groups, leave the $user_id parameter empty. To return
+ * only those child groups visible to a specific user, specify a $user_id.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return array Array of group objects.
+ */
+function bp_groups_get_descendent_groups( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        // Check the cache first.
+        $last_changed = wp_cache_get( 'last_changed', 'bp_groups' );
+        if ( false === $last_changed ) {
+                $last_changed = microtime();
+                wp_cache_set( 'last_changed', $last_changed, 'bp_groups' );
+        }
+
+        $cache_key   = 'bp_groups_descendants_of_' . $group_id . '_' . $last_changed;
+        $descendants = wp_cache_get( $cache_key, 'bp_groups' );
+
+        if ( false === $descendants ) {
+                // Start from the group specified.
+                $parents = array( $group_id );
+                $descendants = array();
+
+                // We work down the tree until no new children are found.
+                while ( $parents ) {
+                        // Fetch all child groups.
+                        $child_args = array(
+                                'parent_id' => $parents,
+                                'show_hidden' => true,
+                        );
+                        $children = groups_get_groups( $child_args );
+
+                        // Add groups to the set of found groups.
+                        $descendants = array_merge( $descendants, $children['groups'] );
+
+                        // Set up the next set of parents.
+                        $parents = wp_list_pluck( $children['groups'], 'id' );
+                }
+
+                // Set the cache to avoid duplicate requests.
+                wp_cache_set( $cache_key, $descendants, 'bp_groups' );
+        }
+
+        // If a user ID has been specified, we filter hidden groups accordingly.
+        if ( false !== $user_id && ! bp_user_can( $user_id, 'bp_moderate' ) ) {
+                foreach ( $descendants as $k => $group ) {
+                        // Check whether the user should be able to see this group.
+                        // @TODO: Use group capabilities for this when possible.
+                        if ( 'hidden' == $group->status && ! groups_is_user_member( $user_id, $group->id ) ) {
+                                unset( $descendants[$k] );
+                        }
+                }
+        }
+
+        return $descendants;
+}
+
+/**
+ * Get the parent group ID for a specific group.
+ *
+ * To return the parent group regardless of visibility, leave the $user_id
+ * parameter empty. To return the parent only when visible to a specific user,
+ * specify a $user_id.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return int ID of parent group.
+ */
+function bp_groups_get_parent_group_id( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        $group     = groups_get_group( array( 'group_id' => $group_id ) );
+        $parent_id = $group->parent_id;
+
+        // If the user is specified, is the parent group visible to that user?
+        // @TODO: This could make use of group visibility when available.
+        if ( false !== $user_id && ! bp_user_can( $user_id, 'bp_moderate' ) ) {
+                $parent_group = groups_get_group( array( 'group_id' => $parent_id) );
+                if ( 'hidden' == $parent_group->status && ! groups_is_user_member( $user_id, $parent_group->id ) ) {
+                        // If the group is not visible to the user, break the chain.
+                        $parent_id = 0;
+                }
+        }
+
+        return (int) $parent_id;
+}
+
+/**
+ * Get an array of group ids that are ancestors of a specific group.
+ *
+ * To return all ancestor groups, leave the $user_id parameter empty. To return
+ * only those ancestor groups visible to a specific user, specify a $user_id.
+ * Note that if groups the user can't see are encountered, the chain of ancestry
+ * is stopped. Also note that the order here is useful: the first element is the
+ * parent group id, the second is the grandparent group id and so on.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return array Array of group objects.
+ */
+function bp_groups_get_ancestor_group_ids( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( $group_id === false ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        $ancestors = array();
+
+        // We work up the tree until no new parent is found.
+        while ( $group_id ) {
+                $parent_group_id = bp_groups_get_parent_group_id( $group_id, $user_id );
+                if ( $parent_group_id ) {
+                        $ancestors[] = $parent_group_id;
+                }
+                // Set a new group id to work from.
+                $group_id = $parent_group_id;
+        }
+
+        return $ancestors;
+}
+
+/**
+ * Get an array of possible parent group ids for a specific group and user.
+ *
+ * To be a candidate for group parenthood, the group cannot be a descendent of
+ * this group, and the user must be allowed to create child groups in that group.
+ *
+ * @since 2.7.0
+ *
+ * @param  int   $group_id ID of the group.
+ * @param  int   $user_id  ID of a user to check group visibility for.
+ *
+ * @return array Array of group objects.
+ */
+function bp_groups_get_possible_parent_groups( $group_id = false, $user_id = false ) {
+        /*
+         * Passing a group id of 0 would find all top-level groups, which could be
+         * intentional. We only try to find the current group when the $group_id is false.
+         */
+        if ( false === $group_id ) {
+                $group_id = bp_get_current_group_id();
+                if ( ! $group_id ) {
+                        // If we can't resolve the group_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        if ( false === $user_id ) {
+                $user_id = bp_loggedin_user_id();
+                if ( ! $user_id ) {
+                        // If we can't resolve the user_id, don't proceed with a zero value.
+                        return array();
+                }
+        }
+
+        // First, get a list of descendants (don't pass a user id--we want them all).
+        $descendants = bp_groups_get_descendent_groups( $group_id );
+        $exclude_ids = wp_list_pluck( $descendants, 'id' );
+        // Also exclude the current group.
+        $exclude_ids[] = $group_id;
+
+        // Make sure to exclude descendent groups.
+        $args = array(
+                'orderby'            => 'name',
+                'order'              => 'ASC',
+                'populate_extras'    => false,
+                'exclude'            => $exclude_ids,
+                'show_hidden'        => true,
+        );
+        // If the user is not a site admin, limit the set to groups she belongs to.
+        if ( ! bp_user_can( $user_id, 'bp_moderate' ) ) {
+                $args['user_id'] = $user_id;
+        }
+        $possible_parents = groups_get_groups( $args );
+        foreach ( $possible_parents['groups'] as $k => $group ) {
+                // Check whether the user can create child groups of this group.
+                if ( ! bp_user_can( $user_id, 'create_subgroups', array( 'group_id' => $group->id ) ) ) {
+                        unset( $possible_parents['groups'][$k] );
+                }
+        }
+
+        return $possible_parents['groups'];
+}

src/bp-groups/bp-groups-screens.php

@@ -608 +608 @@
 }
 
 /**
+ * Handle the display of a group's subgroup directory.
+ *
+ * @since 2.7.0
+ */
+function groups_screen_subgroup_directory() {
+
+        if ( ! bp_is_single_item() )
+                return false;
+
+        /**
+         * Fires before the loading of a group's subgroups page.
+         *
+         * @since 2.7.0
+         *
+         * @param int $id ID of the group whose subgroups are being displayed.
+         */
+        do_action( 'groups_screen_subgroup_directory', bp_get_current_group_id() );
+
+        /**
+         * Filters the template to load for a group's subgroups page.
+         *
+         * @since 2.7.0
+         *
+         * @param string $value Path to a group's subgroups template.
+         */
+        bp_core_load_template( apply_filters( 'groups_template_subgroup_directory', 'groups/single/home' ) );
+}
+
+/**
  * Handle the display of a group's Send Invites page.
  *
  * @since 1.0.0
@@ -911 +940 @@
                 $allowed_invite_status = apply_filters( 'groups_allowed_invite_status', array( 'members', 'mods', 'admins' ) );
                 $invite_status         = isset( $_POST['group-invite-status'] ) && in_array( $_POST['group-invite-status'], (array) $allowed_invite_status ) ? $_POST['group-invite-status'] : 'members';
 
+                // Set a parent group ID.
+                $parent_id = ( isset( $_POST['parent-id'] ) ) ? (int) $_POST['parent-id'] : 0;
+
                 // Check the nonce.
                 if ( !check_admin_referer( 'groups_edit_group_settings' ) )
                         return false;
 
-                if ( !groups_edit_group_settings( $_POST['group-id'], $enable_forum, $status, $invite_status ) ) {
+                if ( !groups_edit_group_settings( $_POST['group-id'], $enable_forum, $status, $invite_status, $parent_id ) ) {
                         bp_core_add_message( __( 'There was an error updating group settings. Please try again.', 'buddypress' ), 'error' );
                 } else {
                         bp_core_add_message( __( 'Group settings were successfully updated.', 'buddypress' ) );

src/bp-groups/bp-groups-template.php

@@ -137 +137 @@
  *                                            about groups. Default: true.
  *     @type array|string $exclude            Array or comma-separated list of group IDs. Results will exclude
  *                                            the listed groups. Default: false.
+ *     @type array|string $parent_id          Array or comma-separated list of group IDs. Results will include only
+ *                                            child groups of the listed groups. Default: false.
  *     @type bool         $update_meta_cache  Whether to fetch groupmeta for queried groups. Default: true.
  * }
  * @return bool True if there are groups to display that match the params
@@ -150 +152 @@
         $slug         = false;
         $type         = '';
         $search_terms = false;
+        $parent_id    = false;
 
         // When looking your own groups, check for two action variables.
         if ( bp_is_current_action( 'my-groups' ) ) {
@@ -198 +201 @@
                 'meta_query'         => false,
                 'include'            => false,
                 'exclude'            => false,
+                'parent_id'          => $parent_id,
                 'populate_extras'    => true,
                 'update_meta_cache'  => true,
         ), 'has_groups' );
@@ -221 +225 @@
                 'meta_query'         => $r['meta_query'],
                 'include'            => $r['include'],
                 'exclude'            => $r['exclude'],
+                'parent_id'          => $r['parent_id'],
                 'populate_extras'    => (bool) $r['populate_extras'],
                 'update_meta_cache'  => (bool) $r['update_meta_cache'],
         ) );
@@ -770 +775 @@
         }
 
 /**
+ * Output the permalink breadcrumbs for the current group in the loop.
+ *
+ * @since 2.7.0
+ *
+ * @param object|bool $group Optional. Group object.
+ *                           Default: current group in loop.
+ * @param string      $separator String to place between group links.
+ */
+function bp_group_permalink_breadcrumbs( $group = false, $separator = ' / ' ) {
+        echo bp_get_group_permalink_breadcrumbs( $group, $separator );
+}
+        /**
+         * Return the permalink breadcrumbs for the current group in the loop.
+         *
+         * @since 2.7.0
+         *
+         * @param object|bool $group Optional. Group object.
+         *                           Default: current group in loop.
+     * @param string      $separator String to place between group links.
+     *
+         * @return string
+         */
+        function bp_get_group_permalink_breadcrumbs( $group = false, $separator = ' / ' ) {
+                global $groups_template;
+
+                if ( empty( $group ) ) {
+                        $group = $groups_template->group;
+                }
+
+                // Create the base group's entry.
+                $item = '<a href="' . bp_get_group_permalink() . '">' . bp_get_group_name() . '</a>';
+                $breadcrumbs = array( $item );
+                $parent_id   = bp_groups_get_parent_group_id( $group->id, bp_loggedin_user_id() );
+
+                // Add breadcrumbs for the ancestors.
+                while ( $parent_id ) {
+                        $parent_group = groups_get_group( array( 'group_id' => $parent_id ) );
+                        $breadcrumbs[] = '<a href="' . bp_get_group_permalink( $parent_group ) . '">' . bp_get_group_name( $parent_group ) . '</a>';
+                        $parent_id   = bp_groups_get_parent_group_id( $parent_group->id, bp_loggedin_user_id() );
+                }
+
+                $breadcrumbs = implode( $separator, array_reverse( $breadcrumbs ) );
+
+                /**
+                 * Filters the permalink for the current group in the loop.
+                 *
+                 * @since 2.7.0
+                 *
+                 * @param string $breadcrumb String of breadcrumb links.
+                 * @param object $group Group object.
+                 */
+                return apply_filters( 'bp_get_group_permalink_breadcrumbs', $breadcrumbs, $group );
+        }
+
+/**
  * Output the permalink for the admin section of the current group in the loop.
  *
  * @since 1.0.0

src/bp-groups/classes/class-bp-groups-component.php

@@ -603 +603 @@
                                 );
                         }
 
+                        // Include the hierarchy item if there are groups to show or the user can create new subgroups.
+                        if ( bp_current_user_can( 'create_subgroups', array( 'group_id' => $this->current_group->id ) ) ||
+                                 bp_groups_has_children( $this->current_group->id, bp_loggedin_user_id() ) ) {
+                                $sub_nav[] = array(
+                                        'name'            => _x( 'Member Groups', 'Subgroup directory screen nav', 'buddypress' ),
+                                        'slug'            => 'hierarchy',
+                                        'parent_url'      => $group_link,
+                                        'parent_slug'     => $this->current_group->slug,
+                                        'screen_function' => 'groups_screen_subgroup_directory',
+                                        'item_css_id'     => 'hierarchy',
+                                        'position'        => 61,
+                                        'user_has_access' => $this->current_group->user_has_access,
+                                        'no_access_url'   => $group_link,
+                                );
+                        }
+
                         if ( bp_is_active( 'friends' ) && bp_groups_user_can_send_invites() ) {
                                 $sub_nav[] = array(
                                         'name'            => _x( 'Send Invites', 'My Group screen nav', 'buddypress' ),

src/bp-groups/classes/class-bp-groups-group.php

@@ -68 +68 @@
         public $status;
 
         /**
+         * Parent ID.
+         *
+         * ID of parent group, if applicable.
+         *
+         * @since 2.7.0
+         * @var int
+         */
+        public $parent_id;
+
+        /**
          * Should (legacy) bbPress forums be enabled for this group?
          *
          * @since 1.6.0
@@ -214 +224 @@
                 $this->slug         = $group->slug;
                 $this->description  = stripslashes( $group->description );
                 $this->status       = $group->status;
+                $this->parent_id    = $group->parent_id;
                 $this->enable_forum = $group->enable_forum;
                 $this->date_created = $group->date_created;
 
@@ -282 +293 @@
                 $this->slug         = apply_filters( 'groups_group_slug_before_save',         $this->slug,         $this->id );
                 $this->description  = apply_filters( 'groups_group_description_before_save',  $this->description,  $this->id );
                 $this->status       = apply_filters( 'groups_group_status_before_save',       $this->status,       $this->id );
+                $this->parent_id    = apply_filters( 'groups_group_parent_id_before_save',    $this->parent_id,    $this->id );
                 $this->enable_forum = apply_filters( 'groups_group_enable_forum_before_save', $this->enable_forum, $this->id );
                 $this->date_created = apply_filters( 'groups_group_date_created_before_save', $this->date_created, $this->id );
 
@@ -324 +336 @@
                                         slug = %s,
                                         description = %s,
                                         status = %s,
+                                        parent_id = %d,
                                         enable_forum = %d,
                                         date_created = %s
                                 WHERE
@@ -334 +347 @@
                                         $this->slug,
                                         $this->description,
                                         $this->status,
+                                        $this->parent_id,
                                         $this->enable_forum,
                                         $this->date_created,
                                         $this->id
@@ -346 +360 @@
                                         slug,
                                         description,
                                         status,
+                                        parent_id,
                                         enable_forum,
                                         date_created
                                 ) VALUES (
-                                        %d, %s, %s, %s, %s, %d, %s
+                                        %d, %s, %s, %s, %s, %d, %d, %s
                                 )",
                                         $this->creator_id,
                                         $this->name,
                                         $this->slug,
                                         $this->description,
                                         $this->status,
+                                        $this->parent_id,
                                         $this->enable_forum,
                                         $this->date_created
                         );
@@ -710 +726 @@
          *                                            See {@link WP_Meta_Query::queries} for description.
          *     @type array|string $value              Optional. Array or comma-separated list of group IDs. Results
          *                                            will be limited to groups within the list. Default: false.
+         *     @type array|string $parent_id          Optional. Array or comma-separated list of group IDs. Results
+         *                                            will be limited to children of the specified groups. Default: false.
          *     @type bool         $populate_extras    Whether to fetch additional information
          *                                            (such as member count) about groups. Default: true.
          *     @type array|string $exclude            Optional. Array or comma-separated list of group IDs.
@@ -761 +779 @@
                         'group_type__not_in' => '',
                         'meta_query'         => false,
                         'include'            => false,
+                        'parent_id'          => false,
                         'populate_extras'    => true,
                         'update_meta_cache'  => true,
                         'exclude'            => false,
@@ -835 +854 @@
                         $sql['include'] = " AND g.id IN ({$include})";
                 }
 
+                if ( ! empty( $r['parent_id'] ) ) {
+                        $parent_id        = implode( ',', wp_parse_id_list( $r['parent_id'] ) );
+                        $sql['parent_id'] = " AND g.parent_id IN ({$parent_id})";
+                }
+
                 if ( ! empty( $r['exclude'] ) ) {
                         $exclude        = implode( ',', wp_parse_id_list( $r['exclude'] ) );
                         $sql['exclude'] = " AND g.id NOT IN ({$exclude})";
@@ -948 +972 @@
                 }
 
                 // Already escaped in the paginated results block.
+                if ( ! empty( $parent_id ) ) {
+                        $total_sql['where'][] = "g.parent_id IN ({$parent_id})";
+                }
+
+                // Already escaped in the paginated results block.
                 if ( ! empty( $exclude ) ) {
                         $total_sql['where'][] = "g.id NOT IN ({$exclude})";
                 }

src/bp-groups/classes/class-bp-groups-template.php

@@ -165 +165 @@
                         'slug'               => false,
                         'include'            => false,
                         'exclude'            => false,
+                        'parent_id'          => false,
                         'search_terms'       => '',
                         'group_type'         => '',
                         'group_type__in'     => '',
@@ -226 +227 @@
                                 'group_type__not_in' => $group_type__not_in,
                                 'include'            => $include,
                                 'exclude'            => $exclude,
+                                'parent_id'          => $parent_id,
                                 'populate_extras'    => $populate_extras,
                                 'update_meta_cache'  => $update_meta_cache,
                                 'show_hidden'        => $show_hidden,

src/bp-templates/bp-legacy/buddypress/groups/single/admin.php

@@ -145 +145 @@
 
         <hr />
 
+        <?php if ( bp_allow_hierarchical_groups() ) : ?>
+
+                <h4><?php _e( 'Group Hierarchy', 'buddypress' ); ?></h4>
+
+                <label for="parent_id">Parent Group</label>
+                        <?php
+                        $current_parent_group_id = bp_groups_get_parent_group_id();
+                        $possible_parent_groups = bp_groups_get_possible_parent_groups( bp_get_current_group_id(), bp_loggedin_user_id() );
+                        if ( $possible_parent_groups ) :
+                                ?>
+                                <select name="parent-id">
+                                        <option value="0" <?php selected( 0, $current_parent_group_id ); ?>><?php echo _x( 'None selected', 'The option that sets a group to be a top-level group and have no parent.', 'buddypress' ); ?></option>
+                                <?php foreach ( $possible_parent_groups as $possible_parent_group ) {
+                                        ?>
+                                        <option value="<?php echo $possible_parent_group->id; ?>" <?php selected( $current_parent_group_id, $possible_parent_group->id ); ?>><?php echo $possible_parent_group->name; ?></option>
+                                        <?php
+                                }
+                                ?>
+                                </select>
+                                <?php
+                        else :
+                                ?>
+                                <p><?php echo __( 'There are no groups available to be a parent to this group.', 'buddypress' ); ?></p>
+                                <?php
+                        endif;
+                        ?>
+
+                <fieldset class="radio">
+
+                        <legend><?php _e( 'Which members of this group are allowed to create subgroups?', 'buddypress' ); ?></legend>
+
+                        <?php
+                        $subgroup_creators = groups_get_groupmeta( bp_get_current_group_id(), 'allowed_subgroup_creators' );
+                        if ( ! $subgroup_creators ) {
+                                $subgroup_creators = 'noone';
+                        }
+                        ?>
+
+                        <label for="allowed-subgroup-creators-members"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-members" value="member" <?php checked( $subgroup_creators, 'member' ); ?> /> <?php _e( 'All group members', 'buddypress' ); ?></label>
+
+                        <label for="allowed-subgroup-creators-mods"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-mods" value="mod" <?php checked( $subgroup_creators, 'mod' ); ?> /> <?php _e( 'Group admins and mods only', 'buddypress' ); ?></label>
+
+                        <label for="allowed-subgroup-creators-admins"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-admins" value="admin" <?php checked( $subgroup_creators, 'admin' ); ?> /> <?php _e( 'Group admins only', 'buddypress' ); ?></label>
+
+                        <label for="allowed-subgroup-creators-noone"><input type="radio" name="allowed-subgroup-creators" id="allowed-subgroup-creators-noone" value="noone" <?php checked( $subgroup_creators, 'noone' ); ?> /> <?php _e( 'No one', 'buddypress' ); ?></label>
+                </fieldset>
+
+        <hr />
+
+        <?php endif; ?>
+
         <?php
 
         /**

src/bp-templates/bp-legacy/buddypress/groups/single/home.php

@@ -117 +117 @@
                                 elseif ( bp_is_group_members()    ) : bp_groups_members_template_part();
 
                                 // Group Invitations
+                                elseif ( bp_is_group_subgroups()  ) : bp_get_template_part( 'groups/single/subgroups-loop' );
+
+                                // Group Invitations
                                 elseif ( bp_is_group_invites()    ) : bp_get_template_part( 'groups/single/send-invites' );
 
                                 // Old group forums

new file src/bp-templates/bp-legacy/buddypress/groups/single/subgroups-loop.php

@@ +1 @@
+<?php
+/**
+ * BuddyPress - Subgroups Loop
+ *
+ * Querystring is set via AJAX in _inc/ajax.php - bp_legacy_theme_object_filter().
+ *
+ * @package BuddyPress
+ * @subpackage bp-legacy
+ */
+
+?>
+
+<?php
+// Store the groups template global so we can "reset" the loop after this subloop.
+global $groups_template;
+$parent_groups_template = $groups_template;
+
+// @TODO: Add a "create subgroup" button here?
+
+/**
+ * Fires before the display of groups from the groups loop.
+ *
+ * @since 1.2.0
+ */
+do_action( 'bp_before_subgroups_loop' ); ?>
+<?php
+// @TODO: Hidden groups are excluded by default. Showing them all is dangerous.
+// Will be much better when group capabilities are in place that allow granular exclusion of hidden groups.
+// @TODO: Ajax pagination doesn't work.
+?>
+<?php if ( bp_has_groups( bp_ajax_querystring( 'groups' ) . '&type=alphabetical&parent_id=' . bp_get_current_group_id() ) ) : ?>
+
+        <div id="pag-top" class="pagination">
+
+                <div class="pag-count" id="group-dir-count-top">
+
+                        <?php bp_groups_pagination_count(); ?>
+
+                </div>
+
+                <div class="pagination-links" id="group-dir-pag-top">
+
+                        <?php bp_groups_pagination_links(); ?>
+
+                </div>
+
+        </div>
+
+        <?php
+
+        /**
+         * Fires before the listing of the groups list.
+         *
+         * @since 1.1.0
+         */
+        do_action( 'bp_before_directory_subgroups_list' ); ?>
+
+        <ul id="groups-list" class="item-list">
+
+        <?php while ( bp_groups() ) : bp_the_group(); ?>
+
+                <li <?php bp_group_class(); ?>>
+                        <?php if ( ! bp_disable_group_avatar_uploads() ) : ?>
+                                <div class="item-avatar">
+                                        <a href="<?php bp_group_permalink(); ?>"><?php bp_group_avatar( 'type=thumb&width=50&height=50' ); ?></a>
+                                </div>
+                        <?php endif; ?>
+
+                        <div class="item">
+                                <div class="item-title"><a href="<?php bp_group_permalink(); ?>"><?php bp_group_name(); ?></a></div>
+                                <div class="item-meta"><span class="activity"><?php printf( __( 'active %s', 'buddypress' ), bp_get_group_last_active() ); ?></span></div>
+
+                                <div class="item-desc"><?php bp_group_description_excerpt(); ?></div>
+
+                                <?php
+
+                                /**
+                                 * Fires inside the listing of an individual group listing item.
+                                 *
+                                 * @since 1.1.0
+                                 */
+                                do_action( 'bp_directory_groups_item' ); ?>
+
+                        </div>
+
+                        <div class="action">
+
+                                <?php
+
+                                /**
+                                 * Fires inside the action section of an individual group listing item.
+                                 *
+                                 * @since 1.1.0
+                                 */
+                                do_action( 'bp_directory_groups_actions' ); ?>
+
+                                <div class="meta">
+
+                                        <?php bp_group_type(); ?> / <?php bp_group_member_count(); ?>
+
+                                </div>
+
+                        </div>
+
+                        <div class="clear"></div>
+                </li>
+
+        <?php endwhile; ?>
+
+        </ul>
+
+        <?php
+
+        /**
+         * Fires after the listing of the groups list.
+         *
+         * @since 1.1.0
+         */
+        do_action( 'bp_after_directory_groups_list' ); ?>
+
+        <div id="pag-bottom" class="pagination">
+
+                <div class="pag-count" id="group-dir-count-bottom">
+
+                        <?php bp_groups_pagination_count(); ?>
+
+                </div>
+
+                <div class="pagination-links" id="group-dir-pag-bottom">
+
+                        <?php bp_groups_pagination_links(); ?>
+
+                </div>
+
+        </div>
+
+<?php else: ?>
+
+        <div id="message" class="info">
+                <p><?php _e( 'There were no member groups found.', 'buddypress' ); ?></p>
+        </div>
+
+<?php endif; ?>
+
+<?php
+
+/**
+ * Fires after the display of groups from the groups loop.
+ *
+ * @since 1.2.0
+ */
+do_action( 'bp_after_subgroups_loop' );
+
+// Reset the $groups_template global and continue with the main group's
+$groups_template = $parent_groups_template;
+?>

tests/phpunit/testcases/groups/class-bp-groups-group.php

@@ -1383 +1383 @@
 
                 $this->assertEmpty( $groups['groups'] );
         }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_get_by_parent_id() {
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g4 = $this->factory->group->create();
+
+                $groups = BP_Groups_Group::get( array(
+                        'parent_id' => $g1,
+                ) );
+
+                $found = wp_list_pluck( $groups['groups'], 'id' );
+                $this->assertEquals( array( $g2 ), $found );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_get_by_parent_id_ignore_grandparent() {
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g4 = $this->factory->group->create();
+
+                $groups = BP_Groups_Group::get( array(
+                        'parent_id' => $g2,
+                ) );
+
+                $found = wp_list_pluck( $groups['groups'], 'id' );
+                $this->assertEquals( array( $g3 ), $found );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_get_by_parent_id_array() {
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g4 = $this->factory->group->create();
+
+                $groups = BP_Groups_Group::get( array(
+                        'parent_id' => array( $g1, $g2 ),
+                ) );
+
+                $found = wp_list_pluck( $groups['groups'], 'id' );
+                $this->assertEqualSets( array( $g2, $g3 ), $found );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_get_by_parent_id_comma_separated_string() {
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g4 = $this->factory->group->create();
+
+                $groups = BP_Groups_Group::get( array(
+                        'parent_id' => "$g1, $g2",
+                ) );
+
+                $found = wp_list_pluck( $groups['groups'], 'id' );
+                $this->assertEqualSets( array( $g2, $g3 ), $found );
+        }
 }
 
 /**

tests/phpunit/testcases/groups/functions.php

@@ -664 +664 @@
                 groups_accept_invite( $u2, $g );
                 $this->assertEquals( 0, groups_get_invite_count_for_user( $u2 ) );
         }
+
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_update_orphaned_groups_on_group_delete_top_level() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+
+                groups_delete_group( $g1 );
+
+                $child = groups_get_group( array( 'group_id' => $g2 ) );
+                $this->assertEquals( 0, $child->parent_id );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_update_orphaned_groups_on_group_delete_two_levels() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+
+                groups_delete_group( $g2 );
+
+                $child = groups_get_group( array( 'group_id' => $g3 ) );
+                $this->assertEquals( $g1, $child->parent_id );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_child_groups_no_user_scope() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+
+                $children = bp_groups_get_child_groups( $g1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_child_groups_user_scope_logged_out() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+
+                $children = bp_groups_get_child_groups( $g1, 0 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_child_groups_user_scope_not_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $u1 = $this->factory->user->create();
+
+                $children = bp_groups_get_child_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_child_groups_user_scope_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                        'creator_id' => $u1,
+                ) );
+
+                $children = bp_groups_get_child_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_child_groups_user_scope_site_admin() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create( array( 'role' => 'administrator' ) );
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                ) );
+
+                $children = bp_groups_get_child_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_descendent_groups_no_user_scope() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_descendent_groups( $g1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3, $g4 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_descendent_groups_user_scope_logged_out() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_descendent_groups( $g1, 0 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g4 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_descendent_groups_user_scope_not_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+                $u1 = $this->factory->user->create();
+
+                $children = bp_groups_get_descendent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g4 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_descendent_groups_user_scope_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                        'creator_id' => $u1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_descendent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3, $g4 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_descendent_groups_user_scope_site_admin() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create( array( 'role' => 'administrator' ) );
+                $this->grant_super_admin( $u1 );
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_descendent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $children, 'id' );
+
+                $this->assertEqualSets( array( $g2, $g3, $g4 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_no_user_scope() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4 );
+
+                $this->assertEqualSets( array( $g1, $g2 ), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_user_scope_logged_out() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g2,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4, 0 );
+
+                $this->assertEqualSets( array( $g1, $g2 ), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_user_scope_logged_out_w_hidden() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                        'status'    => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4, 0 );
+
+                $this->assertEqualSets( array(), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_user_scope_not_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $g1 = $this->factory->group->create( array(
+                        'status' => 'hidden',
+                ) );
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $u1 = $this->factory->user->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4, $u1 );
+
+                $this->assertEqualSets( array( $g3 ), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_user_scope_group_member() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                        'creator_id' => $u1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4, $u1 );
+
+                $this->assertEqualSets( array( $g1, $g3 ), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_ancestor_group_ids_user_scope_site_admin() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create( array( 'role' => 'administrator' ) );
+                $this->grant_super_admin( $u1 );
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                        'status'     => 'hidden',
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+
+                $children = bp_groups_get_ancestor_group_ids( $g4, $u1 );
+
+                $this->assertEqualSets( array( $g1, $g3 ), $children );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_nonmember_member_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'member' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array(), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups_one
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_member_member_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member.
+                $this->add_user_to_group( $u1, $g6 );
+
+                // Members can create subgroups.
+                groups_add_groupmeta( $g6, 'allowed_subgroup_creators', 'member' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array( $g6 ), $found );
+
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_member_mod_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member.
+                $this->add_user_to_group( $u1, $g6 );
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'mod' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array(), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_mod_mod_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member, then promote.
+                $this->add_user_to_group( $u1, $g6 );
+                $m1 = new BP_Groups_Member( $u1, $g6 );
+                $m1->promote( 'mod' );
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'mod' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array( $g6 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_mod_admin_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member, then promote.
+                $this->add_user_to_group( $u1, $g6 );
+                $m1 = new BP_Groups_Member( $u1, $g6 );
+                $m1->promote( 'mod' );
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'admin' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array(), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_admin_admin_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member, then promote.
+                $this->add_user_to_group( $u1, $g6 );
+                $m1 = new BP_Groups_Member( $u1, $g6 );
+                $m1->promote( 'admin' );
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'admin' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array( $g6 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_is_admin_noone_allowed() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create();
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                // Make $u1 a member, then promote.
+                $this->add_user_to_group( $u1, $g6 );
+                $m1 = new BP_Groups_Member( $u1, $g6 );
+                $m1->promote( 'admin' );
+
+                // Members can create subgroups.
+                groups_update_groupmeta( $g6, 'allowed_subgroup_creators', 'noone' );
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array(), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
+        /**
+         * @group hierarchical_groups
+         */
+        public function test_bp_groups_get_possible_parent_groups_user_scope_site_admin() {
+                add_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+
+                $u1 = $this->factory->user->create( array( 'role' => 'administrator' ) );
+                $this->grant_super_admin( $u1 );
+                $g1 = $this->factory->group->create();
+                $g2 = $this->factory->group->create( array(
+                        'parent_id' => $g1,
+                ) );
+                $g3 = $this->factory->group->create( array(
+                        'parent_id'  => $g1,
+                ) );
+                $g4 = $this->factory->group->create( array(
+                        'parent_id' => $g3,
+                ) );
+                $g5 = $this->factory->group->create();
+                $g6 = $this->factory->group->create();
+
+                $groups = bp_groups_get_possible_parent_groups( $g1, $u1 );
+                $found = wp_list_pluck( $groups, 'id' );
+
+                $this->assertEqualSets( array( $g5, $g6 ), $found );
+                remove_filter( 'bp_allow_hierarchical_groups', '__return_true' );
+        }
+
 }