Overview
Arlanix Notifications

For arlanix/notification 1.0.0

Arlanix Notifications documentation

For the developer who installs and looks after the modules, or publishes to them from their own code. Topics, subscriptions and rules themselves are made in the admin by the store; the manual is written for them.

Requirements

  • Magento Open Source or Adobe Commerce 2.4.7 or later.
  • PHP 8.1 to 8.5.
  • A working Magento cron, and the message queue consumers it starts (cron_consumers_runner), or the consumer run by supervisor. RabbitMQ is not needed: without it the MySQL queue is used.
  • For email, Magento's own mail that works, or an SMTP server the store can reach.
  • For Telegram, Slack and Discord, HTTPS out to api.telegram.org, hooks.slack.com and discord.com.

Packages

arlanix/notification is a metapackage. It installs every module in the following table at matching versions; one can be left out by requiring the others alone.

Package Module Purpose
arlanix/module-core Arlanix_Core Shared by every Arlanix module: logging, templates and the support bundle.
arlanix/module-notification Arlanix_Notification Topics, subscriptions, rules, the message log, publishing, and delivery through the message queue.
arlanix/module-notification-smtp Arlanix_NotificationSmtp Email, through Magento's mail or an SMTP server of its own.
arlanix/module-notification-telegram Arlanix_NotificationTelegram Telegram, through the store's bot or a subscription's own.
arlanix/module-notification-slack Arlanix_NotificationSlack Slack, through a channel's incoming webhook.
arlanix/module-notification-discord Arlanix_NotificationDiscord Discord, through a channel's webhook.
arlanix/module-notification-event Arlanix_NotificationEvent The store's events for rules: orders, invoices, refunds, shipments, customers, reviews, newsletter, contact form.
arlanix/module-notification-monitoring Arlanix_NotificationMonitoring The store's health for rules: admin sign-ins, cron, indexers, errors, orders that stop, imports and exports, and a health check URL.

How a message goes

  1. Emit or publish. A module emits one of its declared events through Arlanix\Notification\Api\EmitterInterface, or arlanix_notification_emit; each active rule of the event whose conditions are met publishes its message to its topic. A module may also publish itself, through PublisherInterface::publish() or arlanix_notification_publish. Either way the message is written to arlanix_notification_message, with a row in arlanix_notification_delivery for each subscription of the topic that is active and takes its severity, and each delivery's id is published to the queue topic arlanix.notification.deliver. Neither throws, and neither waits for a mail server or a chat, but for a message sent at once, past the queue, such as Cron stopped: see Publish from your module.
  2. Merge. The consumer arlanix_notification_deliver reads a batch of up to 100 queue messages and hands them to its handler together, which groups them by subscription, so one subscription's deliveries of a batch go as one digest, or as several of up to 25 entries each, a repeated message being one entry.
  3. Deliver. Each delivery is claimed first, so a queue message delivered twice is sent once. The subscription's protocol (email, Telegram, Slack, Discord) sends the digest; a failure is recorded with the time of its next attempt.
  4. Retry. The cron job arlanix_notification_requeue puts the deliveries whose retry is due back on the queue, takes back those a consumer died sending, and puts back those whose queue message was lost.

Queue, cron and command line has the details.

Pages

  • Install: Composer, the upgrade, the consumer, email, admin roles, and a test message to hand back to the store.
  • Email: Magento's mail or a server of its own, encryption, and checking it.
  • Telegram, Slack and Discord: the bot token, a Bot API server, what the store must reach, and where secrets are kept.
  • Monitoring: what is watched, the health check URL for an uptime monitor, and what is kept.
  • Upgrade and remove: moving to a new version, and taking the modules out.
  • Queue, cron and command line: the consumer, merging, running several, the cron jobs, the commands.
  • Configuration: every setting, its default, and setting one from the command line.
  • Troubleshooting: messages that wait, deliveries that fail, rules that do not send.
  • Publish from your module: the PHP API, the events, and a topic select in your settings.
  • Declare events: events of your module for the store's rules.
  • Customise messages: a field added to another module's event, a {message.*} variable, a modifier, a value shown another way.
  • Add a protocol: Microsoft Teams, SMS or your own way of delivery.