Bind filters
Bind filters transform a value before it is written to the document. They are useful for presentation tasks such as formatting a number or adding a currency symbol, without adding a separate formatted getter to an entity.
Filter syntax
Add a pipe and a filter name after the bind key:
<span data-bind:text="amount|numericOutput">0.00</span>
Several filters can be chained together:
<span data-bind:text="amount|numericOutput|userCurrency">£0.00</span>
The value passes through each filter from left to right. Each filter receives the previous filter’s result. Other elements bound to amount still receive the original value unless they also specify filters.
Do not put spaces around the pipes. Filter names start with a letter and contain only letters, numbers or underscores. There is no syntax for calling arbitrary PHP functions or passing extra arguments from the HTML.
Define and register a filter class
Extend GT\DomTemplate\BindFilter. Each filter is a public instance method with the same name as the filter in the HTML. For example, numericOutput calls numericOutput().
use GT\DomTemplate\BindFilter;
class DisplayFilters extends BindFilter {
public function numericOutput(float $value):string {
return number_format($value, 2);
}
public function userCurrency(string $value):string {
$preference = $this->getDependency(CurrencyPreference::class);
return ($preference?->symbol ?? "£") . $value;
}
}
Once the binder’s dependencies have been set up as shown in Getting started, register the instance before binding any filtered values:
$filters = new DisplayFilters();
$binder->registerBindFilter($filters);
$binder->bindKeyValue("amount", 12345);
With the chained HTML above, the output text is £12,345.00. The filters shown here are application code, rather than built-in filters supplied by DomTemplate.
Registration is explicit. DomTemplate does not scan entity attributes, load a specially named application class or look up services. Protected, private and static methods are not exposed as filters, and the inherited setDependency(), getDependency() and getFilter() methods cannot be called from a binding expression.
Optional dependencies
Supply objects to the filter instance with setDependency(). Filter methods can then request them with getDependency().
For the currency example above, the application might define:
class CurrencyPreference {
public function __construct(public string $symbol) {}
}
$filters->setDependency(new CurrencyPreference("€"));
The next call to userCurrency() uses €. Without a supplied preference, it falls back to £.
getDependency(SomeClass::class) returns a matching supplied object, or null if none is available. Parent classes and interfaces can also be requested. If several supplied objects match, the most recently supplied one is returned. Supplying another object of the same concrete class replaces the earlier one.
There is no automatic service-container lookup or constructor injection. The filter decides what to do when an optional dependency is absent.
Share filters across pages, components and lists
Share the same provider instances across the page, its components and its lists. Binders wired to the same ElementBinder and HTMLAttributeBinder share the registrations automatically. Registering a provider on either the document or component binder makes it available to the other binders using those dependencies, including list and table rows.
If binders have separately constructed dependencies, register the same filter instance on each:
$pageBinder->registerBindFilter($filters);
$componentBinder->registerBindFilter($filters);
Register several provider classes
Several filter classes can be registered on the same binder:
$binder->registerBindFilter($defaultFilters);
$binder->registerBindFilter($applicationFilters);
Here both objects extend BindFilter. Each name is looked up in reverse registration order: the application provider can override a default filter, while default filters with other names remain available. A single chain can use methods from several providers. DomTemplate does not supply built-in filters; an application or integrating framework supplies these providers.
Each provider retains its own optional dependencies. Registering a new instance of the same concrete class replaces the earlier instance and gives it the latest registration priority. Registrations are not global: an independent binding setup does not inherit another document’s filter providers or dependencies.
Values and modifiers
Filters receive the original value before normal binding conversion, including values read from #[Bind] and #[BindGetter] objects. A filter can accept an object such as DateTimeInterface and return formatted text. Later filters must accept the type returned by the preceding filter.
A filter can also turn null into a fallback value. If the final result is null, the binding is skipped and its expression remains available, matching the normal null-value behaviour.
Filters work with bind modifiers. Put the chain after the key, before any equality condition or explicit class names:
<button data-bind:disabled="?status|lower=blocked" data-rebind>Save</button>
<div data-bind:class=":amount|positive highlighted"></div>
Here lower would return a lower-case string and positive would return a boolean. The modifier acts on that filtered result. data-rebind runs the chain again when the key is rebound. Semicolon-separated expressions keep their own filter chains.
Unnamed value bindings can also be filtered:
<span data-bind:text="|numericOutput"></span>
Use bindValue(12345) to bind that expression. Filters apply to data-bind:* expressions; {{placeholders}} keep their existing behaviour and do not support filter syntax.
Normal bind-property rules still apply. A text binding writes text, while an HTML binding inserts HTML and should only receive trusted content. See Bind properties and modifiers.
Filter errors
DomTemplate throws specific exceptions when a matching filtered expression cannot be bound:
BindFilterNotRegisteredExceptionmeans no provider has been registered.BindFilterNotFoundExceptionmeans none of the registered providers has a matching public instance method.InvalidBindFilterExpressionExceptionmeans a filter name is empty or invalid.
All three extend BindFilterException, which exposes filterName and expression for callers that want to add diagnostic context. An unmatched expression does not require a provider. Exceptions thrown inside a filter propagate unchanged.
Framework-specific configuration and friendly error-page integration are tracked separately in WebEngine #744.