PHP API

Last updated Oct 3, 20264 min read

`wpmcf_resolve_variables()`

php

wpmcf_resolve_variables( string $template, ?EvaluationContext $context = null ): string

Replaces every {{ }} block in $template and returns the text. Everything outside the blocks is kept.

php

echo esc_html( wpmcf_resolve_variables( 'Hello {{ glb.company }}, it is {{ sys.year }}.' ) );
// Hello Acme, it is 2026.

Situation	Result
The plugin has not booted yet (before `plugins_loaded`)	The template, unchanged
An unexpected error inside the engine	The template, unchanged; the error is logged under module `variables` (Settings › Health)
A block that cannot be evaluated	That block is empty; the rest is resolved
No context, inside the loop	The loop post (`get_the_ID()`) becomes the context object
No context, outside any post	No object: `fg` and `wp.post_*` are empty, `glb` and `sys` still work
A context of type `term`, `user` or `comment`	`wp.post_` is empty; `wp.term_` reads the object when the type is `term`

The return value is not escaped. Escape it for where it goes (esc_html(), esc_attr(), wp_kses_post()). It is also not subject to the "who may run expressions" check of stored field values, because it is trusted code: do not pass visitor input to it. See Security.

`wpmcf_make_context()`

php

wpmcf_make_context( ?int $object_id = null, string $context_type = 'post', array $source_values = [] ): EvaluationContext

Builds the context that tells the engine which object fg and wp.post_* refer to, and what src contains.

Argument	Meaning
`$object_id`	The object ID. Omitted or `null`: the loop post (`get_the_ID()`); no object when there is none.
`$context_type`	`post` (default), `term`, `user` or `comment`. Decides which object type `fg` reads.
`$source_values`	An array readable as `{{ src.key }}`

php

// A field of a specific post
$ctx = wpmcf_make_context( 42 );
echo esc_html( wpmcf_resolve_variables( '{{ fg.product.price | number(2) }}', $ctx ) );

// A field of a term
$ctx = wpmcf_make_context( $term->term_id, 'term' );
echo esc_html( wpmcf_resolve_variables( '{{ fg.category_extra.headline }}', $ctx ) );

// Values of your own
$ctx = wpmcf_make_context( null, 'post', [ 'city' => 'London', 'n' => 10 ] );
echo esc_html( wpmcf_resolve_variables( "{{ src.city == 'London' ? 'Capital' : 'City' }}", $ctx ) );

The evaluation context

WPMass\CustomFields\Variables\Context\EvaluationContext is immutable: each with* method returns a modified copy.

Method	Purpose
`EvaluationContext::make()`	An empty context (object none, type `post`)
`withObjectId( ?int $id )`	Set the object
`withContextType( string $type )`	`post`, `term`, `user`, `comment`
`withSourceValues( array $values )`	Values for `src.*`
`withMeta( string $key, mixed $value )`	Free-form data for namespace resolvers (for example `term_id`, which `wp.term_*` prefers over the context object)
`getObjectId()`, `getContextType()`, `getSourceValue( $key )`, `getAllSourceValues()`, `getMeta( $key )`	Read it back

php

$ctx = wpmcf_make_context( $term->term_id, 'term' )->withMeta( 'term_id', $term->term_id );
echo esc_html( wpmcf_resolve_variables( '{{ wp.term_name }} ({{ wp.term_slug }})', $ctx ) );

The engine

php

$engine = wpmcf_variable_engine();   // ?VariableEngine, null until the plugin has booted

Method	Returns
`resolve( string $template, EvaluationContext $context ): string`	The resolved text
`resolveEscaped( string $template, EvaluationContext $context, callable $escape ): string`	Like `resolve()`, but every top-level block result goes through `$escape( string ): string` while the text around the blocks is left as written. Use it to put values into HTML an editor wrote.
`hasVariables( string $text ): bool`	Whether the text contains `{{` (a quick check before doing work)
`getRegistry(): VariableRegistry`	The registry

php

