Messaging
Reference for the Messaging module: queue and send email, SMS and push notifications. Each message type has a Send entry point that records the message and leaves it in a per-type queue; a queue worker later hands it to a registered provider or configured vendor, marking it sent or scheduling a retry with backoff.
This page is a pure reference. For how the framework fits together, see the Guide.
MessagingEmail- queue an email for sending.MessagingEmailData- immutable data for a queued email.MessagingEmailDatabase- store, read and process email queue rows.MessagingEmailProviderConfig- register and read email providers.MessagingEmailQueueDatabase- lock and process items on the email queue.MessagingErrorSendFailed- raised when a message fails to send.MessagingNotification- queue a push notification for sending.MessagingNotificationData- immutable data for a queued notification.MessagingNotificationDatabase- store, read and process notification queue rows.MessagingNotificationProviderConfig- register and read notification providers.MessagingNotificationQueueDatabase- lock and process items on the notification queue.MessagingSms- queue an SMS for sending.MessagingSmsDatabase- store, read and process SMS queue rows.MessagingSmsProvider- resolve and use the configured SMS vendor.MessagingSmsProviderConfig- register and read SMS providers.MessagingSmsQueueDatabase- lock and process items on the SMS queue.
MessagingEmail
Entry point for sending email. Records a message and leaves it in the email queue for a worker to deliver through a registered provider.
Send
MessagingEmail::Send(string $fromEmail, string $fromName, string $toEmail, string $toName, string $subject, string $body, string|null $optionalHtml): int
Queue an email for sending. The message is stored with its sent flag unset so a queue worker delivers it later; the new row id is returned.
| Name | Type | Description |
|---|---|---|
$fromEmail | string | The sender email address. |
$fromName | string | The sender display name. |
$toEmail | string | The recipient email address. |
$toName | string | The recipient display name. |
$subject | string | The email subject. |
$body | string | The plain text body. |
$optionalHtml | string|null | An HTML body, or null for text only. |
Returns int The id of the queued email.
SendTemplate
MessagingEmail::SendTemplate(string $templateName, string $fromEmail, string $fromName, string $toEmail, string $toName, mixed $templateArgument): void
Build subject, text and optional HTML from a named template and its argument, then queue the resulting email.
| Name | Type | Description |
|---|---|---|
$templateName | string | The name of the email template to render. |
$fromEmail | string | The sender email address. |
$fromName | string | The sender display name. |
$toEmail | string | The recipient email address. |
$toName | string | The recipient display name. |
$templateArgument | mixed | The value passed to the template callbacks. |
Returns void
MessagingEmailData
Immutable data for a queued email. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$email->id | int | The email row id (readonly). |
$email->fromEmail | string | The sender email address (readonly). |
$email->fromName | string | The sender display name (readonly). |
$email->toEmail | string | The recipient email address (readonly). |
$email->toName | string | The recipient display name (readonly). |
$email->subject | string | The email subject (readonly). |
$email->body | string | The plain text body (readonly). |
$email->optionalHtml | string|null | The HTML body, or null (readonly). |
$email->provider | string|null | The provider that handled the email, or null (readonly). |
$email->resendCounter | int | The number of resend attempts (readonly). |
$email->sent | CalendarDateTimeData|null | When the email was sent, or null (readonly). |
__construct
new MessagingEmailData(int $id = 0, string $fromEmail = '', string $fromName = '', string $toEmail = '', string $toName = '', string $subject = '', string $body = '', string|null $optionalHtml = null, string|null $provider = null, int $resendCounter = 0, CalendarDateTimeData|null $sent = null)
Create an email data object from its fields.
| Name | Type | Description |
|---|---|---|
$id | int | The email row id. |
$fromEmail | string | The sender email address. |
$fromName | string | The sender display name. |
$toEmail | string | The recipient email address. |
$toName | string | The recipient display name. |
$subject | string | The email subject. |
$body | string | The plain text body. |
$optionalHtml | string|null | The HTML body, or null. |
$provider | string|null | The provider that handled the email, or null. |
$resendCounter | int | The number of resend attempts. |
$sent | CalendarDateTimeData|null | When the email was sent, or null. |
Returns MessagingEmailData
MessagingEmailDatabase
Stores email queue rows and reads them back as data objects. Also processes a queued email by handing it to a registered provider and marking it sent.
Add
MessagingEmailDatabase::Add(string $fromEmail, string $fromName, string $toEmail, string $toName, string $subject, string $body, string|null $optionalHtml): int
Insert an email row and return its id.
| Name | Type | Description |
|---|---|---|
$fromEmail | string | The sender email address. |
$fromName | string | The sender display name. |
$toEmail | string | The recipient email address. |
$toName | string | The recipient display name. |
$subject | string | The email subject. |
$body | string | The plain text body. |
$optionalHtml | string|null | An HTML body, or null. |
Returns int The id of the inserted row.
fromRow
MessagingEmailDatabase::fromRow(stdClass $row): MessagingEmailData
Build an email data object from a database row.
| Name | Type | Description |
|---|---|---|
$row | stdClass | The database row to convert. |
Returns MessagingEmailData The email data.
GetById
MessagingEmailDatabase::GetById(int $emailId): MessagingEmailData
Read a single email row by id and return it as a data object.
| Name | Type | Description |
|---|---|---|
$emailId | int | The email row id. |
Returns MessagingEmailData The email data.
IncrementResendAndScheduleRetry
MessagingEmailDatabase::IncrementResendAndScheduleRetry(int $emailId, int $nextRetryAt): void
Increment the resend counter and set the timestamp for the next retry attempt.
| Name | Type | Description |
|---|---|---|
$emailId | int | The email row id. |
$nextRetryAt | int | Unix timestamp when the next retry should be attempted. |
Returns void
ListUnsent
MessagingEmailDatabase::ListUnsent(): array
Every email row that has not yet been sent, as data objects.
Returns array A list of unsent email data.
MarkSent
MessagingEmailDatabase::MarkSent(int $emailId): void
Mark an email as sent, recording the sent timestamp and date.
| Name | Type | Description |
|---|---|---|
$emailId | int | The email row id. |
Returns void
ProcessQueue
MessagingEmailDatabase::ProcessQueue(int $emailId): void
Send a queued email through a randomly chosen registered provider, record the provider, and mark it sent.
| Name | Type | Description |
|---|---|---|
$emailId | int | The email id to process. |
Returns void
MessagingEmailProviderConfig
Lets email provider modules register themselves, and reads the registered providers back. Providers are held as objects with providerId, providerName and sendCallback.
Properties
| Property | Type | Description |
|---|---|---|
MessagingEmailProviderConfig::$providers | array | The registered email provider objects. |
AddProvider
MessagingEmailProviderConfig::AddProvider(string $providerId, string $providerName, callable $sendCallback): void
Register an email provider. Throws when a provider with the same id is already registered.
| Name | Type | Description |
|---|---|---|
$providerId | string | The id of the provider (for example "sendgrid"). |
$providerName | string | The display name of the provider. |
$sendCallback | callable | Callback that sends the email. |
Returns void
GetDefaultProvider
MessagingEmailProviderConfig::GetDefaultProvider(): ?object
The first registered provider, or null when none are registered.
Returns ?object The default provider, or null.
GetProvider
MessagingEmailProviderConfig::GetProvider(string $providerId): ?object
The registered provider with the given id, or null when not found.
| Name | Type | Description |
|---|---|---|
$providerId | string | The provider id to look up. |
Returns ?object The provider, or null.
GetProviderIds
MessagingEmailProviderConfig::GetProviderIds(): array
The ids of all registered providers.
Returns array A list of provider ids.
GetProviders
MessagingEmailProviderConfig::GetProviders(): array
All registered provider objects.
Returns array A list of provider objects.
GetRandomProvider
MessagingEmailProviderConfig::GetRandomProvider(): ?object
A random registered provider. Throws when no providers are registered.
Returns ?object A randomly chosen provider.
MessagingEmailQueueDatabase
Locks and processes items on the email queue. Only unsent rows that are due are selected; on failure the item is retried with a backoff, or marked sent once the retry limit is reached so it leaves the queue.
Constants
| Constant | Value | Description |
|---|---|---|
MessagingEmailQueueDatabase::MAX_RESEND_COUNT | 5 | The maximum number of resend attempts before the item is marked sent to leave the queue. |
MessagingEmailQueueDatabase::RETRY_BASE_SECONDS | 60 | The base backoff, in seconds, multiplied per attempt. |
LockNext
MessagingEmailQueueDatabase::LockNext(int $limit): array
Lock and return the ids of due, unsent email queue rows, up to the limit.
| Name | Type | Description |
|---|---|---|
$limit | int | The maximum number of rows to lock and return. |
Returns array A list of integer ids, empty when none are available.
Process
MessagingEmailQueueDatabase::Process(int $emailId): void
Process an email queue item; on success marks it sent, on failure increments the resend counter and schedules the next retry, or marks it sent after the maximum retries.
| Name | Type | Description |
|---|---|---|
$emailId | int | The email id to process. |
Returns void
MessagingErrorSendFailed
Raised when a message fails to send. Extends Exception. It adds no members
of its own.
MessagingNotification
Entry point for sending push notifications. Records a notification and leaves it in the notification queue for a worker to deliver through a registered provider.
Send
MessagingNotification::Send(string $deviceToken, string $title, string $body, array|null $optionalData = null): int
Queue a push notification for sending. The notification is stored for a queue worker to deliver later; the new row id is returned.
| Name | Type | Description |
|---|---|---|
$deviceToken | string | The device token to notify. |
$title | string | The notification title. |
$body | string | The notification body. |
$optionalData | array|null | Extra data to attach, or null. |
Returns int The id of the queued notification.
MessagingNotificationData
Immutable data for a queued notification. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$notification->id | int | The notification row id (readonly). |
$notification->deviceToken | string | The device token (readonly). |
$notification->title | string | The notification title (readonly). |
$notification->body | string | The notification body (readonly). |
$notification->optionalData | string|null | Extra data, or null (readonly). |
$notification->provider | string|null | The provider that handled it, or null (readonly). |
$notification->sent | int | The sent flag (readonly). |
$notification->sentTimestamp | CalendarDateTimeData|null | When it was sent, or null (readonly). |
__construct
new MessagingNotificationData(int $id = 0, string $deviceToken = '', string $title = '', string $body = '', string|null $optionalData = null, string|null $provider = null, int $sent = 0, CalendarDateTimeData|null $sentTimestamp = null)
Create a notification data object from its fields.
| Name | Type | Description |
|---|---|---|
$id | int | The notification row id. |
$deviceToken | string | The device token. |
$title | string | The notification title. |
$body | string | The notification body. |
$optionalData | string|null | Extra data, or null. |
$provider | string|null | The provider that handled it, or null. |
$sent | int | The sent flag. |
$sentTimestamp | CalendarDateTimeData|null | When it was sent, or null. |
Returns MessagingNotificationData
MessagingNotificationDatabase
Stores notification queue rows and reads them back as data objects. Also processes a queued notification by handing it to a registered provider and marking it sent.
Add
MessagingNotificationDatabase::Add(string $deviceToken, string $title, string $body, array|null $optionalData = null): int
Insert a notification row and return its id. Any optional data is stored as JSON.
| Name | Type | Description |
|---|---|---|
$deviceToken | string | The device token to notify. |
$title | string | The notification title. |
$body | string | The notification body. |
$optionalData | array|null | Extra data to attach, or null. |
Returns int The id of the inserted row.
fromRow
MessagingNotificationDatabase::fromRow(stdClass $row): MessagingNotificationData
Build a notification data object from a database row.
| Name | Type | Description |
|---|---|---|
$row | stdClass | The database row to convert. |
Returns MessagingNotificationData The notification data.
GetById
MessagingNotificationDatabase::GetById(int $notificationId): MessagingNotificationData
Read a single notification row by id and return it as a data object.
| Name | Type | Description |
|---|---|---|
$notificationId | int | The notification row id. |
Returns MessagingNotificationData The notification data.
IncrementResendAndScheduleRetry
MessagingNotificationDatabase::IncrementResendAndScheduleRetry(int $notificationId, int $nextRetryAt): void
Increment the resend counter and set the timestamp for the next retry attempt.
| Name | Type | Description |
|---|---|---|
$notificationId | int | The notification row id. |
$nextRetryAt | int | Unix timestamp when the next retry should be attempted. |
Returns void
MarkSent
MessagingNotificationDatabase::MarkSent(int $notificationId): void
Mark a notification as sent, recording the sent timestamp and date.
| Name | Type | Description |
|---|---|---|
$notificationId | int | The notification row id. |
Returns void
ProcessQueue
MessagingNotificationDatabase::ProcessQueue(int $notificationId): void
Send a queued notification through a randomly chosen registered provider, record the provider, and mark it sent.
| Name | Type | Description |
|---|---|---|
$notificationId | int | The notification id to process. |
Returns void
MessagingNotificationProviderConfig
Lets notification provider modules register themselves, and reads the registered providers back. Providers are held as objects with providerId, providerName and sendCallback.
Properties
| Property | Type | Description |
|---|---|---|
MessagingNotificationProviderConfig::$providers | array | The registered notification provider objects. |
AddProvider
MessagingNotificationProviderConfig::AddProvider(string $providerId, string $providerName, callable $sendCallback): void
Register a notification provider. Throws when a provider with the same id is already registered.
| Name | Type | Description |
|---|---|---|
$providerId | string | The id of the provider (for example "firebase"). |
$providerName | string | The display name of the provider. |
$sendCallback | callable | Callback that sends the notification. |
Returns void
GetDefaultProvider
MessagingNotificationProviderConfig::GetDefaultProvider(): ?object
The first registered provider, or null when none are registered.
Returns ?object The default provider, or null.
GetProvider
MessagingNotificationProviderConfig::GetProvider(string $providerId): ?object
The registered provider with the given id, or null when not found.
| Name | Type | Description |
|---|---|---|
$providerId | string | The provider id to look up. |
Returns ?object The provider, or null.
GetProviderIds
MessagingNotificationProviderConfig::GetProviderIds(): array
The ids of all registered providers.
Returns array A list of provider ids.
GetProviders
MessagingNotificationProviderConfig::GetProviders(): array
All registered provider objects.
Returns array A list of provider objects.
GetRandomProvider
MessagingNotificationProviderConfig::GetRandomProvider(): ?object
A random registered provider. Throws when no providers are registered.
Returns ?object A randomly chosen provider.
MessagingNotificationQueueDatabase
Locks and processes items on the notification queue. Only unsent rows that are due are selected; on failure the item is retried with a backoff, or marked sent once the retry limit is reached so it leaves the queue.
Constants
| Constant | Value | Description |
|---|---|---|
MessagingNotificationQueueDatabase::MAX_RESEND_COUNT | 5 | The maximum number of resend attempts before the item is marked sent to leave the queue. |
MessagingNotificationQueueDatabase::RETRY_BASE_SECONDS | 60 | The base backoff, in seconds, multiplied per attempt. |
LockNext
MessagingNotificationQueueDatabase::LockNext(int $limit): array
Lock and return the ids of due, unsent notification queue rows, up to the limit.
| Name | Type | Description |
|---|---|---|
$limit | int | The maximum number of rows to lock and return. |
Returns array A list of integer ids, empty when none are available.
Process
MessagingNotificationQueueDatabase::Process(int $notificationId): void
Process a notification queue item; on success marks it sent, on failure increments the resend counter and schedules the next retry, or marks it sent after the maximum retries.
| Name | Type | Description |
|---|---|---|
$notificationId | int | The notification id to process. |
Returns void
MessagingSms
Entry point for sending SMS. Records a message and leaves it in the SMS queue for a worker to deliver through the configured vendor.
Send
MessagingSms::Send(string $from, string $to, string $text): int
Queue an SMS for sending. The message is stored for a queue worker to deliver later; the new row id is returned.
| Name | Type | Description |
|---|---|---|
$from | string | The sender number or id. |
$to | string | The recipient number. |
$text | string | The message text. |
Returns int The id of the queued SMS.
MessagingSmsDatabase
Stores SMS queue rows and reads them back. Also processes a queued SMS by handing it to the configured vendor and marking it sent.
Add
MessagingSmsDatabase::Add(string $from, string $to, string $text): int
Insert an SMS row and return its id.
| Name | Type | Description |
|---|---|---|
$from | string | The sender number or id. |
$to | string | The recipient number. |
$text | string | The message text. |
Returns int The id of the inserted row.
GetById
MessagingSmsDatabase::GetById(int $smsId): object
Read a single SMS row by id.
| Name | Type | Description |
|---|---|---|
$smsId | int | The SMS row id. |
Returns object The SMS row.
IncrementResendAndScheduleRetry
MessagingSmsDatabase::IncrementResendAndScheduleRetry(int $smsId, int $nextRetryAt): void
Increment the resend counter and set the timestamp for the next retry attempt. Call when a send fails so the item is retried after the next retry time.
| Name | Type | Description |
|---|---|---|
$smsId | int | The SMS row id. |
$nextRetryAt | int | Unix timestamp when the next retry should be attempted. |
Returns void
MarkSent
MessagingSmsDatabase::MarkSent(int $smsId): void
Mark an SMS as sent, recording the sent timestamp and date.
| Name | Type | Description |
|---|---|---|
$smsId | int | The SMS row id. |
Returns void
ProcessQueue
MessagingSmsDatabase::ProcessQueue(int $smsId): void
Send a queued SMS through the configured vendor, record the vendor, and mark it sent.
| Name | Type | Description |
|---|---|---|
$smsId | int | The SMS id to process. |
Returns void
MessagingSmsProvider
Resolves the configured SMS vendor and its send function, and can send an SMS immediately without the queue. The vendor is chosen by the site through the Messaging / SMS_VENDOR config value, never at random.
Constants
| Constant | Value | Description |
|---|---|---|
MessagingSmsProvider::VENDOR_TYPE | 'MessagingSms' | The vendor type SMS providers register against. |
Send
MessagingSmsProvider::Send(string $from, string $to, string $text): void
Send an SMS immediately, not queued, through the configured vendor. Useful for error messages when the database is down.
| Name | Type | Description |
|---|---|---|
$from | string | The sender number or id. |
$to | string | The recipient number. |
$text | string | The message text. |
Returns void
VendorName
MessagingSmsProvider::VendorName(): string
The configured SMS vendor name, from the Messaging / SMS_VENDOR config value. Throws when no SMS vendor is configured.
Returns string The vendor name.
VendorSend
MessagingSmsProvider::VendorSend(string $vendorName): callable
The send function of a named SMS vendor, taking from, to and text. Throws when the vendor is not registered.
| Name | Type | Description |
|---|---|---|
$vendorName | string | The registered vendor name. |
Returns callable The vendor send function.
MessagingSmsProviderConfig
Lets SMS provider modules register themselves, and reads the registered providers back. Providers are held as objects with providerId, providerName and sendCallback.
Properties
| Property | Type | Description |
|---|---|---|
MessagingSmsProviderConfig::$providers | array | The registered SMS provider objects. |
AddProvider
MessagingSmsProviderConfig::AddProvider(string $providerId, string $providerName, callable $sendCallback): void
Register an SMS provider. Throws when a provider with the same id is already registered.
| Name | Type | Description |
|---|---|---|
$providerId | string | The id of the provider (for example "twilio"). |
$providerName | string | The display name of the provider. |
$sendCallback | callable | Callback that sends the SMS. |
Returns void
GetDefaultProvider
MessagingSmsProviderConfig::GetDefaultProvider(): ?object
The first registered provider, or null when none are registered.
Returns ?object The default provider, or null.
GetProvider
MessagingSmsProviderConfig::GetProvider(string $providerId): ?object
The registered provider with the given id, or null when not found.
| Name | Type | Description |
|---|---|---|
$providerId | string | The provider id to look up. |
Returns ?object The provider, or null.
GetProviderIds
MessagingSmsProviderConfig::GetProviderIds(): array
The ids of all registered providers.
Returns array A list of provider ids.
GetProviders
MessagingSmsProviderConfig::GetProviders(): array
All registered provider objects.
Returns array A list of provider objects.
GetRandomProvider
MessagingSmsProviderConfig::GetRandomProvider(): ?object
A random registered provider. Throws when no providers are registered.
Returns ?object A randomly chosen provider.
MessagingSmsQueueDatabase
Locks and processes items on the SMS queue. Only unsent rows that are due are selected; on failure the item is retried with a backoff, or marked sent once the retry limit is reached so it leaves the queue.
Constants
| Constant | Value | Description |
|---|---|---|
MessagingSmsQueueDatabase::MAX_RESEND_COUNT | 5 | The maximum number of resend attempts before the item is marked sent to leave the queue. |
MessagingSmsQueueDatabase::RETRY_BASE_SECONDS | 60 | The base backoff, in seconds, multiplied per attempt. |
LockNext
MessagingSmsQueueDatabase::LockNext(int $limit): array
Lock and return the ids of due, unsent SMS queue rows, up to the limit. Used both for counting and for processing.
| Name | Type | Description |
|---|---|---|
$limit | int | The maximum number of rows to lock and return. |
Returns array A list of integer ids, empty when none are available.
Process
MessagingSmsQueueDatabase::Process(int $smsId): void
Process an SMS queue item; on success marks it sent, on failure increments the resend counter and schedules the next retry, or marks it sent after the maximum retries.
| Name | Type | Description |
|---|---|---|
$smsId | int | The SMS id to process. |
Returns void