function privatemsg_new_thread in Privatemsg 7.2

Same name and namespace in other branches

1. 6.2 privatemsg.module \privatemsg_new_thread()
2. 6 privatemsg.module \privatemsg_new_thread()
3. 7 privatemsg.module \privatemsg_new_thread()

Send a new message.

This functions does send a message in a new thread. Example:

privatemsg_new_thread(array(
  user_load(5),
), 'The subject', 'The body text');

Parameters

$recipients: Array of recipients (user objects)

$subject: The subject of the new message

$body: The body text of the new message

$options: Additional options, possible keys: author => User object of the author timestamp => Time when the message was sent

Return value

An array with a key success. If TRUE, it also contains a key 'message' with the created $message array, the same that is passed to the insert hook. If FALSE, it contains a key 'messages'. This key contains an array where the key is the error type (error, warning, notice) and an array with messages of that type.

It is theoretically possible for success to be TRUE and message to be FALSE. For example if one of the privatemsg database tables become corrupted. When testing for success of message being sent it is always best to see if ['message'] is not FALSE as well as ['success'] is TRUE.

Example:

array(
  'error' => array(
    'A error message',
  ),
);

Related topics

19 calls to privatemsg_new_thread()

PrivatemsgAPITestCase::testPrivatemsgApiNewThread in ./privatemsg.test

PrivatemsgAPITestCase::testPrivatemsgApiReply in ./privatemsg.test

PrivatemsgBlockUserCase::testBlockAndUnblock in pm_block_user/pm_block_user.test

PrivatemsgFilterWidgetTestCase::testAuthorSearch in privatemsg_filter/privatemsg_filter.test

Generic filter widget tests.

PrivatemsgGroupsTestCase::testSendMessagetoGroupAPI in privatemsg_groups/privatemsg_groups.test

Test sending message to a group using privatemsg_new_thread API method.

... See full list

File

./privatemsg.module, line 1690

Allows users to send private messages to other users.

Code

function privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array()) {
  global $user;
  $author = clone $user;
  $message = (object) $options;
  $message->subject = $subject;
  $message->body = $body;

  // Make sure that recipients are keyed correctly and are not added
  // multiple times.
  foreach ($recipients as $recipient) {
    if (!isset($recipient->type)) {
      $recipient->type = 'user';
      $recipient->recipient = $recipient->uid;
    }
    $message->recipients[privatemsg_recipient_key($recipient)] = $recipient;
  }

  // Apply defaults - this will not overwrite existing keys.
  if (!isset($message->author)) {
    $message->author = $author;
  }
  if (!isset($message->timestamp)) {
    $message->timestamp = REQUEST_TIME;
  }
  if (!isset($message->format)) {
    $message->format = filter_default_format($message->author);
  }
  $validated = _privatemsg_validate_message($message);
  if ($validated['success']) {
    $validated['message'] = _privatemsg_send($message);
    if ($validated['message'] !== FALSE) {
      _privatemsg_handle_recipients($validated['message']->mid, $validated['message']->recipients, FALSE);
    }
  }
  return $validated;
}