Search by

preflow / notify

smyr

Preflow notify — send email, SMS and other messages through pluggable transports

Package info

github.com/getpreflow/notify

pkg:composer/preflow/notify

Statistics

Installs: 906

Dependents: 4

Suggesters: 0

Stars: 0

Open Issues: 0

v0.81.1 2026-11-21 13:48 UTC

README

Send email, SMS and other messages through pluggable transports. Application code depends on one class, Notifier, and on small message value objects. Which provider delivers a channel is configuration.

use Preflow\Notify\Email;
use Preflow\Notify\Notifier;
use Preflow\Notify\Sms;

$notifier->send(new Email(to: 'me@example.com', subject: 'Hi', text: 'Hello there'));
$notifier->send(new Sms(to: '+41790000000', text: 'Your code: 4711'));

Notifier is injected by constructor like any other service. Sending is synchronous. This is not a message bus or queue (unlike Symfony Messenger): it only delivers outbound messages.

Configuration

Core boots the package when config/notify.php exists:

return [
    'transports' => [
        'smtp' => ['driver' => 'symfony-mailer', 'dsn' => getenv('MAILER_DSN') ?: ''],
        'log'  => ['driver' => 'log'],
        'mail' => ['driver' => 'failover', 'transports' => ['smtp', 'log']],
    ],
    'channels' => [
        'email' => ['transport' => 'mail', 'from' => getenv('MAIL_FROM') ?: null],
        'sms'   => ['transport' => 'log'],
    ],
];
  • Credentials belong in .env.
  • Transports are created on first send, so an empty or broken DSN never breaks boot. It fails, with a clear message, when something is sent.
  • A channel's from is used when a message doesn't set its own.
  • Any transport takes redirect_to (an address, a comma-separated string or a list): every email it sends then goes only there, for stage and test installations. Cc and Bcc are dropped; the subject starts with [→ original recipients] and the body with a line naming To, Cc and Bcc. SMS passes through unchanged. Example: 'redirect_to' => getenv('MAIL_REDIRECT_TO') ?: '' (empty means off).

Drivers

Driver Needs Purpose
log nothing Appends a summary and the body to storage/logs/messages.log (or path).
null nothing Drops messages.
memory nothing Keeps messages in memory (sent(), reset()) for tests.
failover nothing Tries transports in order. Skips any that can't send the message type.
symfony-mailer composer require symfony/mailer dsn: smtp://user:pass@host:587 or any Symfony mailer bridge DSN.
symfony-notifier-sms composer require symfony/notifier plus a bridge (e.g. symfony/twilio-notifier) dsn: e.g. twilio://SID:TOKEN@default?from=+41….

Messages

  • Email:
    • to, subject, text, plus optional html, from, replyTo, cc, bcc and attachments (Attachment::fromPath() / Attachment::fromContents()).
    • Addresses are strings: a@b.test or Name <a@b.test>.
    • Line breaks in the subject or addresses are rejected, which prevents header injection.
  • Sms: to in E.164 format (+41790000000), text, optional from.
  • Your own types: implement Preflow\Notify\Message with a channel key (chat, push, …) and configure a transport that supports it.

Composed mails

For mails with a plain text part and a matching HTML part, describe what the mail says and let Mailer build the Email:

use Preflow\Notify\Mail\MailAction;
use Preflow\Notify\Mail\MailContent;
use Preflow\Notify\Mail\Mailer;
use Preflow\Notify\Mail\MailText;

