messages_new_message

Create a new message.

Description

(int|bool|WP_Error) messages_new_message( (string) $args = '' ); 

Returns (int|bool|WP_Error)

ID of the message thread on success, false on failure.

Parameters (1)

0. $args — Optional. (string) => ''
Array of arguments.

Options

  • sender_id (int) => 0

    ID of the user who is sending the message. Default: ID of the logged-in user.

  • thread_id (int) => 0

    ID of the parent thread. Leave blank to create a new thread for the message.

  • recipients (array) => null

    IDs or usernames of message recipients. If this is an existing thread, it is unnecessary to pass a $recipients argument - existing thread recipients will be assumed.

  • subject (string) => ''

    Subject line for the message. For existing threads, the existing subject will be used. For new threads, No Subject will be used if no $subject is provided.

  • content (string) => ''

    Content of the message. Cannot be empty.

  • date_sent (string) => ''

    Date sent, in Y-m-d H:i:s format. Default: current date/time.

array(

    /**
     * Optional. ID of the user who is sending the message. Default: ID of the logged-in user.
     *
     * @type int
     * @optional
     */
    'sender_id' => 0,

    /**
     * Optional. ID of the parent thread. Leave blank to create a new thread for the message.
     *
     * @type int
     * @optional
     */
    'thread_id' => 0,

    /**
     * IDs or usernames of message recipients. If this is an existing thread, it is unnecessary to
     * pass a $recipients argument - existing thread recipients will be assumed.
     *
     * @type array
     * @default null
     */
    'recipients' => null,

    /**
     * Optional. Subject line for the message. For existing threads, the existing subject will be
     * used. For new threads, 'No Subject' will be used if no $subject is provided.
     *
     * @type string
     * @default ''
     * @optional
     */
    'subject' => '',

    /**
     * Content of the message. Cannot be empty.
     *
     * @type string
     * @default ''
     */
    'content' => '',

    /**
     * Date sent, in 'Y-m-d H:i:s' format. Default: current date/time.
     *
     * @type string
     * @default ''
     */
    'date_sent' => ''
);        


