EmailTemplateRendererService
in package
Service for rendering email templates with variable substitution
HTML templates are stored as Markdown and converted to HTML during rendering
Table of Contents
Properties
- $parsedown : Parsedown
Methods
- __construct() : mixed
- Constructor
- assertValidForSend() : void
- Like validateForSend() but throws a RuntimeException when there are any errors.
- extractAllPlaceholders() : array<string|int, string>
- Extract all unique placeholder names from every content field of a template.
- extractVariables() : array<string|int, mixed>
- Get list of variables used in a template
- getMissingVariables() : array<string|int, mixed>
- Validate that all required variables are provided
- htmlToText() : string
- Convert HTML to plain text (simple conversion)
- preview() : array<string|int, mixed>
- Preview rendered template with sample data
- renderHtml() : string|null
- Render HTML template
- renderHtmlBody() : string|null
- Render HTML body only (without wrapper)
- renderSubject() : string
- Render subject template
- renderTemplate() : string
- Render a template by replacing variables with values
- renderText() : string|null
- Render text template
- textToHtml() : string
- Convert plain text to HTML (simple conversion)
- validateForSend() : array{errors: string[], warnings: string[]}
- Validate a template against provided send-time variables.
- validateSchemaConsistency() : array{errors: string[], warnings: string[]}
- Validate that a template's variables_schema is consistent with its placeholders.
- evaluateComparison() : bool
- Evaluate a single comparison or bare variable presence check.
- evaluateCondition() : bool
- Evaluate a conditional expression safely.
- extractRenderedPlaceholders() : array<string|int, string>
- Extract placeholders that render literal output tokens.
- formatDateTimeValue() : string
- Format a date/time value in the kingdom default timezone.
- formatDateValue() : string
- Format a date value in the kingdom default timezone.
- formatValue() : string
- Format a value for display in email
- hasUsefulValue() : bool
- Determine whether a value is useful enough to render a bare {{#if variable}} block.
- normalizeTemplateVars() : array<string|int, mixed>
- Normalize send-time variables using the template contract.
- processConditionals() : string
- Process conditional blocks in template before variable substitution.
- renderTemplateHtmlEscaped() : string
- Render a template for the HTML pipeline, escaping substituted values only.
- splitOutsideQuotes() : array<string|int, mixed>
- Split a condition string by a logical operator, but only when the operator appears outside of quoted strings.
- wrapInEmailHtml() : string
- Wrap HTML body content in email-friendly HTML structure
Properties
$parsedown
protected
Parsedown
$parsedown
Methods
__construct()
Constructor
public
__construct() : mixed
assertValidForSend()
Like validateForSend() but throws a RuntimeException when there are any errors.
public
assertValidForSend(EmailTemplate $template, array<string|int, mixed> $vars) : void
Parameters
- $template : EmailTemplate
- $vars : array<string|int, mixed>
-
Variable name => value pairs
Tags
extractAllPlaceholders()
Extract all unique placeholder names from every content field of a template.
public
extractAllPlaceholders(EmailTemplate $template) : array<string|int, string>
Combines subject_template, html_template, and text_template so callers get a unified view of what the template actually needs.
Parameters
- $template : EmailTemplate
Return values
array<string|int, string> —Unique placeholder names
extractVariables()
Get list of variables used in a template
public
extractVariables(string $template) : array<string|int, mixed>
Finds {{variable}}, ${variable}, and variable references in {{#if}} conditionals.
Parameters
- $template : string
Return values
array<string|int, mixed> —List of variable names
getMissingVariables()
Validate that all required variables are provided
public
getMissingVariables(string $template, array<string|int, mixed> $vars) : array<string|int, mixed>
Parameters
- $template : string
-
Template string
- $vars : array<string|int, mixed>
-
Variables provided
Return values
array<string|int, mixed> —Missing variable names
htmlToText()
Convert HTML to plain text (simple conversion)
public
htmlToText(string $html) : string
Parameters
- $html : string
-
HTML
Return values
string —Plain text
preview()
Preview rendered template with sample data
public
preview(EmailTemplate $emailTemplate[, array<string|int, mixed> $sampleVars = [] ]) : array<string|int, mixed>
Parameters
- $emailTemplate : EmailTemplate
- $sampleVars : array<string|int, mixed> = []
-
Sample variable values
Return values
array<string|int, mixed> —Preview of subject, html, and text
renderHtml()
Render HTML template
public
renderHtml(EmailTemplate $template[, array<string|int, mixed> $vars = [] ]) : string|null
The html_template field stores Markdown, which is converted to HTML during rendering. Variables are substituted BEFORE markdown conversion to allow variables in links, etc.
Parameters
- $template : EmailTemplate
- $vars : array<string|int, mixed> = []
Return values
string|nullrenderHtmlBody()
Render HTML body only (without wrapper)
public
renderHtmlBody(EmailTemplate $template[, array<string|int, mixed> $vars = [] ]) : string|null
Used when you need just the content without the HTML structure wrapper.
Parameters
- $template : EmailTemplate
- $vars : array<string|int, mixed> = []
Return values
string|nullrenderSubject()
Render subject template
public
renderSubject(EmailTemplate $emailTemplate, array<string|int, mixed> $vars) : string
Parameters
- $emailTemplate : EmailTemplate
- $vars : array<string|int, mixed>
Return values
stringrenderTemplate()
Render a template by replacing variables with values
public
renderTemplate(string $template, array<string|int, mixed> $vars) : string
Processes conditional blocks first, then substitutes variables.
Parameters
- $template : string
-
Template string with {{variable}} placeholders
- $vars : array<string|int, mixed>
-
Array of variable name => value pairs
Return values
string —Rendered template
renderText()
Render text template
public
renderText(EmailTemplate $emailTemplate, array<string|int, mixed> $vars) : string|null
Parameters
- $emailTemplate : EmailTemplate
- $vars : array<string|int, mixed>
Return values
string|nulltextToHtml()
Convert plain text to HTML (simple conversion)
public
textToHtml(string $text) : string
Parameters
- $text : string
-
Plain text
Return values
string —HTML
validateForSend()
Validate a template against provided send-time variables.
public
validateForSend(EmailTemplate $template, array<string|int, mixed> $vars) : array{errors: string[], warnings: string[]}
Performs a three-way comparison:
- Placeholders extracted from subject + html + text vs $vars provided → errors for any placeholder that has no value (it would render as a raw {{...}} token).
- variables_schema required entries vs $vars → errors for any required schema var absent.
- Placeholders used in template vs variables_schema declared names → warnings for any placeholder not declared in the schema (undocumented variable drift).
Returns ['errors' => string[], 'warnings' => string[]]. Errors are blocking (use assertValidForSend to throw); warnings are advisory.
Parameters
- $template : EmailTemplate
- $vars : array<string|int, mixed>
-
Variable name => value pairs to be used at send time
Return values
array{errors: string[], warnings: string[]}validateSchemaConsistency()
Validate that a template's variables_schema is consistent with its placeholders.
public
validateSchemaConsistency(EmailTemplate $template) : array{errors: string[], warnings: string[]}
A schema-consistency check for template authoring time (not send time). Returns ['errors' => [], 'warnings' => []] where:
- warnings include schema vars not referenced by any template placeholder.
Parameters
- $template : EmailTemplate
Return values
array{errors: string[], warnings: string[]}evaluateComparison()
Evaluate a single comparison or bare variable presence check.
protected
evaluateComparison(string $comparison, array<string|int, mixed> $vars) : bool
Supports both == (equality) and != (not-equal) operators. Variable names do not use a $ prefix in the {{#if}} syntax.
Parameters
- $comparison : string
-
Single comparison expression
- $vars : array<string|int, mixed>
-
Available variable values
Return values
boolevaluateCondition()
Evaluate a conditional expression safely.
protected
evaluateCondition(string $condition, array<string|int, mixed> $vars) : bool
Splits by || first (lower precedence), then && (higher precedence), then evaluates individual comparisons.
Parameters
- $condition : string
-
Expression like 'var == "value" || var == "other"'
- $vars : array<string|int, mixed>
-
Available variable values
Return values
boolextractRenderedPlaceholders()
Extract placeholders that render literal output tokens.
protected
extractRenderedPlaceholders(EmailTemplate $template) : array<string|int, string>
Unlike extractAllPlaceholders(), this excludes variables referenced only inside conditional expressions because missing condition vars safely evaluate false and do not render literal tokens.
Parameters
- $template : EmailTemplate
Return values
array<string|int, string>formatDateTimeValue()
Format a date/time value in the kingdom default timezone.
protected
formatDateTimeValue(mixed $value) : string
Parameters
- $value : mixed
-
Date/time value
Return values
stringformatDateValue()
Format a date value in the kingdom default timezone.
protected
formatDateValue(mixed $value) : string
Parameters
- $value : mixed
-
Date value
Return values
stringformatValue()
Format a value for display in email
protected
formatValue(mixed $value) : string
Parameters
- $value : mixed
Return values
stringhasUsefulValue()
Determine whether a value is useful enough to render a bare {{#if variable}} block.
protected
hasUsefulValue(mixed $value) : bool
Parameters
- $value : mixed
-
Value to test
Return values
boolnormalizeTemplateVars()
Normalize send-time variables using the template contract.
protected
normalizeTemplateVars(EmailTemplate $template, array<string|int, mixed> $vars) : array<string|int, mixed>
Parameters
- $template : EmailTemplate
- $vars : array<string|int, mixed>
-
Variable name => value pairs
Return values
array<string|int, mixed>processConditionals()
Process conditional blocks in template before variable substitution.
protected
processConditionals(string $template, array<string|int, mixed> $vars) : string
Parses {{#if condition}}...{{/if}} blocks as a safe DSL. Supports ==, !=, bare variable presence, || (OR), and && (AND) operators.
Example: {{#if awardReason}}...{{/if}} Example: {{#if status == "Approved" || status == "Revoked"}}...{{/if}}
Parameters
- $template : string
-
Template with conditional blocks
- $vars : array<string|int, mixed>
-
Variable values for condition evaluation
Return values
string —Template with conditionals resolved
renderTemplateHtmlEscaped()
Render a template for the HTML pipeline, escaping substituted values only.
protected
renderTemplateHtmlEscaped(string $template, array<string|int, mixed> $vars) : string
Parameters
- $template : string
-
Template string with variable placeholders
- $vars : array<string|int, mixed>
-
Variable values
Return values
string —Rendered template with HTML-escaped values
splitOutsideQuotes()
Split a condition string by a logical operator, but only when the operator appears outside of quoted strings.
protected
splitOutsideQuotes(string $condition, string $operator) : array<string|int, mixed>
Parameters
- $condition : string
-
The condition string to split
- $operator : string
-
The operator to split on ('||' or '&&')
Return values
array<string|int, mixed> —Parts of the condition (single-element array if operator not found outside quotes)
wrapInEmailHtml()
Wrap HTML body content in email-friendly HTML structure
protected
wrapInEmailHtml(string $htmlBody) : string
Parameters
- $htmlBody : string
-
HTML body content
Return values
string —Complete HTML email