Message Module API

The Message module is a general logging utility tool which you can use to log any type of activity on a Drupal website. I’ve already written about how you can use Message module with Rules. If you’ve never used this module I would recommend that you read "Log Site Activity with Message and Rules" first, so you can get a good introduction on how to use Message module.

In this article we’ll look at creating messages programmatically via Entity’s entity_metadata_wrapper() function. Finally we’ll look at how to load and display a message log. This is useful if you need to manually add a message to a template file.

The Message module ships with a message_example module. Enable this module to see the code below in action.

Create Message Logs

If you want to follow along, go to Structure -> "Message types" (admin/structure/messages) and create a message type with the values detailed in Table 1-1.

Table 1-1. Creating a message type

Now let's jump into some code. To create a message log simply run:

$values = array(
  'arguments' => array(
    '!action' => ‘Content updated’, 
    '@name' => ‘John’),
);
$message = message_create('ww_node_log', $values);
$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->save();

When we created the message log, we added !action by @name. into the message text. These replacement tokens would then be replaced by "Content updated by John.".

In the arguments array within the $values variable, all you need to do is define what the token should be replaced with. The $message variable is used to create the message object. All we need to pass the message_create function is message type and the $values variable defining the arguments. The $wrapper will be used to load entity_metadata_wrapper function from Entity API module and finally we just save the message with $wrapper->save().

If you have attached a field to the message type, just set the field value by using entity_metadata_wrapper’s set method. 

For example:

$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->field_published->set($node->status);
$wrapper->save();

View Message Logs

In the last section we looked at creating a message log, now let’s look at loading and displaying a message. Most of the time you’ll use Views to display or list messages, however, it’s still good to know how to do all of this via code.

$message = message_load(5);
$message->getText();

In the above code example, all we have done is load a message with the message ID of 5 and display the message text via getText() method, that's the simplest example.

If you've attached a field to the message type, then you'll have to pass the $message variable via the entity_metadata_wrapper function.

For example:

$message = message_load(5);
$message->getText();
$wrapper = entity_metadata_wrapper('message', $message);
$wrapper->field_published->value();

$wrapper->field_published->value(); will display the value for the field_published field attached to the message log.

I hope you've learned something new today about the Message module. If you have any question please leave a comment below.