$link = MailText::absoluteUrl('/invite/abc', $appUrl);
$mailer->send(new MailContent(
    subject: 'Your invitation',
    text: "Hello Anna\n\nYou are invited. Open your invitation:\n" . $link,
    lang: 'en',
    action: new MailAction('Open invitation', $link),
), to: 'anna@example.com');
  • MailContent: subject, text (plain text, paragraphs separated by a blank line), lang (the HTML's lang, default en), an optional action (the primary link: label and URL) and vars (extra variables for a template of your own). links (optional, the last argument) names the URLs the HTML part may link; any other URL stays plain text, e.g. in a message someone else wrote. null (default) links every http(s) URL, [] none.
  • Mailer::compose() returns the Email; send() sends it at once (a TransportException propagates); sendLater() queues it (see below). Each takes optional from, template and accent for this mail (an accent that is not a hex colour falls back to mail.accent).
  • The text part is text as is. The subject is made one line (control characters become a space). The HTML part comes from the layout: the paragraphs escaped, http(s) URLs linked, single line breaks kept, and the action as a button (data-mail-action) with its URL in small text below (data-mail-action-url).
  • MailText has the helpers: oneLine(), paragraphs() and absoluteUrl($pathOrUrl, $appUrl), which makes a path absolute, keeps an absolute http(s) URL and rejects anything else (//host, other schemes, whitespace) with an InvalidArgumentException.

The layout

The default design is neutral: a white page 560px wide, dark text, a 3px bar in the accent colour, the paragraphs and the button. Core binds MailLayout on first use:

  • TemplateMailLayout when the bound template engine (preflow/view) can render it: a Twig engine, or any engine when layout names the site's own template (a Blade app's). It renders @notify/mail/layout.twig, or the configured template, with lang, subject, accent, paragraphs (safe HTML, print it with |raw), action ({label, url}, only when the mail has one) and the content's vars.
  • BasicMailLayout otherwise (no engine, or an engine other than Twig without layout): the same markup in plain PHP. It has no templates, so layout and template are ignored.

Settings in config/notify.php, all optional:

'mail' => [
    'accent' => '#336699',                  // hex colour of the bar, links and button; default #1a1a1a
    'layout' => 'templates/mail.twig',      // the site's layout template; default @notify/mail/layout.twig
    'from'   => 'Site <hello@example.com>', // default: the email channel's from
],

To give every mail your site's look, copy @notify/mail/layout.twig into your templates, change it and name it in layout. A single mail can use another template with $mailer->send($content, $to, template: '…'). To replace the layout altogether, bind your own Preflow\Notify\Mail\MailLayout in a service provider.

The Mailer calls the layout's html() inside its compose scope (below). With preflow/core that is a render of its own in the recipient's context, so a layout of your own, or your layout template, reads the reader's language from $content->lang (the template's lang) or from the current render (current_locale(), t()), and nobody is signed in there. It never reads the language from the request that sends the mail. CSS or scripts the template collects stay in the mail, and a cookie or mail it queues is dropped.

The Mailer takes the Notifier itself or a Closure that returns it. Core passes a Closure that reads the container at each send, so a Notifier a provider or a test binds later is the one that sends, and its flushDeferred() sends what sendLater() queued.

A provider with its own SDK

Implement Preflow\Notify\Transport and register it as a driver from a service provider:

final class AcmeSmsTransport implements Transport
{
    public function __construct(private AcmeClient $client, private string $name) {}

    public function supports(Message $message): bool { return $message instanceof Sms; }

    public function send(Message $message): SentMessage
    {
        try {
            $id = $this->client->sendText($message->to, $message->text);
        } catch (\Throwable $e) {
            throw TransportException::fromProvider($this->name, $e);
        }

        return new SentMessage($message, $this->name, $id);
    }
}

// in a ServiceProvider::boot()
$container->get(TransportFactory::class)->extend(
    'acme-sms',
    fn (array $config, string $name) => new AcmeSmsTransport(new AcmeClient($config['key']), $name),
);

Then set 'texts' => ['driver' => 'acme-sms', 'key' => getenv('ACME_KEY') ?: ''] in transports.

Sending after the response

Sending takes an SMTP round trip. On account flows (forgot password, registration, resend confirmation) that makes "an account exists" answer measurably slower than "no account", which leaks which addresses are registered. Queue those mails instead:

$notifier->sendLater(
    new Email(to: $user->email, subject: 'Reset your password', text: $text),
    onFailure: fn (\Throwable $e) => $this->audit->warn('reset mail failed'),
);

sendLater() only queues. Core sends the queue once the response has gone out: Application::run() emits the response, releases the client the way Symfony's Response::send() does (fastcgi_finish_request() on PHP-FPM, else litespeed_finish_request() on LiteSpeed LSAPI, else outside the CLI it flushes all output buffers), then calls flushDeferred(). The flush sits in a finally, so mail queued before an exception or an error page still goes out.

