function privatemsg_new_thread in Privatemsg 6

Same name and namespace in other branches

1. 6.2 privatemsg.module \privatemsg_new_thread()
2. 7.2 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

8 calls to privatemsg_new_thread()

PrivatemsgAPITestCase::testPrivatemsgApiNewThread in tests/privatemsgapi.test

PrivatemsgAPITestCase::testPrivatemsgApiReply in tests/privatemsgapi.test

PrivatemsgBlockUserCase::testBlockAndUnblock in pm_block_user/pm_block_user.test

PrivatemsgTagsTestCase::testCreateUserTag in privatemsg_filter/privatemsg_filter.test

PrivatemsgTagsTestCase::testInboxTagging in privatemsg_filter/privatemsg_filter.test

... See full list

File

./privatemsg.module, line 1637

Allows users to send private messages to other users.

Code

function privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array()) {
  global $user;
  $author = drupal_clone($user);
  $message = array();
  $message['subject'] = $subject;
  $message['body'] = $body;

  // Make sure that recipients are keyed by user id and are not added
  // multiple times.
  foreach ($recipients as $recipient) {
    $message['recipients'][$recipient->uid] = $recipient;
  }

  // Set custom options, if any.
  if (!empty($options)) {
    $message += $options;
  }

  // Apply defaults - this will not overwrite existing keys.
  $message += array(
    'author' => $author,
    'timestamp' => time(),
    'format' => filter_resolve_format(FILTER_FORMAT_DEFAULT),
  );
  $validated = _privatemsg_validate_message($message);
  if ($validated['success']) {
    $validated['message'] = _privatemsg_send($message);
  }
  return $validated;
}