Changeset 10374 for trunk/src/bp-blogs/bp-blogs-functions.php

Timestamp:

11/23/2015 03:55:00 AM (9 years ago)

Author:

tw2113

Message:

More documentation cleanup for BP-Blogs component.

See #6397.

File:

• trunk/src/bp-blogs/bp-blogs-functions.php (modified) (57 diffs)

trunk/src/bp-blogs/bp-blogs-functions.php

@@ -7 +7 @@
  */
 
-// Exit if accessed directly
+// Exit if accessed directly.
 defined( 'ABSPATH' ) || exit;
 
@@ -43 +43 @@
 function bp_blogs_get_blogs( $args = '' ) {
 
-    // Parse query arguments
+    // Parse query arguments.
     $r = bp_parse_args( $args, array(
         'type'              => 'active', // 'active', 'alphabetical', 'newest', or 'random'
@@ -54 +54 @@
     ), 'blogs_get_blogs' );
 
-    // Get the blogs
+    // Get the blogs.
     $blogs = BP_Blogs_Blog::get(
         $r['type'],
@@ -65 +65 @@
     );
 
-    // Filter and return
+    // Filter and return.
     return apply_filters( 'bp_blogs_get_blogs', $blogs, $r );
 }
@@ -83 +83 @@
     global $wpdb;
 
-    // Query for all sites in network
+    // Query for all sites in network.
     if ( is_multisite() ) {
 
-        // Get blog ID's if not a large network
+        // Get blog ID's if not a large network.
         if ( ! wp_is_large_network() ) {
             $blog_ids = $wpdb->get_col( $wpdb->prepare( "SELECT blog_id FROM {$wpdb->base_prefix}blogs WHERE mature = 0 AND spam = 0 AND deleted = 0 AND site_id = %d", $wpdb->siteid ) );
 
-            // If error running this query, set blog ID's to false
+            // If error running this query, set blog ID's to false.
             if ( is_wp_error( $blog_ids ) ) {
                 $blog_ids = false;
             }
 
-        // Large networks are not currently supported
+        // Large networks are not currently supported.
         } else {
             $blog_ids = false;
         }
 
-    // Record a single site
+    // Record a single site.
     } else {
         $blog_ids = $wpdb->blogid;
     }
 
-    // Bail if there are no blogs in the network
+    // Bail if there are no blogs in the network.
     if ( empty( $blog_ids ) ) {
         return false;
     }
 
-    // Get BuddyPress
+    // Get BuddyPress.
     $bp = buddypress();
 
-    // Truncate user blogs table
+    // Truncate user blogs table.
     $truncate = $wpdb->query( "TRUNCATE {$bp->blogs->table_name}" );
     if ( is_wp_error( $truncate ) ) {
@@ -119 +119 @@
     }
 
-    // Truncate user blogsmeta table
+    // Truncate user blogsmeta table.
     $truncate = $wpdb->query( "TRUNCATE {$bp->blogs->table_name_blogmeta}" );
     if ( is_wp_error( $truncate ) ) {
@@ -125 +125 @@
     }
 
-    // Loop through users of blogs and record the relationship
+    // Loop through users of blogs and record the relationship.
     foreach ( (array) $blog_ids as $blog_id ) {
 
-        // Ensure that the cache is clear after the table TRUNCATE above
+        // Ensure that the cache is clear after the table TRUNCATE above.
         wp_cache_delete( $blog_id, 'blog_meta' );
 
-        // Get all users
+        // Get all users.
         $users = get_users( array(
             'blog_id' => $blog_id
         ) );
 
-        // Continue on if no users exist for this site (how did this happen?)
+        // Continue on if no users exist for this site (how did this happen?).
         if ( empty( $users ) ) {
             continue;
         }
 
-        // Loop through users and record their relationship to this blog
+        // Loop through users and record their relationship to this blog.
         foreach ( (array) $users as $user ) {
             bp_blogs_add_user_to_blog( $user->ID, false, $blog_id );
@@ -154 +154 @@
     do_action( 'bp_blogs_recorded_existing_blogs' );
 
-    // No errors
+    // No errors.
     return true;
 }
@@ -170 +170 @@
  * @param int $blog_id ID of the blog being checked.
  * @param int $user_id Optional. ID of the user for whom access is being checked.
- *
  * @return bool True if blog is recordable, otherwise false.
  */
@@ -203 +202 @@
  * @param int $blog_id ID of the blog being checked.
  * @param int $user_id Optional. ID of the user for whom access is being checked.
- *
  * @return bool True if blog is trackable, otherwise false.
  */
@@ -234 +232 @@
  * @param bool $no_activity Optional. Whether to skip recording an activity
  *                          item about this blog creation. Default: false.
- *
  * @return bool|null Returns false on failure.
  */
@@ -261 +258 @@
         $thread_depth = get_blog_option( $blog_id, 'thread_comments_depth' );
     } else {
-        // perhaps filter this?
+        // Perhaps filter this?
         $thread_depth = 1;
     }
