Skip to:
Content

BuddyPress.org

Changeset 7995


Ignore:
Timestamp:
02/26/2014 09:48:25 PM (11 years ago)
Author:
r-a-y
Message:

Add phpDoc for BP_Messages_Thread class.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-messages/bp-messages-classes.php

    r7994 r7995  
    1111if ( !defined( 'ABSPATH' ) ) exit;
    1212
     13/**
     14 * BuddyPress Message Thread class.
     15 *
     16 * @since BuddyPress (1.0.0)
     17 */
    1318class BP_Messages_Thread {
     19    /**
     20     * The message thread ID.
     21     *
     22     * @since BuddyPress (1.0.0)
     23     * @var int
     24     */
    1425    public $thread_id;
     26
     27    /**
     28     * The current messages.
     29     *
     30     * @since BuddyPress (1.0.0)
     31     * @var object
     32     */
    1533    public $messages;
     34
     35    /**
     36     * The current recipients in the message thread.
     37     *
     38     * @since BuddyPress (1.0.0)
     39     * @var object
     40     */
    1641    public $recipients;
     42
     43    /**
     44     * The user IDs of all messages in the message thread.
     45     *
     46     * @since BuddyPress (1.2.0)
     47     * @var array
     48     */
    1749    public $sender_ids;
    1850
     51    /**
     52     * The unread count for the logged-in user.
     53     *
     54     * @since BuddyPress (1.2.0)
     55     * @var int
     56     */
    1957    public $unread_count;
    2058
    … …  
    2260     * The content of the last message in this thread
    2361     *
    24      * @since BuddyPress (1.2)
     62     * @since BuddyPress (1.2.0)
    2563     * @var string
    2664     */
    … …  
    3068     * The date of the last message in this thread
    3169     *
    32      * @since BuddyPress (1.2)
     70     * @since BuddyPress (1.2.0)
    3371     * @var string
    3472     */
    … …  
    3876     * The ID of the last message in this thread
    3977     *
    40      * @since BuddyPress (1.2)
     78     * @since BuddyPress (1.2.0)
    4179     * @var int
    4280     */
    … …  
    4684     * The subject of the last message in this thread
    4785     *
    48      * @since BuddyPress (1.2)
     86     * @since BuddyPress (1.2.0)
    4987     * @var string
    5088     */
    … …  
    5492     * The user ID of the author of the last message in this thread
    5593     *
    56      * @since BuddyPress (1.2)
     94     * @since BuddyPress (1.2.0)
    5795     * @var int
    5896     */
    … …  
    62100     * Sort order of the messages in this thread (ASC or DESC).
    63101     *
    64      * @since BuddyPress (1.5)
     102     * @since BuddyPress (1.5.0)
    65103     * @var string
    66104     */
    67105    public $messages_order;
    68106
     107    /**
     108     * Constructor.
     109     *
     110     * @since BuddyPress (1.0.0)
     111     *
     112     * @param int $thread_id The message thread ID.
     113     * @param string $order The order to sort the messages. Either 'ASC' or 'DESC'.
     114     */
    69115    public function __construct( $thread_id = false, $order = 'ASC' ) {
    70         if ( $thread_id )
     116        if ( $thread_id ) {
    71117            $this->populate( $thread_id, $order );
    72     }
    73 
     118        }
     119    }
     120
     121    /**
     122     * Populate method.
     123     *
     124     * Used in constructor.
     125     *
     126     * @since BuddyPress (1.0.0)
     127     *
     128     * @param int $thread_id The message thread ID.
     129     * @param string $order The order to sort the messages. Either 'ASC' or 'DESC'.
     130     */
    74131    public function populate( $thread_id, $order ) {
    75132        global $wpdb, $bp;
    76133
    77         if( 'ASC' != $order && 'DESC' != $order )
     134        if( 'ASC' != $order && 'DESC' != $order ) {
    78135            $order= 'ASC';
     136        }
    79137
    80138        $this->messages_order = $order;
    81139        $this->thread_id      = $thread_id;
    82140
    83         if ( !$this->messages = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$bp->messages->table_name_messages} WHERE thread_id = %d ORDER BY date_sent " . $order, $this->thread_id ) ) )
    84             return false;
    85 
    86         foreach ( (array) $this->messages as $key => $message )
     141        if ( !$this->messages = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$bp->messages->table_name_messages} WHERE thread_id = %d ORDER BY date_sent " . $order, $this->thread_id ) ) ) {
     142            return false;
     143        }
     144
     145        foreach ( (array) $this->messages as $key => $message ) {
    87146            $this->sender_ids[$message->sender_id] = $message->sender_id;
     147        }
    88148
    89149        // Fetch the recipients
    … …  
    91151
    92152        // Get the unread count for the logged in user
    93         if ( isset( $this->recipients[bp_loggedin_user_id()] ) )
     153        if ( isset( $this->recipients[bp_loggedin_user_id()] ) ) {
    94154            $this->unread_count = $this->recipients[bp_loggedin_user_id()]->unread_count;
    95     }
    96 
     155        }
     156    }
     157
     158    /**
     159     * Mark a thread initialized in this class as read.
     160     *
     161     * @since BuddyPress (1.0.0)
     162     *
     163     * @see BP_Messages_Thread::mark_as_read()
     164     */
    97165    public function mark_read() {
    98166        BP_Messages_Thread::mark_as_read( $this->thread_id );
    99167    }
    100168
     169    /**
     170     * Mark a thread initialized in this class as unread.
     171     *
     172     * @since BuddyPress (1.0.0)
     173     *
     174     * @see BP_Messages_Thread::mark_as_unread()
     175     */
    101176    public function mark_unread() {
    102177        BP_Messages_Thread::mark_as_unread( $this->thread_id );
    103178    }
    104179
     180    /**
     181     * Returns recipients for a message thread.
     182     *
     183     * @since BuddyPress (1.0.0)
     184     *
     185     * @return object
     186     */
    105187    public function get_recipients() {
    106188        global $wpdb, $bp;
    … …  
    117199    /** Static Functions ******************************************************/
    118200
     201    /**
     202     * Delete a message thread.
     203     *
     204     * @since BuddyPress (1.0.0)
     205     *
     206     * @param int $thread_id The message thread ID
     207     * @return bool
     208     */
    119209    public static function delete( $thread_id ) {
    120210        global $wpdb, $bp;
    … …  
    138228    }
    139229
     230    /**
     231     * Get current message threads for a user.
     232     *
     233     * @since BuddyPress (1.0.0)
     234     *
     235     * @param int    $user_id The user ID.
     236     * @param string $box  The type of mailbox to get. Either 'inbox' or 'sentbox'.
     237     *                     Defaults to 'inbox'.
     238     * @param string $type The type of messages to get. Either 'all' or 'unread'
     239     *                     or 'read'. Defaults to 'all'.
     240     * @param int    $limit The number of messages to get. Defaults to null.
     241     * @param int    $page  The page number to get. Defaults to null.
     242     * @param string $search_terms The search term to use. Defaults to ''.
     243     * @return array|bool Array on success. Boolean false on failure.
     244     */
    140245    public static function get_current_threads_for_user( $user_id, $box = 'inbox', $type = 'all', $limit = null, $page = null, $search_terms = '' ) {
    141246        global $wpdb, $bp;
    142247
    143248        $pag_sql = $type_sql = $search_sql = '';
    144         if ( $limit && $page )
     249        if ( $limit && $page ) {
    145250            $pag_sql = $wpdb->prepare( " LIMIT %d, %d", intval( ( $page - 1 ) * $limit), intval( $limit ) );
    146 
    147         if ( $type == 'unread' )
     251        }
     252
     253        if ( $type == 'unread' ) {
    148254            $type_sql = " AND r.unread_count != 0 ";
    149         elseif ( $type == 'read' )
     255        } elseif ( $type == 'read' ) {
    150256            $type_sql = " AND r.unread_count = 0 ";
    151 
    152         if ( !empty( $search_terms ) ) {
     257        }
     258
     259        if ( ! empty( $search_terms ) ) {
    153260            $search_terms = like_escape( esc_sql( $search_terms ) );
    154261            $search_sql   = "AND ( subject LIKE '%%$search_terms%%' OR message LIKE '%%$search_terms%%' )";
    … …  
    163270        }
    164271
    165         if ( empty( $thread_ids ) )
    166             return false;
     272        if ( empty( $thread_ids ) ) {
     273            return false;
     274        }
    167275
    168276        // Sort threads by date_sent
    169         foreach( (array) $thread_ids as $thread )
     277        foreach( (array) $thread_ids as $thread ) {
    170278            $sorted_threads[$thread->thread_id] = strtotime( $thread->date_sent );
     279        }
    171280
    172281        arsort( $sorted_threads );
    173282
    174283        $threads = false;
    175         foreach ( (array) $sorted_threads as $thread_id => $date_sent )
     284        foreach ( (array) $sorted_threads as $thread_id => $date_sent ) {
    176285            $threads[] = new BP_Messages_Thread( $thread_id );
     286        }
    177287
    178288        return array( 'threads' => &$threads, 'total' => (int) $total_threads );
    179289    }
    180290
     291    /**
     292     * Mark a thread as read.
     293     *
     294     * @since BuddyPress (1.0.0)
     295     *
     296     * @param int $thread_id The message thread ID.
     297     */
    181298    public static function mark_as_read( $thread_id ) {
    182299        global $wpdb, $bp;
    … …  
    186303    }
    187304
     305    /**
     306     * Mark a thread as unread.
     307     *
     308     * @since BuddyPress (1.0.0)
     309     *
     310     * @param int $thread_id The message thread ID.
     311     */
    188312    public static function mark_as_unread( $thread_id ) {
    189313        global $wpdb, $bp;
    … …  
    193317    }
    194318
     319    /**
     320     * Returns the total number of message threads for a user.
     321     *
     322     * @since BuddyPress (1.0.0)
     323     *
     324     * @param int    $user_id The user ID.
     325     * @param string $box  The type of mailbox to get. Either 'inbox' or 'sentbox'.
     326     *                     Defaults to 'inbox'.
     327     * @param string $type The type of messages to get. Either 'all' or 'unread'
     328     *                     or 'read'. Defaults to 'all'.
     329     * @return int
     330     */
    195331    public static function get_total_threads_for_user( $user_id, $box = 'inbox', $type = 'all' ) {
    196332        global $wpdb, $bp;
    … …  
    208344    }
    209345
     346    /**
     347     * Determine if the logged-in user is a sender of any message in a thread.
     348     *
     349     * @since BuddyPress (1.0.0)
     350     *
     351     * @param int $thread_id The message thread ID.
     352     * @param bool
     353     */
    210354    public static function user_is_sender( $thread_id ) {
    211355        global $wpdb, $bp;
    … …  
    213357        $sender_ids = $wpdb->get_col( $wpdb->prepare( "SELECT sender_id FROM {$bp->messages->table_name_messages} WHERE thread_id = %d", $thread_id ) );
    214358
    215         if ( !$sender_ids )
    216             return false;
     359        if ( ! $sender_ids ) {
     360            return false;
     361        }
    217362
    218363        return in_array( bp_loggedin_user_id(), $sender_ids );
    219364    }
    220365
     366    /**
     367     * Returns the userlink of the last sender in a message thread.
     368     *
     369     * @since BuddyPress (1.0.0)
     370     *
     371     * @param int $thread_id The message thread ID.
     372     * @return string|bool The user link on success. Boolean false on failure.
     373     */
    221374    public static function get_last_sender( $thread_id ) {
    222375        global $wpdb, $bp;
    223376
    224         if ( !$sender_id = $wpdb->get_var( $wpdb->prepare( "SELECT sender_id FROM {$bp->messages->table_name_messages} WHERE thread_id = %d GROUP BY sender_id ORDER BY date_sent LIMIT 1", $thread_id ) ) )
    225             return false;
     377        if ( ! $sender_id = $wpdb->get_var( $wpdb->prepare( "SELECT sender_id FROM {$bp->messages->table_name_messages} WHERE thread_id = %d GROUP BY sender_id ORDER BY date_sent LIMIT 1", $thread_id ) ) ) {
     378            return false;
     379        }
    226380
    227381        return bp_core_get_userlink( $sender_id, true );
    228382    }
    229383
     384    /**
     385     * Gets the inbox message count for a user.
     386     *
     387     * @since BuddyPress (1.0.0)
     388     *
     389     * @param int $user_id The user ID.
     390     * @return int
     391     */
    230392    public static function get_inbox_count( $user_id = 0 ) {
     393        global $wpdb, $bp;
     394
     395        if ( empty( $user_id ) ) {
     396            $user_id = bp_loggedin_user_id();
     397        }
     398
     399        $sql = $wpdb->prepare( "SELECT SUM(unread_count) FROM {$bp->messages->table_name_recipients} WHERE user_id = %d AND is_deleted = 0 AND sender_only = 0", $user_id );
     400        $unread_count = $wpdb->get_var( $sql );
     401
     402        if ( empty( $unread_count ) || is_wp_error( $unread_count ) ) {
     403            return 0;
     404        }
     405
     406        return (int) $unread_count;
     407    }
     408
     409    /**
     410     * Checks whether a user is a part of a message thread discussion.
     411     *
     412     * @since BuddyPress (1.0.0)
     413     *
     414     * @param int $thread_id The message thread ID.
     415     * @param int $user_id The user ID.
     416     * @return int The message ID on success.
     417     */
     418    public static function check_access( $thread_id, $user_id = 0 ) {
    231419        global $wpdb, $bp;
    232420
    … …  
    234422            $user_id = bp_loggedin_user_id();
    235423
    236         $sql = $wpdb->prepare( "SELECT SUM(unread_count) FROM {$bp->messages->table_name_recipients} WHERE user_id = %d AND is_deleted = 0 AND sender_only = 0", $user_id );
    237         $unread_count = $wpdb->get_var( $sql );
    238 
    239         if ( empty( $unread_count ) || is_wp_error( $unread_count ) )
    240             return 0;
    241 
    242         return (int) $unread_count;
    243     }
    244 
    245     public static function check_access( $thread_id, $user_id = 0 ) {
    246         global $wpdb, $bp;
    247 
    248         if ( empty( $user_id ) )
    249             $user_id = bp_loggedin_user_id();
    250 
    251424        return $wpdb->get_var( $wpdb->prepare( "SELECT id FROM {$bp->messages->table_name_recipients} WHERE thread_id = %d AND user_id = %d", $thread_id, $user_id ) );
    252425    }
    253426
     427    /**
     428     * Checks whether a message thread exists.
     429     *
     430     * @since BuddyPress (1.0.0)
     431     *
     432     * @param int $thread_id The message thread ID.
     433     * @return int The message thread ID on success.
     434     */
    254435    public static function is_valid( $thread_id ) {
    255436        global $wpdb, $bp;
    … …  
    258439    }
    259440
     441    /**
     442     * Returns a string containing all the message recipient userlinks.
     443     *
     444     * String is comma-delimited.
     445     *
     446     * If a message thread has more than four users, the returned string is simply
     447     * "X Recipients" where "X" is the number of recipients in the message thread.
     448     *
     449     * @since BuddyPress (1.0.0)
     450     *
     451     * @param object $recipients Object containing the message recipients.
     452     * @return string
     453     */
    260454    public static function get_recipient_links( $recipients ) {
    261455        if ( count( $recipients ) >= 5 )
    … …  
    277471    }
    278472
     473    /**
     474     * Upgrade method for the older BP message thread DB table.
     475     *
     476     * @since BuddyPress (1.2.0)
     477     *
     478     * @todo We should remove this.  No one is going to upgrade from v1.1, right?
     479     * @return bool
     480     */
    279481    public static function update_tables() {
    280482        global $wpdb, $bp;
    … …  
    285487
    286488        // Nothing to update, just return true to remove the table
    287         if ( empty( $threads ) )
     489        if ( empty( $threads ) ) {
    288490            return true;
     491        }
    289492
    290493        foreach( (array) $threads as $thread ) {
    … …  
    295498
    296499                // Add the thread_id to the messages table
    297                 if ( !$wpdb->query( $wpdb->prepare( "UPDATE {$bp->messages->table_name_messages} SET thread_id = %d WHERE id IN ({$message_ids})", $thread->id ) ) )
     500                if ( ! $wpdb->query( $wpdb->prepare( "UPDATE {$bp->messages->table_name_messages} SET thread_id = %d WHERE id IN ({$message_ids})", $thread->id ) ) )
    298501                    $errors = true;
    299502            }
    300503        }
    301504
    302         if ( $errors )
    303             return false;
     505        if ( $errors ) {
     506            return false;
     507        }
    304508
    305509        return true;
Note: See TracChangeset for help on using the changeset viewer.