Module Architecture (For Developers)

This is an overview of the architecture of the Private Message module. This page is for developers who wish to extend the module or contribute to changes moving forward.

Entity Types

This module creates four entity types, private message, private message thread, thread access time, and thread delete time.

Private Message entity

The private message entity stores an individual private message.

Fields (machine name)

• Private message ID (id): The unique ID of the private message.
• UUID (uuid): The Universally Unique Identifier of the message will be unique across all environments.
• From (owner): The user who created the message.
• Created (created): The timestamp at which the message was created.
• Message (message):  A single value field of base property type text_long. Has no label.

Private Message Thread entity

The private message thread entity brings together private messages and users to create a private message thread. Threads are created in the background when a user creates a message with a combination of users who have never had a thread together. When creating a message, if a user puts together a combination of users for whom a thread already exists, that thread is used, rather than creating a new thread.

Private message threads have a concept of soft-delete, as well as hard-delete. The soft delete function works when a user chooses to delete a thread. For this user, the thread will appear to have been deleted. However, the thread still exists in the database unless/until all members of the thread have deleted the thread.

Fields (machine name)

• ID (id): The unique ID of the thread.
• UUID (uuid): The Universally Unique Identifier. This will be unique across all environments.
• Updated (updated): The most recent time at which the thread was updated.
• Member(s) (members): An entity reference (to User entities) of all the members of the thread. Unlimited values.
• Messages (private_messages): An entity reference (to Private Message entities) of all thread messages.
• Last Access Times (last_access_time): An entity reference (to Private Message Last Access Time entities) containing a timestamp for the last time each member of the thread accessed the thread.
• Last Delete Times (last_delete_time): An entity reference (to Private Message Last Delete Time entities) containing a timestamp for the last time a user deleted a thread.

Private Message Thread Last Access Time:

The last access time stores the time at which a user last accessed a private message thread. This allows for threads to be given custom classes to indicate whether a thread has new messages in it for the current user.

Fields (machine name)

• ID (id): The unique ID for the entity.
• UUID (uuid): The Universally Unique Identifier for the access time. This will be unique across all environments.
• User Name (owner): A single value entity reference field (to the User object) for the user to whom the last timestamp belongs.
• Access Time (access_time): The timestamp indicating when the user last accessed the thread that references the entity.

Private Message Thread Last Delete Time

As mentioned above, private message threads have a concept of soft-delete, as well as hard-delete. The soft delete function works when a user chooses to delete a thread. The thread will appear to have been deleted for this user, though it still exists in the database until all users have deleted the thread.

This entity provides a timestamp for each user when they delete a thread. If they re-enter the thread (whether initiated by themselves or another user), the only messages shown are those created after the timestamp stored in this entity.

Fields (machine name)

• ID (id): The unique ID for the entity.
• UUID (uuid): The Universally Unique Identifier for the access time. This will be unique across all environments.
• User Name (owner): A single value entity reference field (to the User object) for the user to whom the last timestamp belongs.
• Delete Time (delete_time): The time at which the user deleted the private message thread that references this entity.

Faux Fields

Several 'faux fields' have been set up to allow for the ordering of elements within a view mode for not real fields. These view modes have been set up using hook_entity_extra_field_info(). The following fields have been set up:

• Last Message
  • Entity: Private Message Thread
  • Description: Displays the last message in the thread
• Form
  • Entity: Private Message Thread
  • Description: The private message form, used to create private messages for the thread.
• Delete link
  • Entity: Private Message Thread
  • Description: A link to delete the private message
• Username (linked if the viewer has permission)
  • Entity: User
  • Description: Displays the username, linked to the user profile if the viewer has permission to access user profiles
• Private message thread link [on user]
  • Entity: User
  • Description: Displays a link to send a private message to the user
• Private message thread link [on nodes]
  • Entity: Node
  • Description: Displays a link to send a private message to the node author
• Private message thread link [on comments]
  • Entity: Comment
  • Description: Displays a link to send a private message to the comment author

Whenever new elements related to private messages are added to any entities, a new 'faux field' should be created to allow for the ordering of elements to be handled through view modes.

View Modes

This module provides the following view modes. View modes are used for default output, allowing for added/removed/reordered fields in the output.

• Entity: Private Message Thread
  • View mode: Inbox
    • Description: The display of a private message thread in the private message inbox. It intended to show the last message in the inbox.
• Entity: Private Message
  • View mode: Inbox
    • Description: The display of a message (usually the last message shown) in the private message's inbox.
• User
  • View mode: Private message author
    • Description: A rendering of the user profile, shown in private messages. Allows for avatars to be added etc.

Programmatically Create Private Message

We can programmatically create a private message using our Custom module by following the below code. 

use Drupal\Core\Entity\EntityInterface;
use Drupal\private_message\Entity\PrivateMessage;


  $user1 = User::load($user);
  $user2 = User::load($user2_id);

  $members = [$user1, $user2];
  $service = \Drupal::service('private_message.service');

  // This will create a thread if one does not exist.  
  $private_message_thread = $service->getThreadForMembers($members);

  // Add a Message to the thread.
  $private_message = PrivateMessage::create();
  $private_message->set('owner', $user1);
  $private_message->set('message', 'message text entered here');
  $private_message->save();
  $private_message_thread->addMessage($private_message)->save();

$user1 is the owner of the message, and $user2 is the receiver of the message.  We are using private_message_service to access their Private message thread. If there is a thread, it will take its id and message in that thread. If not, it will create a new thread.