The "after the response" guarantee holds on PHP-FPM and LSAPI. Elsewhere (mod_php, plain CGI) it is best effort: the connection stays open until the script ends. Some timing differences remain regardless of the transport: building the message and any database writes happen before the response. Keep those equally cheap on both branches of an account flow. register_shutdown_function was not used: it runs outside the application's control and cannot be flushed deterministically in the CLI and in tests.

  • Order is FIFO; every message is isolated, one failure does not stop the others.
  • A deferred failure never throws into the request. It calls $onFailure(\Throwable) when given; otherwise it logs a generic line (no addresses) through a PSR LoggerInterface bound in the container, else error_log().
  • flushDeferred() returns the number sent.
  • CLI and tests: Application::handle() flushes the queue itself before returning (only run() postpones it until after emitting), so in-process requests and tests never lose mail. A CLI command that does not go through handle()/run() must call $notifier->flushDeferred() itself.
  • The cap applies per flushDeferred() call: it sends at most Notifier::FLUSH_LIMIT (100) messages and logs what is left, so an onFailure that keeps re-queuing cannot loop forever. If onFailure throws, a generic line is logged.
  • The logger is looked up in the container when a failure happens, so one bound by a provider is used. defer is read as a boolean ("false", 0 and off count as false).
  • Without config/notify.php there is no Notifier and nothing happens.
  • 'defer' => false in config/notify.php (default true) makes sendLater() send at once, a failure going to $onFailure/the log. Handy to debug; tests rarely need it.

Dropping queued mail: discardingQueued()

Notifier::discardingQueued(\Closure $work): mixed (since 0.74) runs $work and returns its result. While it runs, sendLater() drops its message: it is not queued, not sent even with 'defer' => false, and its onFailure is not called. Since 0.81 send() sends nothing inside it either.

  • Calls nest; the state is put back when $work throws.
  • What was queued before stays queued and is sent as usual: only the messages queued inside are dropped.

With preflow/core it is deprecated since 0.81 (removed in 0.83): render under a discarding render context instead (Application::render() or Contexts::run() with RenderContext::discarding()).

The queue and the compose scope (since 0.81)

notify depends on no other package. The Notifier keeps what sendLater() queues in a Preflow\Notify\Deferred\DeferredQueue (the fifth constructor argument, queue() returns it; notify's own InMemoryQueue when none is given), and the queue's policy() (deliver, discard or capture) also decides whether send() delivers. Each queued message reaches the queue as a Preflow\Notify\Deferred\Deferred value: the Message, its channel, the onFailure closure and a one-line summary. A queue sends it with Notifier::deliver($item), so a durable queue (a cron worker that sends later) can store the message itself. deliver() is for queues only: it sends whatever the current render's policy is, since the queue already decided the item may go. With a durable queue, flushDeferred() returns 0 (nothing was sent in this process); code that reads 0 as "not sent", such as rbac's staff:create message, has to be adapted when such a queue is added.

The Mailer renders a mail's HTML part inside a Preflow\Notify\Mail\ComposeScope (its fourth argument; DirectCompose renders where it is called) for the content's language. MailContent::$lang may be null: the scope then picks the language (DirectCompose: 'en', as before 0.81) and the layout gets the content with that language.

With preflow/core, core binds its own implementations of both:

  • What sendLater() queues joins the current render's outbox, on the outbox channel notify. A visitor's request sends it after the response (also when the request failed), a console command when it ends (also when it failed). A render that must send nothing (the SEO audit, GEO, page cache rebuilds, verify) drops it; a preview or a view as a role lists it in its result and sends nothing. send() follows the same rule: it records instead of sending and answers as if sent, so the code around it takes the path it takes on a real visit.
  • A composed mail renders in its recipient's context: the texts and the locale of MailContent::$lang, else of the current render's locale, an anonymous visitor, published content.
  • flushDeferred() in a command or a request sends that command's or request's mail now and returns how many went out.
  • A Notifier you bind yourself (in a provider) must use the app's queue, or its mail would also leave internal renders and previews: new Notifier($factory, $channels, $logger, $defer, $container->get(DeferredQueue::class)). Core checks it once the providers booted: it throws in debug mode and logs otherwise.
  • The outbox channel name notify belongs to notify: a channel of another package registered under that name is refused (LogicException).
  • Sending through a transport directly (TransportFactory::get(...)->send()) bypasses all of this.

Errors

Every failure is a Preflow\Notify\TransportException. Provider errors are wrapped, and their message is masked: URL user-info (smtp://***@host) and secret-looking query parameters (api_key=***, password=***, token=***). The original exception is chained unmasked as getPrevious(), so don't log the whole chain verbatim.

When a failover delivers through a fallback, SentMessage::$failures lists each transport it fell back from (name → masked reason). Log these. Otherwise a broken SMTP setup goes unnoticed while mail quietly lands in the log transport.

The caller decides what a failure means; for a contact form, store the submission first, then send.

CLI

php preflow notify:test --to=me@example.com
php preflow notify:test --channel=sms --to=+41790000000

This sends a fixed test message through the configured transport and prints the result or the error. It exits non-zero when a failover had to fall back, and prints why the preferred transport failed. Use it to check credentials on a live server.