Usage

  1. if ( !function_exists( 'messages_new_message' ) ) { 
  2. require_once '/bp-messages/bp-messages-functions.php'; 
  3.  
  4. // Array of arguments. 
  5. $args = array( 
  6. 'sender_id' => 0, 
  7. 'thread_id' => 0, 
  8. 'recipients' => null, 
  9. 'subject' => '', 
  10. 'content' => '', 
  11. 'date_sent' => '' 
  12. ); 
  13.  
  14. // NOTICE! Understand what this does before running. 
  15. $result = messages_new_message($args); 
  16.  

Defined (1)

The function is defined in the following location(s).

/bp-messages/bp-messages-functions.php  
  1. function messages_new_message( $args = '' ) { 
  2.  
  3. // Parse the default arguments. 
  4. $r = bp_parse_args( $args, array( 
  5. 'sender_id' => bp_loggedin_user_id(),  
  6. 'thread_id' => false, // False for a new message, thread id for a reply to a thread. 
  7. 'recipients' => array(), // Can be an array of usernames, user_ids or mixed. 
  8. 'subject' => false,  
  9. 'content' => false,  
  10. 'date_sent' => bp_core_current_time(),  
  11. 'error_type' => 'bool' 
  12. ), 'messages_new_message' ); 
  13.  
  14. // Bail if no sender or no content. 
  15. if ( empty( $r['sender_id'] ) || empty( $r['content'] ) ) { 
  16. if ( 'wp_error' === $r['error_type'] ) { 
  17. if ( empty( $r['sender_id'] ) ) { 
  18. $error_code = 'messages_empty_sender'; 
  19. $feedback = __( 'Your message was not sent. Please use a valid sender.', 'buddypress' ); 
  20. } else { 
  21. $error_code = 'messages_empty_content'; 
  22. $feedback = __( 'Your message was not sent. Please enter some content.', 'buddypress' ); 
  23.  
  24. return new WP_Error( $error_code, $feedback ); 
  25.  
  26. } else { 
  27. return false; 
  28.  
  29. // Create a new message object. 
  30. $message = new BP_Messages_Message; 
  31. $message->thread_id = $r['thread_id']; 
  32. $message->sender_id = $r['sender_id']; 
  33. $message->subject = $r['subject']; 
  34. $message->message = $r['content']; 
  35. $message->date_sent = $r['date_sent']; 
  36.  
  37. // If we have a thread ID... 
  38. if ( ! empty( $r['thread_id'] ) ) { 
  39.  
  40. // ...use the existing recipients 
  41. $thread = new BP_Messages_Thread( $r['thread_id'] ); 
  42. $message->recipients = $thread->get_recipients(); 
  43.  
  44. // Strip the sender from the recipient list, and unset them if they are 
  45. // not alone. If they are alone, let them talk to themselves. 
  46. if ( isset( $message->recipients[ $r['sender_id'] ] ) && ( count( $message->recipients ) > 1 ) ) { 
  47. unset( $message->recipients[ $r['sender_id'] ] ); 
  48.  
  49. // Set a default reply subject if none was sent. 
  50. if ( empty( $message->subject ) ) { 
  51. $message->subject = sprintf( __( 'Re: %s', 'buddypress' ), $thread->messages[0]->subject ); 
  52.  
  53. // ...otherwise use the recipients passed 
  54. } else { 
  55.  
  56. // Bail if no recipients. 
  57. if ( empty( $r['recipients'] ) ) { 
  58. if ( 'wp_error' === $r['error_type'] ) { 
  59. return new WP_Error( 'message_empty_recipients', __( 'Message could not be sent. Please enter a recipient.', 'buddypress' ) ); 
  60. } else { 
  61. return false; 
  62.  
  63. // Set a default subject if none exists. 
  64. if ( empty( $message->subject ) ) { 
  65. $message->subject = __( 'No Subject', 'buddypress' ); 
  66.  
  67. // Setup the recipients array. 
  68. $recipient_ids = array(); 
  69.  
  70. // Invalid recipients are added to an array, for future enhancements. 
  71. $invalid_recipients = array(); 
  72.  
  73. // Loop the recipients and convert all usernames to user_ids where needed. 
  74. foreach ( (array) $r['recipients'] as $recipient ) { 
  75.  
  76. // Trim spaces and skip if empty. 
  77. $recipient = trim( $recipient ); 
  78. if ( empty( $recipient ) ) { 
  79. continue; 
  80.  
  81. // Check user_login / nicename columns first 
  82. // @see http://buddypress.trac.wordpress.org/ticket/5151. 
  83. if ( bp_is_username_compatibility_mode() ) { 
  84. $recipient_id = bp_core_get_userid( urldecode( $recipient ) ); 
  85. } else { 
  86. $recipient_id = bp_core_get_userid_from_nicename( $recipient ); 
  87.  
  88. // Check against user ID column if no match and if passed recipient is numeric. 
  89. if ( empty( $recipient_id ) && is_numeric( $recipient ) ) { 
  90. if ( bp_core_get_core_userdata( (int) $recipient ) ) { 
  91. $recipient_id = (int) $recipient; 
  92.  
  93. // Decide which group to add this recipient to. 
  94. if ( empty( $recipient_id ) ) { 
  95. $invalid_recipients[] = $recipient; 
  96. } else { 
  97. $recipient_ids[] = (int) $recipient_id; 
  98.  
  99. // Strip the sender from the recipient list, and unset them if they are 
  100. // not alone. If they are alone, let them talk to themselves. 
  101. $self_send = array_search( $r['sender_id'], $recipient_ids ); 
  102. if ( ! empty( $self_send ) && ( count( $recipient_ids ) > 1 ) ) { 
  103. unset( $recipient_ids[ $self_send ] ); 
  104.  
  105. // Remove duplicates & bail if no recipients. 
  106. $recipient_ids = array_unique( $recipient_ids ); 
  107. if ( empty( $recipient_ids ) ) { 
  108. if ( 'wp_error' === $r['error_type'] ) { 
  109. return new WP_Error( 'message_invalid_recipients', __( 'Message could not be sent because you have entered an invalid username. Please try again.', 'buddypress' ) ); 
  110. } else { 
  111. return false; 
  112.  
  113. // Format this to match existing recipients. 
  114. foreach ( (array) $recipient_ids as $i => $recipient_id ) { 
  115. $message->recipients[ $i ] = new stdClass; 
  116. $message->recipients[ $i ]->user_id = $recipient_id; 
  117.  
  118. // Bail if message failed to send. 
  119. $send = $message->send(); 
  120. if ( false === is_int( $send ) ) { 
  121. if ( 'wp_error' === $r['error_type'] ) { 
  122. if ( is_wp_error( $send ) ) { 
  123. return $send; 
  124. } else { 
  125. return new WP_Error( 'message_generic_error', __( 'Message was not sent. Please try again.', 'buddypress' ) ); 
  126.  
  127. return false; 
  128.  
  129. /** 
  130. * Fires after a message has been successfully sent. 
  131. * @since 1.1.0 
  132. * @param BP_Messages_Message $message Message object. Passed by reference. 
  133. */ 
  134. do_action_ref_array( 'messages_message_sent', array( &$message ) ); 
  135.  
  136. // Return the thread ID. 
  137. return $message->thread_id;