SIGNALS Docs
Reader View

Merge Field Filter Registry

Contract for registering merge-field filter callbacks and applying them during communication-template rendering.

Overview

App\Services\Notifications\MergeFieldFilterRegistry is the filter catalogue behind the notification template renderer. It records named callbacks that transform merge-field values during MergeFieldRenderer substitution.

Core binds the registry as a singleton in AppServiceProvider, then CoreMergeFieldFilters::register() loads the shipped filters during boot. Plugins currently register additional filters through PluginRegistrar::registerFilter().

Public surface

Method Purpose
register() Save one callback under a filter name
has() Check whether a filter name exists
get() Return the callback for a filter name or null
all() Return the full name-to-callback map
apply() Invoke a filter with value, optional argument, and render context

Accepted callback contract

Every registered filter is a callable with this signature:

callable(mixed $value, ?string $arg, MergeFieldRenderContext $context): mixed

The callback receives:

  • the current field value after any prior filters in the chain
  • the optional filter argument parsed from filter:arg
  • the current MergeFieldRenderContext

MergeFieldRenderContext currently carries:

  • currencyCode for currency-sensitive formatting
  • unknownFieldBehaviour for blank-versus-placeholder rendering

Registry names are unrestricted string keys: register() performs no format validation, and direct get() or apply() calls can use any exact registered string. The template grammar is narrower. In a {{ ... }} expression, template-expression filter names must contain alphabetic characters only (A–Z or a–z). A registered name containing digits, punctuation, underscores, or hyphens remains directly callable but cannot be referenced by the current template-expression parser. Names are case-sensitive at both boundaries.

Current core filters

CoreMergeFieldFilters::register() currently ships these filter names:

  • date
  • time
  • currency
  • number
  • upper
  • lower
  • title
  • default
  • truncate
  • plural

These are the current built-ins, not an open-ended generated catalogue.

Built-in argument contracts

Filter Value and argument behavior
date Accepts a string or DateTimeInterface; the optional argument is a PHP date format, otherwise company.date_format_php or d/m/Y is used
time Accepts a string or DateTimeInterface; the optional argument is a PHP time format, otherwise company.time_format_php or H:i is used
currency Formats integer minor units: an integer, or a clean integer string in the integer range (an optional - and digits, such as 12500); the optional argument is a currency code, otherwise the render context's code is used. A PreformattedMoney value (billing money already formatted in its own currency, such as $12.50) and text with no digit (a note) pass through unchanged. A float and every other value with a digit are refused: decimals, separators (, ' no-break spaces), text with a currency (12.50 GBP), exponents, +5, --5, leading or trailing spaces and integers outside the integer range
number number accepts numeric input and treats its optional argument as an integer decimal count, defaulting to 2; non-numeric values pass through unchanged
upper Casts non-null input to string and uppercases it; the argument is ignored
lower Casts non-null input to string and lowercases it; the argument is ignored
title Casts non-null input to string, lowercases it, then title-cases words; the argument is ignored
default Replaces null or the empty string with its argument, or with an empty string when no argument is present
truncate truncate treats its optional argument as an integer length, defaulting to 50; longer strings return a prefix of max(0, length - 3) characters followed by ..., so requested lengths below 3 still return ... and exceed that requested length
plural plural requires a singular form in its argument to transform the value; `singular

Lookup, replacement, and invocation rules

Lookup

  • has($name) reports whether a filter is registered
  • get($name) returns the callable or null
  • all() returns the raw associative map exactly as the registry records it

Replacement behavior

Filter names are associative keys. Registering the same name twice replaces the prior callback. The registry does not reject collisions or accumulate multiple callbacks under one name.

Invocation

apply($name, $value, $arg, $context) looks up the callback and invokes it directly when found.

MergeFieldRenderer applies chained filters from left to right, so each callback receives the output of the preceding filter in the expression. Its special handling for an empty value occurs at the point where default is encountered in that sequence. It is not a global pre-dispatch short circuit: prior filters run first, and later filters receive the default literal as their input.

Missing-filter behavior

If apply() cannot find the named filter, it returns the original $value unchanged. Unknown filter names are therefore a no-op at the registry layer rather than an exception.

Rendering context and current behavior

The registry is consumed by MergeFieldRenderer, which parses expressions shaped like:

{{ contact.name | upper | truncate:12 }}

The renderer resolves the field value first, then calls apply() for each parsed filter. Current durable behavior includes:

  • currency expects integer minor units and uses MergeFieldRenderContext::$currencyCode when no explicit code argument is supplied; billing merge data sends minor units only for money in the company base currency at its ISO precision, and sends other money as PreformattedMoney
  • date and time use the timezone helper plus the configured company formats unless an explicit format argument is passed
  • default is registered like any other filter; when the renderer reaches that filter with null or an empty string, it inserts the argument directly and continues through the remaining left-to-right pipeline

That special handling is part of the renderer contract, not additional registry behavior.

Invariants and failure modes

Duplicate names

Later registrations replace prior callbacks for the same filter name.

Missing filters

Missing filters are non-fatal. apply() returns the input value unchanged.

Filter-specific failures

The registry does not catch exceptions thrown by a concrete filter. For example, the core currency filter rejects floats and decimal strings because it requires integer minor units.

Worked example

This is the current core registration and consumption shape exercised in renderer tests:

$registry = new MergeFieldFilterRegistry;

CoreMergeFieldFilters::register($registry);

$rendered = $registry->apply(
    'upper',
    'abc',
    null,
    MergeFieldRenderContext::defaults(),
);

The core registration records the upper callback, and apply() returns ABC. Re-registering upper later would replace that callback rather than appending another stage.