Search by

arraypress / wp-register-emails

arraypress

This package is abandoned and no longer maintained. No replacement package was suggested.

Merge tags, HTML email components and named transactional emails for WordPress plugins.

Package info

github.com/arraypress/wp-register-emails

pkg:composer/arraypress/wp-register-emails

Statistics

Installs: 307

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v1.0.0 2026-08-25 18:02 UTC

This package is auto-updated.

Last update: 2026-11-18 10:53:51 UTC


README

This library has moved. It is now part of sugarcommerce/emails (namespace SugarCommerce\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