Message
A general message logging utility that provides a flexible message entity system for creating activity streams, notifications, and event logging.
message
Install
composer require 'drupal/message:8.x-1.8'
Overview
The Message module provides the core of the message stack, offering a comprehensive message entity system for Drupal. It introduces a Message content entity type that can be organized into multiple message templates (bundles), enabling flexible message logging and display functionality.
Key capabilities include dynamic token replacement in message text, custom callback arguments for runtime content generation, and a partial system allowing message text to be split into multiple reusable components. The module integrates seamlessly with Views for message display, supports multilingual content, and provides automatic message purging based on age or quota limits.
The module serves three primary use cases: logging and displaying system events (activity streams similar to Facebook's News Feed), notifying users when messages are generated (via Message Notify module), and notifying subscribers when content they follow is updated (via Message Subscribe module).
Features
- Message content entity with configurable templates (bundles) for organizing different message types
- MessageTemplate configuration entity serving as bundles with multi-value text fields (partials)
- Dynamic token replacement using Drupal's token system for runtime content injection
- Single-use tokens that are replaced at message creation time for performance optimization
- Custom callback arguments allowing PHP functions to generate replacement values
- Message text partials system enabling separation of HTML markup from content and selective rendering
- View modes support for controlling message display per template via Manage Display
- Automatic message purging via cron based on age (days) or quantity (quota) limits
- Per-template purge setting overrides for fine-grained message retention control
- Automatic deletion of messages when referenced entities are deleted
- Full Views integration with custom field handler for message text display
- Multilingual support with translatable messages and templates
- Bulk operations support for message management
- Migration support from Drupal 7 message module
- Integration points for Rules module via Entity API
Use Cases
Activity Stream / News Feed
Create a Facebook-style activity stream showing user actions. Define message templates for different activities (created content, commented, followed user), use tokens to inject dynamic content (usernames, content titles, links), and display messages using Views. Messages automatically include timestamps and author information.
System Event Logging
Log important system events beyond Drupal's core logging. Create templates for events like user registration, content publication, or workflow transitions. Use callbacks to capture complex data at event time, and leverage purge settings to manage log growth automatically.
User Notifications Center
Build a notification inbox for users. Create message templates for notification types, attach messages to users via entity reference fields, use Message Notify to send email digests, and display unread notifications using Views with exposed filters.
Content Change Tracking
Track changes to important content. Create templates with single-use tokens to capture content state at modification time, store references to the modified entities, and build audit trails showing who changed what and when.
Subscription-Based Updates
Notify users about content they follow. Combine with Message Subscribe and Flag modules to let users subscribe to content, then automatically generate and deliver messages when subscribed content changes, using per-user notification preferences.
Multilingual Notifications
Send messages in users' preferred languages. Create translated message templates using Configuration Translation, set message language based on recipient preferences, and let the token system resolve translations appropriately.
Tips
- Use single-use tokens (@{token}) for data that won't change, improving performance by avoiding repeated token lookups at display time.
- Split message text into multiple partials to separate HTML structure from content, enabling flexible display configurations per view mode.
- Configure per-template purge settings for different retention needs - keep system messages longer while cleaning up ephemeral notifications quickly.
- Use the Message Example submodule to learn implementation patterns before building your own message system.
- Leverage the custom Views 'get_text' field with delta parameter to display specific partials in different parts of your page layout.
- When creating messages programmatically, use setArguments() to pass callback functions that resolve values at display time for dynamic content.
- Enable the Token module to get a helpful token browser when editing message templates.
- Use entity reference fields on messages to create relationships, enabling automatic cleanup when referenced content is deleted.
Technical Details
Admin Pages 6
/admin/structure/message
Lists all available message templates. From this page you can add, edit, and delete message templates that define the structure and content of different message types.
/admin/structure/message/template/add
Create a new message template that defines the structure and text content for a specific type of message.
/admin/structure/message/manage/{message_template}
Edit an existing message template including its label, description, text content, and purge settings.
/admin/config/message
Main configuration landing page for the Message module. Provides access to message-related configuration pages.
/admin/config/message/message
Configure global message settings including automatic purging and entity deletion behavior.
/admin/content/message
View and manage all message entities. Displays messages in a table with bulk operations support, filtering by template, and sortable columns.
Permissions 3
Hooks 7
hook_message_view
Act on a message that is being assembled before rendering. Allows adding elements to the message content array.
hook_message_view_alter
Alter the results of entity_view() for messages after content has been assembled. Can modify weights, add post_render callbacks.
hook_default_message_template
Define default message template configurations that can be created programmatically.
hook_default_message_template_alter
Alter default message template configurations before they are used.
hook_form_message_template_form_alter
Alter message template forms. Can be used with #entity_builders to copy form values to the entity.
hook_default_message_category
Define default message template category configurations.
hook_default_message_category_alter
Alter default message template category configurations.
Troubleshooting 5
Ensure cron is running regularly. Check that 'Purge messages' is enabled at /admin/config/message/message with at least one purge method configured. For per-template purging, verify 'Override global purge settings' is checked on the template.
Verify that 'Token replace' is checked in the message template settings. Ensure the Token module is installed for the token browser. Check that tokens are using correct syntax: [message:field_name] for message fields.
Check that the entity type is selected in 'Auto delete messages referencing the following entities' at /admin/config/message/message. Only entity_reference fields trigger automatic deletion.
Navigate to the message template's 'Manage display' tab at /admin/structure/message/manage/[template]/display and configure which partials are visible for each view mode.
Ensure d7_filter_format migration runs first (dependency). Check that source database connection is configured. Verify message module was enabled on the D7 site.
Security Notes 5
- The module filters message template descriptions using Xss::filterAdmin() to prevent XSS attacks.
- Message text uses Drupal's text format system with proper sanitization via check_markup equivalent.
- Access to message administration requires specific permissions - grant 'administer messages' and 'administer message templates' carefully.
- The 'overview messages' permission controls access to the message listing view - consider content sensitivity when granting.
- Callback functions in message arguments are executed at display time - ensure callbacks are trusted code paths.