 |
VOOZH | about |
|
VOOZH | about |
This page provides an overview of the message construction layer in the hypervel/notifications package. Message classes define the content and structure of notifications for specific delivery channels, but do not handle the actual delivery logic.
For detailed guides on constructing specific message types, see:
For information about how messages are delivered through channels, see Notification Channels.
The package provides three primary message classes, each designed for a specific delivery channel:
| Message Class | Channel | Base Class | Purpose |
|---|---|---|---|
MailMessage | mail | SimpleMessage | Email notifications with views, attachments, and recipients |
SlackMessage | slack | None | Slack notifications with Block Kit support |
BroadcastMessage | broadcast | None | Real-time event data for broadcasting |
Diagram: Message Class Hierarchy
Sources: src/Messages/SimpleMessage.php1-231 src/Messages/MailMessage.php1-333 src/Slack/SlackMessage.php1-336
The SimpleMessage class provides common structure for notification content, primarily used by MailMessage. It defines a standard notification format with greeting, intro lines, an optional action button, and outro lines.
Properties:
| Property | Type | Purpose |
|---|---|---|
level | string | Notification level: info, success, or error |
subject | string|null | Subject line for the notification |
greeting | string|null | Opening greeting text |
salutation | string|null | Closing salutation text |
introLines | array | Lines of text before the action button |
outroLines | array | Lines of text after the action button |
actionText | string|null | Call-to-action button text |
actionUrl | string|null | URL for the action button |
Key Methods:
success(): Set level to successerror(): Set level to errorsubject($subject): Set subject linegreeting($greeting): Set greeting textline($line): Add content lineaction($text, $url): Configure action buttonThe with() method src/Messages/SimpleMessage.php164-175 intelligently places content: lines added before action() go into introLines, and lines added after go into outroLines.
Sources: src/Messages/SimpleMessage.php10-231
All message classes implement a fluent interface pattern, allowing method chaining to construct messages declaratively:
Diagram: Message Construction Flow
Sources: src/Messages/SimpleMessage.php60-202 src/Messages/MailMessage.php93-332 src/Slack/SlackMessage.php90-291
MailMessage extends SimpleMessage to add email-specific functionality while inheriting the base structure. This extension pattern allows emails to use the standard greeting/lines/action format or provide custom views.
Extended Properties:
view: Custom HTML/text view templatesmarkdown: Markdown template path (default: notifications::email)theme: Theme for Markdown renderingfrom, replyTo, cc, bccattachments, rawAttachmentstags, metadata, priorityView Selection Logic:
The render() method src/Messages/MailMessage.php306-322 implements this logic:
view is set, render using the mailer's template engineMarkdown service to render the markdown template with the base message structureSources: src/Messages/MailMessage.php16-333
Unlike MailMessage, SlackMessage does not extend SimpleMessage. It uses a completely different structure optimized for Slack's Block Kit API.
Core Properties:
channel: Target Slack channeltext: Fallback text for notificationsblocks: Array of Block Kit blocksusername: Bot username overrideicon (emoji) or image (URL)threadTs, broadcastReplyBlock Kit Methods:
Slack messages are constructed using Block Kit builder methods:
actionsBlock($callback): Add interactive buttonscontextBlock($callback): Add contextual informationdividerBlock(): Add visual dividerheaderBlock($text): Add header textimageBlock($url, $altText): Add imagesectionBlock($callback): Add text section with optional accessoryFor detailed information on Block Kit components, see Slack Block Kit.
Sources: src/Slack/SlackMessage.php21-336
Notification classes define which channels to use via the via() method, and provide channel-specific messages through methods like toMail(), toSlack(), or toBroadcast():
Diagram: Message Construction and Channel Delivery
Sources: src/Messages/MailMessage.php1-333 src/Slack/SlackMessage.php1-336
Both MailMessage and SlackMessage use the Conditionable trait src/Messages/MailMessage.php18 src/Slack/SlackMessage.php23 which provides conditional method chaining:
This allows dynamic message construction based on runtime conditions without breaking the fluent interface chain.
Sources: src/Messages/MailMessage.php18 src/Slack/SlackMessage.php23
Messages implement validation to ensure they can be successfully delivered:
MailMessage: No explicit validation; relies on underlying mailer to validate addresses
SlackMessage: Validates before conversion to array src/Slack/SlackMessage.php296-304:
text or blocksLogicException if validation failsBroadcastMessage: Minimal structure; primarily wraps arbitrary data
Sources: src/Slack/SlackMessage.php296-304
Message classes implement toArray() to convert their structure into formats expected by delivery channels:
SimpleMessage src/Messages/SimpleMessage.php217-230: Returns all properties including computed displayableActionUrl
MailMessage src/Messages/MailMessage.php280-283: Merges base array with viewData for template rendering
SlackMessage src/Slack/SlackMessage.php296-323: Converts blocks to arrays, filters null values, formats for Slack API
The array representation is consumed by channels during the send operation.
Sources: src/Messages/SimpleMessage.php217-230 src/Messages/MailMessage.php280-283 src/Slack/SlackMessage.php296-323
SlackMessage provides a dd() method src/Slack/SlackMessage.php328-335 for debugging:
dd(true): Dumps raw array structuredd(): Generates URL to Slack Block Kit Builder with message payloadThis allows developers to preview Slack messages in Slack's official builder tool before sending.
Sources: src/Slack/SlackMessage.php328-335