@@ -282 +279 @@
     $is_private = !apply_filters( 'bp_is_new_blog_public', !$is_private );
 
-    // Only record this activity if the blog is public
+    // Only record this activity if the blog is public.
     if ( !$is_private && !$no_activity && bp_blogs_is_blog_trackable( $blog_id, $user_id ) ) {
 
-        // Record this in activity streams
+        // Record this in activity streams.
         bp_blogs_record_activity( array(
             'user_id'      => $recorded_blog->user_id,
@@ -565 +562 @@
  * @param bool|string $is_approved Optional. The $is_approved value passed to
  *                                 the 'comment_post' action. Default: true.
- *
  * @return bool|object Returns false on failure, the comment object on success.
  */
 function bp_blogs_record_comment( $comment_id, $is_approved = true ) {
-    // bail if activity component is not active
+    // Bail if activity component is not active.
     if ( ! bp_is_active( 'activity' ) ) {
         return;
     }
 
-    // Get the users comment
+    // Get the users comment.
     $recorded_comment = get_comment( $comment_id );
 
-    // Don't record activity if the comment hasn't been approved
+    // Don't record activity if the comment hasn't been approved.
     if ( empty( $is_approved ) )
         return false;
 
-    // Don't record activity if no email address has been included
+    // Don't record activity if no email address has been included.
     if ( empty( $recorded_comment->comment_author_email ) )
         return false;
 
-    // Don't record activity if the comment has already been marked as spam
+    // Don't record activity if the comment has already been marked as spam.
     if ( 'spam' === $is_approved )
         return false;
@@ -592 +588 @@
     $user = get_user_by( 'email', $recorded_comment->comment_author_email );
 
-    // If user isn't registered, don't record activity
+    // If user isn't registered, don't record activity.
     if ( empty( $user ) )
         return false;
 
-    // Get the user_id
+    // Get the user_id.
     $user_id = (int) $user->ID;
 
-    // Get blog and post data
+    // Get blog and post data.
     $blog_id = get_current_blog_id();
 
@@ -611 +607 @@
         return false;
 
-    // If this is a password protected post, don't record the comment
+    // If this is a password protected post, don't record the comment.
     if ( !empty( $recorded_comment->post->post_password ) )
         return false;
 
-    // Don't record activity if the comment's associated post isn't a WordPress Post
+    // Don't record activity if the comment's associated post isn't a WordPress Post.
     if ( !in_array( $recorded_comment->post->post_type, apply_filters( 'bp_blogs_record_comment_post_types', array( 'post' ) ) ) )
         return false;
@@ -621 +617 @@
     $is_blog_public = apply_filters( 'bp_is_blog_public', (int)get_blog_option( $blog_id, 'blog_public' ) );
 
-    // If blog is public allow activity to be posted
+    // If blog is public allow activity to be posted.
     if ( $is_blog_public ) {
 
-        // Get activity related links
+        // Get activity related links.
         $post_permalink = get_permalink( $recorded_comment->comment_post_ID );
         $comment_link   = get_comment_link( $recorded_comment->comment_ID );
 
-        // Setup activity args
+        // Setup activity args.
         $args = array();
 
@@ -637 +633 @@
 
         // Setup some different activity args depending if activity commenting is
-        // enabled or not
-
+        // enabled or not.
         // if cannot comment, record separate activity entry
-        // this is the old way of doing things
+        // this is the old way of doing things.
         if ( bp_disable_blogforum_comments() ) {
             $args['type']              = 'new_blog_comment';
@@ -646 +641 @@
             $args['secondary_item_id'] = $comment_id;
 
-            // record the activity entry
+            // Record the activity entry.
             $activity_id = bp_blogs_record_activity( $args );
 
-            // add some post info in activity meta
+            // Add some post info in activity meta.
             bp_activity_update_meta( $activity_id, 'post_title', $recorded_comment->post->post_title );
             bp_activity_update_meta( $activity_id, 'post_url',   add_query_arg( 'p', $recorded_comment->post->ID, home_url( '/' ) ) );
 
-        // record comment as BP activity comment under the parent 'new_blog_post'
-        // activity item
+        // Record comment as BP activity comment under the parent 'new_blog_post'
+        // activity item.
         } else {
-            // this is a comment edit
-            // check to see if corresponding activity entry already exists
+            // This is a comment edit
+            // check to see if corresponding activity entry already exists.
             if ( ! empty( $_REQUEST['action'] ) ) {
                 $existing_activity_id = get_comment_meta( $comment_id, 'bp_activity_comment_id', true );
@@ -666 +661 @@
             }
 
-            // find the parent 'new_blog_post' activity entry
+            // Find the parent 'new_blog_post' activity entry.
             $parent_activity_id = bp_activity_get_activity_id( array(
                 'component'         => 'blogs',
@@ -674 +669 @@
             ) );
 
-            // Try to create a new activity item for the parent blog post
+            // Try to create a new activity item for the parent blog post.
             if ( empty( $parent_activity_id ) ) {
                 $parent_activity_id = bp_activity_post_type_publish( $recorded_comment->comment_post_ID, $recorded_comment->post );
             }
 
-            // we found the parent activity entry
-            // so let's go ahead and reconfigure some activity args
+            // We found the parent activity entry
+            // so let's go ahead and reconfigure some activity args.
             if ( ! empty( $parent_activity_id ) ) {
-                // set the 'item_id' with the parent activity entry ID
+                // Set the 'item_id' with the parent activity entry ID.
                 $args['item_id'] = $parent_activity_id;
 
-                // now see if the WP parent comment has a BP activity ID
+                // Now see if the WP parent comment has a BP activity ID.
                 $comment_parent = 0;
                 if ( ! empty( $recorded_comment->comment_parent ) ) {
@@ -692 +687 @@
 
                 // WP parent comment does not have a BP activity ID
-                // so set to 'new_blog_post' activity ID
+                // so set to 'new_blog_post' activity ID.
                 if ( empty( $comment_parent ) ) {
                     $comment_parent = $parent_activity_id;
@@ -701 +696 @@
                 $args['type']              = 'activity_comment';
 
-            // could not find corresponding parent activity entry
-            // so wipe out $args array
+            // Could not find corresponding parent activity entry
+            // so wipe out $args array.
             } else {
                 $args = array();
             }
 
-            // Record in activity streams
+            // Record in activity streams.
             if ( ! empty( $args ) ) {
                 // @todo should we use bp_activity_new_comment()? that function will also send
-                // an email to people in the activity comment thread
+                // an email to people in the activity comment thread.
                 //
-                // what if a site already has some comment email notification plugin setup?
+                // What if a site already has some comment email notification plugin setup?
                 // this is why I decided to go with bp_activity_add() to avoid any conflict
-                // with existing comment email notification plugins
+                // with existing comment email notification plugins.
                 $comment_activity_id = bp_activity_add( $args );
 
                 if ( empty( $args['id'] ) ) {
-                    // add meta to activity comment
+                    // Add meta to activity comment.
                     bp_activity_update_meta( $comment_activity_id, 'bp_blogs_post_comment_id', $comment_id );
                     bp_activity_update_meta( $comment_activity_id, 'post_title', $recorded_comment->post->post_title );
                     bp_activity_update_meta( $comment_activity_id, 'post_url', add_query_arg( 'p', $recorded_comment->post->ID, home_url( '/' ) ) );
 
-                    // add meta to comment
+                    // Add meta to comment.
                     add_comment_meta( $comment_id, 'bp_activity_comment_id', $comment_activity_id );
                 }
@@ -729 +724 @@
         }
 
-        // Update the blogs last active date
+        // Update the blogs last active date.
         bp_blogs_update_blogmeta( $blog_id, 'last_activity', bp_core_current_time() );
     }
@@ -752 +747 @@
  * @param string|bool $role    User's WordPress role for this blog ID.
  * @param int         $blog_id Blog ID user is being added to.
- *
  * @return bool|null False on failure.
  */
@@ -758 +752 @@
     global $wpdb;
 
-    // If no blog ID was passed, use the root blog ID
+    // If no blog ID was passed, use the root blog ID.
     if ( empty( $blog_id ) ) {
         $blog_id = isset( $wpdb->blogid ) ? $wpdb->blogid : bp_get_root_blog_id();
     }
 
-    // If no role was passed, try to find the blog role
+    // If no role was passed, try to find the blog role.
     if ( empty( $role ) ) {
 
-        // Get user capabilities
+        // Get user capabilities.
         $key        = $wpdb->get_blog_prefix( $blog_id ). 'capabilities';
         $user_roles = array_keys( (array) bp_get_user_meta( $user_id, $key, true ) );
 
-        // User has roles so lets
+        // User has roles so lets.
         if ( ! empty( $user_roles ) ) {
 
-            // Get blog roles
+            // Get blog roles.
             $blog_roles      = array_keys( bp_get_current_blog_roles() );
 
-            // Look for blog only roles of the user
+            // Look for blog only roles of the user.
             $intersect_roles = array_intersect( $user_roles, $blog_roles );
 
@@ -789 +783 @@
     }
 
-    // Bail if no role was found or role is not in the allowed roles array
+    // Bail if no role was found or role is not in the allowed roles array.
     if ( empty( $role ) || ! in_array( $role, bp_blogs_get_allowed_roles() ) ) {
         return false;
     }
 
-    // Record the blog activity for this user being added to this blog
+    // Record the blog activity for this user being added to this blog.
     bp_blogs_record_blog( $blog_id, $user_id, true );
 }
@@ -873 +867 @@
     BP_Blogs_Blog::delete_blog_for_all( $blog_id );
 
-    // Delete activity stream item
+    // Delete activity stream item.
     bp_blogs_delete_activity( array(
         'item_id'   => $blog_id,
@@ -915 +909 @@
     BP_Blogs_Blog::delete_blog_for_user( $blog_id, $user_id );
 
-    // Delete activity stream item
+    // Delete activity stream item.
     bp_blogs_delete_activity( array(
         'item_id'   => $blog_id,
@@ -941 +935 @@
  * @param int $user_id Optional. Defaults to the logged-in user ID. This param
  *                     is currently unused in the function (but is passed to hooks).
- *
  * @return bool
  */
@@ -969 +962 @@
     do_action( 'bp_blogs_before_remove_post', $blog_id, $post_id, $user_id );
 
-    // Delete activity stream item
+    // Delete activity stream item.
     bp_blogs_delete_activity( array(
         'item_id'           => $blog_id,
@@ -998 +991 @@
     global $wpdb;
 
-    // activity comments are disabled for blog posts
-    // which means that individual activity items exist for blog comments
+    // Activity comments are disabled for blog posts
+    // which means that individual activity items exist for blog comments.
     if ( bp_disable_blogforum_comments() ) {
-        // Delete the individual activity stream item
+        // Delete the individual activity stream item.
         bp_blogs_delete_activity( array(
             'item_id'           => $wpdb->blogid,
@@ -1008 +1001 @@
         ) );
 
-    // activity comments are enabled for blog posts
-    // remove the associated activity item
+    // Activity comments are enabled for blog posts
+    // remove the associated activity item.
     } else {
-        // get associated activity ID from comment meta
+        // Get associated activity ID from comment meta.
         $activity_id = get_comment_meta( $comment_id, 'bp_activity_comment_id', true );
 
-        // delete the associated activity comment
+        // Delete the associated activity comment.
         //
-        // also removes child post comments and associated activity comments
+        // Also removes child post comments and associated activity comments.
         if ( ! empty( $activity_id ) && bp_is_active( 'activity' ) ) {
-            // fetch the activity comments for the activity item
+            // Fetch the activity comments for the activity item.
             $activity = bp_activity_get( array(
                 'in'               => $activity_id,
@@ -1025 +1018 @@
             ) );
 
-            // get all activity comment IDs for the pending deleted item
+            // Get all activity comment IDs for the pending deleted item.
             if ( ! empty( $activity['activities'] ) ) {
                 $activity_ids   = bp_activity_recurse_comments_activity_ids( $activity );
                 $activity_ids[] = $activity_id;
 
-                // delete activity items
+                // Delete activity items.
                 foreach ( $activity_ids as $activity_id ) {
                     bp_activity_delete( array(
@@ -1037 +1030 @@
                 }
 
-                // remove associated blog comments
+                // Remove associated blog comments.
                 bp_blogs_remove_associated_blog_comments( $activity_ids );
 
-                // rebuild activity comment tree
+                // Rebuild activity comment tree.
                 BP_Activity_Activity::rebuild_activity_comment_tree( $activity['activities'][0]->item_id );
             }
@@ -1069 +1062 @@
  * @param array $activity_ids The activity IDs to check association with blog
  *                            comments.
- * @param bool $force_delete  Whether to force delete the comments. If false,
+ * @param bool  $force_delete  Whether to force delete the comments. If false,
  *                            comments are trashed instead.
  */
 function bp_blogs_remove_associated_blog_comments( $activity_ids = array(), $force_delete = true ) {
-    // query args
+    // Query args.
     $query_args = array(
         'meta_query' => array(
@@ -1084 +1077 @@
     );
 
-    // get comment
+    // Get comment.
     $comment_query = new WP_Comment_Query;
     $comments = $comment_query->query( $query_args );
 
-    // found the corresponding comments
+    // Found the corresponding comments
     // let's delete them!
     foreach ( $comments as $comment ) {
         wp_delete_comment( $comment->comment_ID, $force_delete );
 
-        // if we're trashing the comment, remove the meta key as well
+        // If we're trashing the comment, remove the meta key as well.
         if ( empty( $force_delete ) ) {
             delete_comment_meta( $comment->comment_ID, 'bp_activity_comment_id' );
@@ -1111 +1104 @@
 function bp_blogs_transition_activity_status( $new_status, $old_status, $comment ) {
 
-    // Check the Activity component is active
+    // Check the Activity component is active.
     if ( ! bp_is_active( 'activity' ) )
         return;
@@ -1136 +1129 @@
     }
 
-    // Get the activity
+    // Get the activity.
     if ( bp_disable_blogforum_comments() ) {
         $activity_id = bp_activity_get_activity_id( array(
@@ -1148 +1141 @@
     }
 
-    // Check activity item exists
+    // Check activity item exists.
     if ( empty( $activity_id ) ) {
         // If no activity exists, but the comment has been approved, record it into the activity table.
@@ -1158 +1151 @@
     }
 
-    // Create an activity object
+    // Create an activity object.
     $activity = new BP_Activity_Activity( $activity_id );
     if ( empty( $activity->component ) )
         return;
 
-    // Spam/ham the activity if it's not already in that state
+    // Spam/ham the activity if it's not already in that state.
     if ( 'spam_activity' == $action && ! $activity->is_spam ) {
         bp_activity_mark_as_spam( $activity );
@@ -1170 +1163 @@
     }
 
-    // Add "new_blog_comment" to the whitelisted activity types, so that the activity's Akismet history is generated
+    // Add "new_blog_comment" to the whitelisted activity types, so that the activity's Akismet history is generated.
     $comment_akismet_history = create_function( '$t', '$t[] = "new_blog_comment"; return $t;' );
     add_filter( 'bp_akismet_get_activity_types', $comment_akismet_history );
 
-    // Save the updated activity
+    // Save the updated activity.
     $activity->save();
 
-    // Remove the "new_blog_comment" activity type whitelist so we don't break anything
+    // Remove the "new_blog_comment" activity type whitelist so we don't break anything.
     remove_filter( 'bp_akismet_get_activity_types', $comment_akismet_history );
 }
@@ -1205 +1198 @@
  * @param int $user_id ID of the user being queried. Default: on a user page,
  *                     the displayed user. Otherwise, the logged-in user.
- *
  * @return int $count Total blog count for the user.
  */
@@ -1213 +1205 @@
     }
 
-    // no user ID? do not attempt to look at cache
+    // No user ID? do not attempt to look at cache.
     if ( empty( $user_id ) ) {
         return 0;
@@ -1247 +1239 @@
     BP_Blogs_Blog::delete_blog_for_all( $blog_id );
 
-    // Delete activity stream item
+    // Delete activity stream item.
     bp_blogs_delete_activity( array(
         'item_id'   => $blog_id,
@@ -1274 +1266 @@
  * @param int  $user_id     See {@BP_Blogs_Blog::get_blogs_for_user()}.
  * @param bool $show_hidden See {@BP_Blogs_Blog::get_blogs_for_user()}.
- *
  * @return array See {@BP_Blogs_Blog::get_blogs_for_user()}.
  */
@@ -1288 +1279 @@
  * @param int $limit See {@BP_Blogs_Blog::get_all()}.
  * @param int $page  See {@BP_Blogs_Blog::get_all()}.
- *
  * @return array See {@BP_Blogs_Blog::get_all()}.
  */
@@ -1302 +1292 @@
  * @param int $limit See {@BP_Blogs_Blog::get()}.
  * @param int $page  See {@BP_Blogs_Blog::get()}.
- *
  * @return array See {@BP_Blogs_Blog::get()}.
  */
@@ -1315 +1304 @@
  *
  * @param int $blog_id See {@BP_Blogs_Blog::is_hidden()}.
- *
  * @return bool See {@BP_Blogs_Blog::is_hidden()}.
  */
@@ -1322 +1310 @@
 }
 
-/*******************************************************************************
+/*
  * Blog meta functions
  *
@@ -1343 +1331 @@
  *                                deleted if the meta_value matches this parameter.
  * @param bool        $delete_all Optional. If true, delete matching metadata entries for
- *                               all objects, ignoring the specified blog_id. Otherwise, only
- *                               delete matching metadata entries for the specified blog.
- *                               Default: false.
- *
+ *                                all objects, ignoring the specified blog_id. Otherwise, only
+ *                                delete matching metadata entries for the specified blog.
+ *                                Default: false.
  * @return bool True on success, false on failure.
  */
@@ -1352 +1339 @@
     global $wpdb;
 
-    // Legacy - if no meta_key is passed, delete all for the blog_id
+    // Legacy - if no meta_key is passed, delete all for the blog_id.
     if ( empty( $meta_key ) ) {
         $keys = $wpdb->get_col( $wpdb->prepare( "SELECT meta_key FROM {$wpdb->blogmeta} WHERE blog_id = %d", $blog_id ) );
@@ -1384 +1371 @@
  *                         metadata for the blog will be fetched.
  * @param bool   $single   Optional. If true, return only the first value of the
- *                          specified meta_key. This parameter has no effect if
- *                          meta_key is not specified. Default: true.
- *
+ *                         specified meta_key. This parameter has no effect if
+ *                         meta_key is not specified. Default: true.
  * @return mixed The meta value(s) being requested.
  */
@@ -1408 +1394 @@
  *                           metadata entries with the specified value.
  *                           Otherwise, update all entries.
- *
  * @return bool|int Returns false on failure. On successful update of existing
  *                  metadata, returns true. On successful creation of new metadata,
@@ -1432 +1417 @@
  *                           for the given key. If true, and the object already has a value for
  *                           the key, no change will be made. Default: false.
- *
  * @return int|bool The meta ID on successful update, false on failure.
  */
@@ -1446 +1430 @@
  *
  * @param int $user_id ID whose blog data should be removed.
- *
- * @return bool|null Returns false on failure.
+ * @return bool Returns false on failure.
  */
 function bp_blogs_remove_data( $user_id ) {
@@ -1490 +1473 @@
     }
 
-    // Get the user's blogs
+    // Get the user's blogs.
     $user_blogs = get_blogs_of_user( $user_id );
     if ( empty( $user_blogs ) ) {