Developer API

Vector Expressions exposes a set of WordPress filter hooks for extending both the PHP evaluation engine and the Gutenberg editor UI.

PHP Extension Hooks

Registering a Custom Context Root

Use vector_expressions/context/get to register custom top-level data namespaces. The filter receives the currently resolved value and the requested root name — return your data when the root matches.

/**
 * @param mixed  $value The resolved value (default null).
 * @param string $root  The root variable name requested.
 */
add_filter( 'vector_expressions/context/get', function( $value, $root ) {
    if ( 'myroot' === $root ) {
        return [
            'price'         => 100,
            'hero_subtitle' => 'My Hero Subtitle',
        ];
    }

    return $value;
}, 10, 2 );

After registering, your custom root is immediately available in expressions:

{{ myroot.price }}
{{ myroot.hero_subtitle | default "Default subtitle" }}

Registering a Custom Modifier

Use vector_expressions/library/apply to add new modifier functions to the engine. The filter receives the piped-in value, the modifier name, and an array of arguments. Return the transformed value when the name matches; otherwise pass $in through unchanged.

/**
 * @param mixed  $in   The piped-in input value.
 * @param string $fn   The modifier name.
 * @param array  $args Modifier arguments (positional or named).
 */
add_filter( 'vector_expressions/library/apply', function( $in, $fn, $args ) {
    if ( 'currency' === $fn ) {
        $symbol   = $args['symbol'] ?? $args[0] ?? '$';
        $decimals = (int)( $args['decimals'] ?? 2 );
        return $symbol . number_format( (float) $in, $decimals );
    }

    return $in;
}, 10, 3 );

Usage in expressions:

{{ post.meta.price | currency symbol="£" decimals=0 }}
→ "£1,200"

Modifying Allowed Object Properties

Use these filters to control which properties are accessible on built-in context objects. Each filter receives a map of expression_key => actual_property pairs.

// Control accessible WP_Post properties
add_filter( 'vector_expressions/context/post_allowed_properties', function( array $map ): array {
    $map['my_alias'] = 'post_my_alias';
    return $map;
} );

// Control accessible WP_User properties
add_filter( 'vector_expressions/context/user_allowed_properties', function( array $map ): array {
    // Remove an alias to restrict access
    unset( $map['email'] );
    return $map;
} );

Blocking HTML Attribute Injection

Use vector_expressions/sanitization/deny_list to prevent specific HTML attributes from being injected dynamically during block rendering.

add_filter( 'vector_expressions/sanitization/deny_list', function( array $attrs ): array {
    $attrs[] = 'onmouseover';
    $attrs[] = 'data-secret';
    return $attrs;
} );

Modifying the Site Context

Use vector_expressions/context/site to modify the global site context object before it is made available to expressions.

add_filter( 'vector_expressions/context/site', function( array $site ): array {
    $site['plan'] = get_option( 'my_plugin_plan', 'free' );
    return $site;
} );

Intercepting Token Evaluation

Use vector_expressions/parser/render_token to modify a resolved value immediately after evaluation and before it is written to the output.

/**
 * @param mixed  $value      The resolved value.
 * @param string $expression The raw expression string.
 * @param bool   $is_raw     Whether the token used triple-brace {{{ }}} syntax.
 */
add_filter( 'vector_expressions/parser/render_token', function( $value, $expression, $is_raw ) {
    // Example: redact values on non-production environments
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG && is_string( $value ) && strlen( $value ) > 200 ) {
        return '[truncated]';
    }
    return $value;
}, 10, 3 );

Modifying the Block Attribute Schema

Use vector_expressions/attributes/schema to modify the vectex_logic attribute schema registered for all blocks. The schema is a standard WordPress block attribute definition with a default key containing the logic fields.

add_filter( 'vector_expressions/attributes/schema', function( array $schema ): array {
    // Add a new field to the logic data defaults
    $schema['default']['my_custom_field'] = '';
    return $schema;
} );

Filtering the Editor Context

Use vector_expressions/editor/context to control the data that is localized into the window.vectexContext JavaScript global in the block editor.

add_filter( 'vector_expressions/editor/context', function( array $ctx ): array {
    $ctx['membership_tier'] = my_plugin_get_membership_tier( get_current_user_id() );
    return $ctx;
} );

JavaScript Extension Hooks

Registering Custom Completions

Use the vector_expressions.editor.completions WordPress JS filter to add custom items to the editor’s autocomplete dropdown and expression chips.

const { addFilter } = window.wp.hooks;

addFilter(
  "vector_expressions.editor.completions",
  "my-plugin/add-custom-completions",
  (completions) => {
    return [
      ...completions,
      {
        label: "Member: Loyalty Points",
        expr: "user.meta.loyalty_points",
        preview: "450", // Optional: static preview shown in the editor
        category: "User", // Tab grouping: User | Post | Site | Modifier | Pattern
        prefix: "user", // Drives contextual filtering (e.g., shown when user types "user.")
      },
    ];
  },
);

Completion object properties:

Accessing Editor Context

The window.vectexContext global is available in the block editor. It contains pre-calculated data about the current user, site, and active post, used to populate expression previews without API calls.

const userRole = window.vectexContext?.user?.roles?.[0] || "guest";
console.log("Editing as:", userRole);

Modify the contents of this object using the PHP vector_expressions/editor/context filter (see above).

Available Hooks Summary

PHP

JavaScript