WooCommerce Code Reference

Personalizer
in package

Class for replacing personalization tags with their values in the email content.

Table of Contents

RENDERING_CONTEXT_HREF  = 'href'
Rendering context for link destinations. Tag callbacks must return a raw, unescaped URL (or URL component); URL escaping is applied when the attribute is written.
RENDERING_CONTEXT_HTML  = 'html'
Rendering context for HTML content. Tag values are rendered into HTML markup.
RENDERING_CONTEXT_KEY  = 'rendering_context'
Reserved key under which the current rendering context is exposed in the context array passed to tag callbacks. Any value set via set_context() under this key is overwritten.
RENDERING_CONTEXT_TEXT  = 'text'
Rendering context for plain-text content (e.g., email subject, preheader, plain-text body).
TAG_NAME_PATTERN  = '[a-zA-Z0-9\-\/]+'
Regex pattern for matching personalization tag names (e.g., "woocommerce/store-url", "user-firstname").
$context  : array<string|int, mixed>
Context for personalization tags.
$tags_registry  : Personalization_Tags_Registry
Personalization tags registry.
$value_interceptor  : callable|null
Optional callback intercepting each resolved personalization tag value before it is written into the content.
__construct()  : mixed
Class constructor with required dependencies.
get_context()  : array<string, mixed>
Get the current context.
personalize_content()  : string
Personalize the content by replacing the personalization tags with their values.
set_context()  : void
Set the context for personalization.
set_value_interceptor()  : callable|null
Set a callback intercepting each resolved personalization tag value before it is written.
get_callback_context()  : array<string, mixed>
Build the context array passed to a tag callback, exposing the rendering context of the current replacement site under the reserved key.
intercept_value()  : string
Run a resolved value through the registered interceptor, if any.
parse_token()  : array{token: string, arguments: array}
Parse a personalization tag to the token and attributes.
personalize_href_tokens()  : string|null
Replace personalization tag tokens embedded in a link URL.
replace_link_href()  : string
Replace the href attribute of the anchor tag with the personalized value.

Constants

RENDERING_CONTEXT_HREF

Rendering context for link destinations. Tag callbacks must return a raw, unescaped URL (or URL component); URL escaping is applied when the attribute is written.

public mixed RENDERING_CONTEXT_HREF = 'href'

RENDERING_CONTEXT_KEY

Reserved key under which the current rendering context is exposed in the context array passed to tag callbacks. Any value set via set_context() under this key is overwritten.

public mixed RENDERING_CONTEXT_KEY = 'rendering_context'

RENDERING_CONTEXT_TEXT

Rendering context for plain-text content (e.g., email subject, preheader, plain-text body).

public mixed RENDERING_CONTEXT_TEXT = 'text'

Tag values must be raw text without HTML entities or markup.

TAG_NAME_PATTERN

Regex pattern for matching personalization tag names (e.g., "woocommerce/store-url", "user-firstname").

private mixed TAG_NAME_PATTERN = '[a-zA-Z0-9\-\/]+'

Used in both tag detection and parsing.

Properties

$context

Context for personalization tags.

private array<string|int, mixed> $context

The context is an associative array containing recipient-specific or campaign-specific data. This data is used to resolve personalization tags and provide input for tag callbacks during email content processing.

Example context: array( 'recipient_email' => 'john@example.com', // Recipient's email 'custom_field' => 'Special Value', // Custom campaign-specific data )

Methods

get_context()

Get the current context.

public get_context() : array<string, mixed>

The context is an associative array containing recipient-specific or campaign-specific data. This data is used to resolve personalization tags and provide input for tag callbacks during email content processing.

Return values
array<string, mixed> — The current context.

personalize_content()

Personalize the content by replacing the personalization tags with their values.

public personalize_content(string $content[, string $rendering_context = self::RENDERING_CONTEXT_HTML ]) : string
Parameters
$content : string

The content to personalize.

$rendering_context : string = self::RENDERING_CONTEXT_HTML

The rendering context of the content — one of the RENDERING_CONTEXT_HTML or RENDERING_CONTEXT_TEXT constants. Unknown values fall back to RENDERING_CONTEXT_HTML.

Return values
string — The personalized content.

set_context()

Set the context for personalization.

public set_context(array<string, mixed> $context) : void

The context provides data required for resolving personalization tags during content processing. This method allows the context to be set or updated.

Example usage: $personalizer->set_context(array( 'recipient_email' => 'john@example.com', ));

Parameters
$context : array<string, mixed>

Associative array containing personalization data.

Return values
void —

set_value_interceptor()

Set a callback intercepting each resolved personalization tag value before it is written.

public set_value_interceptor(callable|null $interceptor) : callable|null

The interceptor receives the resolved value (after any context-driven escaping), the raw source text being replaced (the trimmed tag token including arguments, the raw data-link-href attribute value, or the tag token found inside a plain href), and the rendering context of the replacement site — one of the RENDERING_CONTEXT_HTML, RENDERING_CONTEXT_TEXT, or RENDERING_CONTEXT_HREF constants. Its return value is written instead of the resolved value — verbatim in the html and text rendering contexts. In the href rendering context the return value ends up in the href attribute, which WordPress escapes with esc_url(): characters not allowed in URLs (such as curly braces) are stripped and a missing scheme is prepended, so a "{{placeholder}}" return comes out as "http://placeholder". An empty return value in the href rendering context means no replacement — the link is left untouched, just like an empty resolved value. This allows consumers (e.g. bulk-sending integrations) to substitute placeholders for values while recording the values externally.

The interceptor persists until cleared by passing null, and the Personalizer instance may be shared with other consumers, so clear or restore the interceptor (e.g. in a finally block) as soon as the work it was registered for is done. The previously registered interceptor is returned to support restoring it.

Parameters
$interceptor : callable|null

The interceptor callback or null to clear. The callback receives the resolved value, the raw source token, and a RENDERING_CONTEXT_* constant.

Return values
callable|null — The previously registered interceptor, or null when none was set.

get_callback_context()

Build the context array passed to a tag callback, exposing the rendering context of the current replacement site under the reserved key.

private get_callback_context(string $rendering_context) : array<string, mixed>
Parameters
$rendering_context : string

One of the RENDERING_CONTEXT_* constants.

Return values
array<string, mixed> — The callback context.

intercept_value()

Run a resolved value through the registered interceptor, if any.

private intercept_value(string $value, string $source, string $rendering_context) : string
Parameters
$value : string

The resolved personalization tag value about to be written.

$source : string

The raw source text being replaced.

$rendering_context : string

One of the RENDERING_CONTEXT_* constants.

Return values
string — The value to write.

parse_token()

Parse a personalization tag to the token and attributes.

private parse_token(string $token) : array{token: string, arguments: array}
Parameters
$token : string

The token to parse.

Return values
array{token: string, arguments: array} — The parsed token.

personalize_href_tokens()

Replace personalization tag tokens embedded in a link URL.

private personalize_href_tokens(string $href) : string|null
Parameters
$href : string

The href attribute value.

Return values
string|null — The href with tokens replaced, or null when nothing was replaced.

replace_link_href()

Replace the href attribute of the anchor tag with the personalized value.

private replace_link_href(string $content, string $token, string $replacement) : string

The replacement uses regular expression to match the shortcode and its attributes.

Parameters
$content : string

The content to replace the link href.

$token : string

Personalization tag token.

$replacement : string

The callback output to replace the link href.

Return values
string —