arraypress / wp-register-emails
Merge tags, HTML email components and named transactional emails for WordPress plugins.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
- arraypress/wp-field-kit: Its email_editor field draws the merge-tag chooser; email_tags_for_editor() feeds it.
- arraypress/wp-money: Formats an amount in the currency an order was placed in.
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/emails(namespaceSugarCommerce\Emails, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
Register Emails
Named transactional emails with merge tags, and HTML that survives Outlook.
What it does
A plugin that sends a receipt needs three things nobody enjoys writing: merge tags a shop owner can put in the subject line, HTML that renders the same in Gmail and Outlook, and a way to preview the result without placing a test order.
This registers tags and emails by name, resolves the tags against whatever object the email is about, and builds the markup from components rather than from a table layout you maintain by hand.
Features
- Register a merge tag with a preview value, so the tester shows something real
- Register an email by name, with its subject and body
- Send one by name, overriding the recipient or subject at the call site
- Preview an email without sending, or triggering whatever produces it
- Build the body from components — buttons, tables, panels — not raw HTML
- Offer the available tags to an editor, so an owner can insert them
- Let the site owner reword, switch off and redirect each email from a settings panel
- Give every email one look — design, brand colour, logo, footer — chosen with a live preview
- Preview and send a test of what is on the screen, before anything is saved
Installation
composer require arraypress/wp-register-emails
Quick start
Register what the tags mean:
register_email_tag( 'shop', 'customer_name', [ 'label' => __( 'Customer name', 'my-plugin' ), 'callback' => fn( $order ) => $order->billing_name, 'preview' => 'Jane Doe', ] );
Then the email that uses them:
register_email( 'shop', 'receipt', [ 'subject' => __( 'Your order from {site_name}', 'my-plugin' ), 'content' => __( 'Thanks, {customer_name}.', 'my-plugin' ), ] );
And sending it:
send_registered_email( 'shop', 'receipt', [ 'to' => $order->email ] );
The preview value is what makes the tester useful — without it, previewing
an email means having an order to preview it against.
Tag types
A tag's type says how what its callback returns goes in. text, the
default, goes in as text — a billing name with markup in it reads as the name.
html goes in as it is, for a callback that builds its own markup. Any
component name — button, order_items, alert — draws that component from
what the callback returns. Tags work in the subject line as well as the body.
Theme overrides
An email's shell is an .html file in the library's templates/ folder. A
theme overrides one by putting a file of the same name in its own folder —
register-emails/ unless the plugin names another, so a shop can keep its
email copies with the rest of its theme templates:
\ArrayPress\RegisterEmails\Templates::set_theme_dir( 'my-shop/emails' );
The child theme is looked in first, then its parent.
Editable emails
register_email() gives an email a default wording. A Mailer is what a
plugin puts round its emails so the site owner can change them: the wording
each is sent with, a switch to turn one off, where a note to the site goes,
one look for all of them, and a settings panel per email with Preview and Send
a test.
use ArrayPress\RegisterEmails\Mailer; $mailer = Mailer::register( 'myshop', [ 'option_name' => 'myshop_settings', 'contexts' => [ 'order' => [ 'load' => 'myshop_get_order', // an id in, the order out 'latest' => 'myshop_latest_order_id', // for Send a test ], ], 'tags' => function ( Mailer $mailer ) { $mailer->register_tag( 'customer_name', [ 'label' => __( 'Customer name', 'myshop' ), 'description' => __( 'The name they gave at checkout.', 'myshop' ), 'callback' => fn( $order ) => $order->name, 'sample' => 'Jane Doe', ] ); }, 'emails' => function ( Mailer $mailer ) { $mailer->register_email( 'receipt', [ 'label' => __( 'Receipt', 'myshop' ), 'subject' => __( 'Your order {order_number}', 'myshop' ), 'body' => __( "Hello {customer_name},\n\nThanks for your order.", 'myshop' ), ] ); }, ] ); $mailer->send( 'receipt', $order_id );
The built-in tags and emails are registered on init (or by whoever asks
first). Another plugin adds its own on myshop_register_email_tags and
myshop_register_emails, or at any time before: an early registration waits
and goes in after the plugin's own, so a tag with a built-in's name replaces
it. Every hook is named from the mailer's prefix (its id by default), so two
plugins bundling the library never answer each other's.
Saved wording and the switch
Each email's panel saves enabled, subject, heading, body, template
and, for an email to the site, recipient under one key —
{key_prefix}{email}, so email_receipt. A blank part is sent as the
registered default, and send() returns true without sending for an email
the owner switched off: a preference is not a failure.
Change a built-in email's wording later and register the old body under
earlier: a saved body that is still word-for-word the old one was never the
owner's, and the new wording is sent instead.
Who it goes to, and who it is from
recipient is customer (the record's email, then the customer_email
callable), admin (what was typed on the panel, then the admin_email key,
then the site's admin address), or a callable given the record. Every email
and every test comes from the from_name and from_address keys, with a
Reply-To from the reply_to key when it is somewhere else; an empty sender is
the site's name at wordpress@ its domain.
Contexts: what an email is about
An email names a context, and that decides both the tags its editor offers
and the record they are handed. Each tag is given the loaded record, never
the id, so a tag is one line. Add one with the {prefix}_email_contexts
filter:
add_filter( 'myshop_email_contexts', function ( $contexts ) { $contexts['booking'] = [ 'group' => 'myshop_booking', 'load' => 'myaddon_get_booking' ]; return $contexts; } );
The look
The design, brand colour, logo and size, heading alignment and footer are saved once and drawn into every email — a send, a preview and a test alike. The words on the colour and the links beside it are worked out from it, so a pale colour still reads. An email built by hand gets the same look:
$look = $mailer->look()->settings(); compose_email()->template( $look['template'] )->context( $look['context'] );
Another plugin adds a design with an .html file through
{prefix}_email_templates, and changes the look of one email through
{prefix}_email_brand.
The settings screen
$mailer->fields() returns one email_editor field per email, for
wp-register-setting-fields
and wp-field-kit: the switch, a
Send to box for a note to the site, subject, heading, a body with Add Tag, and
a design of its own. $mailer->look_card()->sections() and ->fields() are
the Look card, whose preview redraws as the controls change, without a save:
'look_card' => [ 'screen' => 'myshop-settings', 'endpoint' => fn() => rest_url( 'myshop-field-kit/v1/action' ), 'preview_email' => 'receipt', ],
Call $mailer->panels()->fill_blanks() before the screen draws, so an editor
always shows what would be sent. Every word on the screen can be replaced
through labels. A plugin that registers its mailer before init can pass
labels, templates and last_tag_group as closures returning them: each is
called the first time it is read, when its words can be translated.
Preview and Send a test
Both buttons work from what is in the editor and on the Look card now, saved or not, and both work on an email that is switched off. A test goes to the person who pressed it, about the newest record when there is one, and is the sample preview when there is not.
Keeping a plugin's stored keys
A plugin that kept these settings itself before keeps every key: name its
option (or hand over settings, option and update callables), its
key_prefix, and any key that does not follow it through keys —
reply_to, admin_email and business_name have none until given one.
$mailer->store()->keys() lists every key the mailer reads or writes.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later