Transactional Email Builder

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Builds subject, plain text, and HTML email bodies from safe template variables.
 *
 * Primary use case: Contact forms, receipts, account notices.
 * Typical inputs: template key, variables, policy.
 * Typical output: email payload.
 *
 * Implementation note: Escape values per text/html context.
 *
 * @param array $input Structured input values for this helper contract.
 * @param array $options Optional policy and formatting controls.
 * @return array Structured result data with success, message, and data keys.
 */
function ogBuildTransactionalEmail($input = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($input)) {
		$result['message'] = 'Input must be an array.';
		return $result;
	}

	if (!is_array($options)) {
		$options = array();
	}

	$template_key = '';
	if (!empty($input['template_key'])) {
		$template_key = trim((string)$input['template_key']);
	}
	$subject_template = '';
	if (!empty($input['subject'])) {
		$subject_template = (string)$input['subject'];
	}
	$text_template = '';
	if (!empty($input['text'])) {
		$text_template = (string)$input['text'];
	}
	$html_template = '';
	if (!empty($input['html'])) {
		$html_template = (string)$input['html'];
	}
	$variables = array();
	if (!empty($input['variables']) && is_array($input['variables'])) {
		$variables = $input['variables'];
	}

	if (empty($template_key) || empty($subject_template)) {
		$result['message'] = 'Template key and subject are required.';
		return $result;
	}

	$subject = $subject_template;
	$text = $text_template;
	$html = $html_template;

	foreach ($variables as $key => $value) {
		$key = preg_replace('/[^a-zA-Z0-9_]/', '', (string)$key);
		if (empty($key)) {
			continue;
		}
		$text_value = trim((string)$value);
		$html_value = htmlspecialchars($text_value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
		$subject = str_replace('{' . $key . '}', $text_value, $subject);
		$text = str_replace('{' . $key . '}', $text_value, $text);
		$html = str_replace('{' . $key . '}', $html_value, $html);
	}

	$subject = str_replace(array("\r", "\n"), ' ', $subject);
	$subject = trim($subject);

	$result['success'] = true;
	$result['message'] = 'Transactional email payload built.';
	$result['data'] = array(
		'template_key' => $template_key,
		'subject' => $subject,
		'text' => $text,
		'html' => $html
	);

	return $result;
}