$engine = wpmcf_variable_engine();
if ( $engine ) {
    $html = $engine->resolveEscaped(
        '<p class="price">{{ fg.product.price | number(2) }}</p>',
        wpmcf_make_context( get_the_ID() ),
        'esc_html'
    );
}

resolve() itself is not guarded against exceptions the way wpmcf_resolve_variables() is. Prefer the function unless you need resolveEscaped().

The registry

php

$registry = wpmcf_variable_registry();   // ?VariableRegistry

Method	Purpose
`registerNamespace( string $name, NamespaceResolverInterface\|Closure $resolver )`	Add a namespace (a closure builds the resolver on first use)
`registerFilter( string $name, callable $fn )`	Add a filter. `$fn( $value, ...$arguments )`
`registerFunction( string $name, callable $fn )`	Add a function for `fn.name()`. `$fn( ...$arguments )`
`hasNamespace()`, `hasFilter()`, `hasFunction()`	Existence checks (names are lowercased)
`getRegisteredNamespaces()`, `getRegisteredFilters()`, `getRegisteredFunctions()`	Lists of lowercase names

Registering a name again replaces the earlier entry.

Extend the engine

Add namespaces, filters and functions from the wpmcf/variables/register action. It receives the registry and fires once, when the registry is built after the plugin has booted.

php

use WPMass\CustomFields\Variables\Context\EvaluationContext;
use WPMass\CustomFields\Variables\Namespace\NamespaceResolverInterface;
use WPMass\CustomFields\Variables\Registry\VariableRegistry;

final class My_Resolver implements NamespaceResolverInterface {
    public function resolve( array $path, EvaluationContext $ctx ): mixed {
        // {{ my.rating }} → $path = [ 'rating' ]
        return match ( $path[0] ?? '' ) {
            'rating' => (string) get_post_meta( (int) $ctx->getObjectId(), 'rating', true ),
            default  => null,        // null renders nothing
        };
    }

    public function getNamespace(): string {
        return 'my';
    }
}

add_action( 'wpmcf/variables/register', function ( VariableRegistry $registry ): void {
    $registry->registerNamespace( 'my', new My_Resolver() );
    $registry->registerFilter( 'shout', fn ( $value, $suffix = '!' ) => strtoupper( (string) $value ) . $suffix );
    $registry->registerFunction( 'sum_all', fn ( ...$numbers ) => array_sum( $numbers ) );
} );

Now {{ my.rating }}, {{ glb.name | shout('?') }} and {{ fn.sum_all(1, 2, 3) }} work.

Rules for extensions:

Return plain values. Strings, numbers, booleans, null or lists. Lists print joined by , ; null and false print nothing; true prints 1.
Never trust the path. $path comes from editors. Whitelist the names you handle (match above) and read only data that is safe to print publicly.
Do not print secrets. Passwords and keys must not be reachable. The built-in fg and glb resolvers exclude password values; follow that rule.
Names are made of letters, digits and underscores and are matched case-insensitively. fn, func, fonk and function are reserved for function calls.
Throwing is safe (the block renders empty), but returning null is cleaner.

Timing

The listener must be attached before the registry is built after boot. Attach it when your plugin file loads, or on plugins_loaded. If you may run later than that, skip the action and register directly on the registry:

php

$registry = wpmcf_variable_registry();
if ( $registry ) {
    $registry->registerFilter( 'shout', fn ( $value ) => strtoupper( (string) $value ) );
}

Adding request data to the context

The wpmcf/variables/context filter lets a module add data to the context at the start of every top-level evaluation. Programmatic SEO uses it to give field values on a generated page access to the page's data row.

php

add_filter( 'wpmcf/variables/context', function ( EvaluationContext $ctx ): EvaluationContext {
    return $ctx->withMeta( 'campaign', 'spring-sale' );
} );

Reading values without expressions

When you only need a value and not a template, use wpmcf_get_field() and wpmcf_get_global(). They evaluate {{ }} inside the stored value, once, under the rules in Where variables work.

Was this page helpful?

Still stuck? Contact support