Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
10/22/2015 06:12:16 AM (8 years ago)
Author:
tw2113
Message:

Second pass at Messages Component docs cleanup.

See #6403.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/bp-messages/classes/class-bp-messages-thread.php

    r10139 r10304  
    112112     * @see BP_Messages_Thread::populate() for full description of parameters.
    113113     *
    114      * @param bool   $thread_id
    115      * @param string $order
    116      * @param array  $args
     114     * @param bool   $thread_id ID for the message thread.
     115     * @param string $order     Order to display the messages in.
     116     * @param array  $args      Array of arguments for thread querying.
    117117     */
    118118    public function __construct( $thread_id = false, $order = 'ASC', $args = array() ) {
     
    131131     * @param int    $thread_id The message thread ID.
    132132     * @param string $order     The order to sort the messages. Either 'ASC' or 'DESC'.
    133      * @param array $args {
     133     * @param array  $args {
    134134     *     Array of arguments.
    135135     *     @type bool $update_meta_cache Whether to pre-fetch metadata for
     
    144144        }
    145145
    146         // merge $args with our defaults
     146        // Merge $args with our defaults.
    147147        $r = wp_parse_args( $args, array(
    148148            'user_id'           => bp_loggedin_user_id(),
     
    153153        $this->thread_id      = (int) $thread_id;
    154154
    155         // get messages for thread
     155        // Get messages for thread.
    156156        $this->messages = self::get_messages( $this->thread_id );
    157157
     
    160160        }
    161161
    162         // flip if order is DESC
     162        // Flip if order is DESC.
    163163        if ( 'DESC' === $order ) {
    164164            $this->messages = array_reverse( $this->messages );
     
    176176        }
    177177
    178         // Fetch the recipients
     178        // Fetch the recipients.
    179179        $this->recipients = $this->get_recipients();
    180180
    181         // Get the unread count for the logged in user
     181        // Get the unread count for the logged in user.
    182182        if ( isset( $this->recipients[ $r['user_id'] ] ) ) {
    183183            $this->unread_count = $this->recipients[ $r['user_id'] ]->unread_count;
    184184        }
    185185
    186         // Grab all message meta
     186        // Grab all message meta.
    187187        if ( true === (bool) $r['update_meta_cache'] ) {
    188188            bp_messages_update_meta_cache( wp_list_pluck( $this->messages, 'id' ) );
     
    228228     *
    229229     * @param int $thread_id The thread ID.
    230      *
    231230     * @return array
    232231     */
     
    275274     * @param int $thread_id The message thread ID.
    276275     *
    277      * @return array
     276     * @return object List of messages associated with a thread.
    278277     */
    279278    public static function get_messages( $thread_id = 0 ) {
     
    286285            $bp = buddypress();
    287286
    288             // always sort by ASC by default
     287            // Always sort by ASC by default.
    289288            $messages = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$bp->messages->table_name_messages} WHERE thread_id = %d ORDER BY date_sent ASC", $thread_id ) );
    290289
     
    300299     * @since 2.3.0
    301300     *
    302      * @param  int $thread_id The thread ID.
    303      *
     301     * @param int $thread_id The thread ID.
    304302     * @return array
    305303     */
     
    318316     *
    319317     * @param int $thread_id The message thread ID.
    320      *
    321318     * @return bool
    322319     */
     
    340337        //
    341338        // @todo the reliance on bp_loggedin_user_id() sucks for plugins
    342         //       refactor this method to accept a $user_id parameter
     339        // refactor this method to accept a $user_id parameter.
    343340        $wpdb->query( $wpdb->prepare( "UPDATE {$bp->messages->table_name_recipients} SET is_deleted = 1 WHERE thread_id = %d AND user_id = %d", $thread_id, bp_loggedin_user_id() ) );
    344341
    345         // Get the message ids in order to pass to the action
     342        // Get the message ids in order to pass to the action.
    346343        $message_ids = $wpdb->get_col( $wpdb->prepare( "SELECT id FROM {$bp->messages->table_name_messages} WHERE thread_id = %d", $thread_id ) );
    347344
    348         // Check to see if any more recipients remain for this message
     345        // Check to see if any more recipients remain for this message.
    349346        $recipients = $wpdb->get_results( $wpdb->prepare( "SELECT id FROM {$bp->messages->table_name_recipients} WHERE thread_id = %d AND is_deleted = 0", $thread_id ) );
    350347
    351         // No more recipients so delete all messages associated with the thread
     348        // No more recipients so delete all messages associated with the thread.
    352349        if ( empty( $recipients ) ) {
    353350
     
    362359            do_action( 'bp_messages_thread_before_delete', $thread_id, $message_ids );
    363360
    364             // Delete all the messages
     361            // Delete all the messages.
    365362            $wpdb->query( $wpdb->prepare( "DELETE FROM {$bp->messages->table_name_messages} WHERE thread_id = %d", $thread_id ) );
    366363
    367             // Do something for each message ID
     364            // Do something for each message ID.
    368365            foreach ( $message_ids as $message_id ) {
    369366
    370                 // Delete message meta
     367                // Delete message meta.
    371368                bp_messages_delete_meta( $message_id );
    372369
     
    381378            }
    382379
    383             // Delete all the recipients
     380            // Delete all the recipients.
    384381            $wpdb->query( $wpdb->prepare( "DELETE FROM {$bp->messages->table_name_recipients} WHERE thread_id = %d", $thread_id ) );
    385382        }
     
    420417        global $wpdb;
    421418
    422         // Backward compatibility with old method of passing arguments
     419        // Backward compatibility with old method of passing arguments.
    423420        if ( ! is_array( $args ) || func_num_args() > 1 ) {
    424421            _deprecated_argument( __METHOD__, '2.2.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) );
     
    470467        $r['user_id'] = (int) $r['user_id'];
    471468
    472         // Default deleted SQL
     469        // Default deleted SQL.
    473470        $deleted_sql = 'r.is_deleted = 0';
    474471
     
    485482
    486483            default :
    487                 // Omit user-deleted threads from all other custom message boxes
     484                // Omit user-deleted threads from all other custom message boxes.
    488485                $deleted_sql = $wpdb->prepare( '( r.user_id = %d AND r.is_deleted = 0 )', $r['user_id'] );
    489486                break;
    490487        }
    491488
    492         // Process meta query into SQL
     489        // Process meta query into SQL.
    493490        $meta_query = self::get_meta_query_sql( $r['meta_query'] );
    494491        if ( ! empty( $meta_query['join'] ) ) {
     
    501498        $bp = buddypress();
    502499
    503         // set up SQL array
     500        // Set up SQL array.
    504501        $sql = array();
    505502        $sql['select'] = 'SELECT m.thread_id, MAX(m.date_sent) AS date_sent';
     
    508505        $sql['misc']   = "GROUP BY m.thread_id ORDER BY date_sent DESC {$pag_sql}";
    509506
    510         // get thread IDs
     507        // Get thread IDs.
    511508        $thread_ids = $wpdb->get_results( implode( ' ', $sql ) );
    512509        if ( empty( $thread_ids ) ) {
     
    514511        }
    515512
    516         // adjust $sql to work for thread total
     513        // Adjust $sql to work for thread total.
    517514        $sql['select'] = 'SELECT COUNT( DISTINCT m.thread_id )';
    518515        unset( $sql['misc'] );
    519516        $total_threads = $wpdb->get_var( implode( ' ', $sql ) );
    520517
    521         // Sort threads by date_sent
     518        // Sort threads by date_sent.
    522519        foreach( (array) $thread_ids as $thread ) {
    523520            $sorted_threads[ $thread->thread_id ] = strtotime( $thread->date_sent );
     
    559556     * @param array $meta_query An array of meta_query filters. See the
    560557     *                          documentation for WP_Meta_Query for details.
    561      *
    562558     * @return array $sql_array 'join' and 'where' clauses.
    563559     */
     
    574570
    575571            // WP_Meta_Query expects the table name at
    576             // $wpdb->messagemeta
     572            // $wpdb->messagemeta.
    577573            $wpdb->messagemeta = buddypress()->messages->table_name_meta;
    578574
     
    629625     * @param string $type    The type of messages to get. Either 'all' or 'unread'.
    630626     *                        or 'read'. Defaults to 'all'.
    631      * @return int
     627     * @return int $value Total thread count for the provided user.
    632628     */
    633629    public static function get_total_threads_for_user( $user_id, $box = 'inbox', $type = 'all' ) {
     
    656652     *
    657653     * @param int $thread_id The message thread ID.
    658      *
    659654     * @return bool
    660655     */
     
    679674     *
    680675     * @param int $thread_id The message thread ID.
    681      *
    682676     * @return string|bool The user link on success. Boolean false on failure.
    683677     */
     
    700694     *
    701695     * @param int $user_id The user ID.
    702      *
    703      * @return int
     696     * @return int $unread_count Total inbox unread count for user.
    704697     */
    705698    public static function get_inbox_count( $user_id = 0 ) {
     
    738731     * @param int $thread_id The message thread ID.
    739732     * @param int $user_id   The user ID.
    740      *
    741733     * @return int|null The recorded recipient ID on success, null on failure.
    742734     */
     
    762754     *
    763755     * @param int $thread_id The message thread ID.
    764      *
    765756     * @return int|null The message thread ID on success, null on failure.
    766757     */
    767758    public static function is_valid( $thread_id = 0 ) {
    768759
    769         // Bail if no thread ID is passed
     760        // Bail if no thread ID is passed.
    770761        if ( empty( $thread_id ) ) {
    771762            return false;
     
    792783     *
    793784     * @param array $recipients Array containing the message recipients (array of objects).
    794      *
    795      * @return string
     785     * @return string $value String of message recipent userlinks.
    796786     */
    797787    public static function get_recipient_links( $recipients ) {
     
    831821        $threads   = $wpdb->get_results( "SELECT * FROM {$bp_prefix}bp_messages_threads" );
    832822
    833         // Nothing to update, just return true to remove the table
     823        // Nothing to update, just return true to remove the table.
    834824        if ( empty( $threads ) ) {
    835825            return true;
     
    844834                $message_ids = implode( ',', $message_ids );
    845835
    846                 // Add the thread_id to the messages table
     836                // Add the thread_id to the messages table.
    847837                if ( ! $wpdb->query( $wpdb->prepare( "UPDATE {$bp->messages->table_name_messages} SET thread_id = %d WHERE id IN ({$message_ids})", $thread->id ) ) ) {
    848838                    $errors = true;
Note: See TracChangeset for help on using the changeset viewer.