Variables and developer hooks

Hooks reference: filters

Last updated Oct 3, 202612 min read

Filters let you change a value. Every filter must return a value of the type shown in Returns; the plugin ignores or replaces a wrong type for most of them, but returning something unexpected is a bug in your code. Actions are on Hooks reference: actions.

Plan: Free filters are in every build. Pro filters exist only where Pro code is present.
Declare the number of arguments you read: add_filter( 'wpmcf/...', $callback, 10, 3 ).
$objectId is the post, user, term or comment ID of the value being read; for options values it can be null or 0.

Reading and printing field values · Global Data output · Variables · Field groups, location rules and storage · Shortcodes, queries and options pages · Admin screens · Admin columns · Post types and taxonomies · Local JSON · Background jobs and database · Page cache · Page builders · Licensing (Pro) · AI (Pro) · Data tables (Pro) · Forms (Pro) · Programmatic SEO (Pro)

Reading and printing field values

The order for one field read is: stored value → wpmcf/field/value → {{ }} evaluation (if allowed) → escaping for the output format → wpmcf/field/the_escaped → markup → wpmcf/field/the_html.

`wpmcf/field/value`


Plan	Free
Arguments	`mixed $value`, `string $group_key`, `string $field_key`, `?int $object_id`, `array $args`
Returns	`mixed`, the value to use
Default	The stored value (or the `default` argument when empty)
Runs	On every read through `wpmcf_get_field()`, `wpmcf_the_field()`, `[wpmcf_field]`, blocks, bindings and `{{ fg.* }}`, before variables are evaluated and before escaping. `$args` holds what the caller passed (`context`, `path`, `default`, `format` ...).

php

add_filter( 'wpmcf/field/value', function ( $value, $group, $field ) {
    if ( $group === 'product' && $field === 'price' && is_numeric( $value ) ) {
        return $value * 1.2;               // show prices with tax
    }
    return $value;
}, 10, 3 );

`wpmcf/field/the_escaped`


Plan	Free
Arguments	`string $escaped`, `string $group_key`, `string $field_key`, `?int $object_id`, `array $args`
Returns	`string` that is already safe to print
Runs	In `wpmcf_the_field()` and the shortcode, after the value was escaped for its format and before the wrapper element is added. Not run when the escaped value is empty.

You are responsible for the safety of what you return. Escape anything you add.

`wpmcf/field/the_html`


Plan	Free
Arguments	`string $markup`, `string $group_key`, `string $field_key`, `?int $object_id`, `array $args`, `string $escaped`
Returns	`string` safe HTML
Runs	Last step of `wpmcf_the_field()` and the shortcode: `$markup` is the full output including the wrapper `<span>`; `$escaped` is the inner content.

php

add_filter( 'wpmcf/field/the_html', function ( $markup, $group, $field ) {
    return $group === 'product' && $field === 'badge' ? '<strong>' . $markup . '</strong>' : $markup;
}, 10, 3 );

`wpmcf/field/the_password`


Plan	Free
Arguments	`bool $allow`
Returns	`bool`. `true` lets a password field's value be printed, returned by `{{ fg.* }}` and read by the field runtime.
Default	`false`
Runs	Whenever the plugin decides whether a password field may leave the database through a template path. The hashed storage mode is never revealed regardless.

php

add_filter( 'wpmcf/field/the_password', '__return_true' );   // the site accepts printing stored passwords

`wpmcf/field/resolve_variables`


Plan	Free
Arguments	`bool $trusted`, `string $group_key`, `string $field_key`, `int $object_id`, `string $context`
Returns	`bool`. `true` evaluates `{{ }}` in this stored value.
Default	Post: the post author has `unfiltered_html`. User: that user has it. Comment: `false`. Term, widget, options: `true`.
Runs	Once per string value read through the field runtime that contains `{{`. `$context` is `post`, `user`, `term`, `comment`, `widget` or `options`.

Examples and the reasoning are on Security.

`wpmcf/field/repeater_html`


Plan	Free
Arguments	`string $html`, `array $rows`, `FieldDTO $field`
Returns	`string` HTML
Runs	When a repeater value is turned into the default list markup (`<ol class="wpmcf-repeater">`). Use it to restyle the default output of `wpmcf_the_field()`.

`wpmcf/field/flexible_content_html`


Plan	Pro
Arguments	`string $html`, `array $rows`, `FieldDTO $field`
Returns	`string` HTML
Runs	When a flexible content value is turned into the default markup (`<div class="wpmcf-flexible">`).

Global Data output

Same shape as the field filters, for Global Data.

Hook	Plan	Arguments	Returns	Runs
`wpmcf/global/value`	Free	`mixed $value`, `string $key`, `array $args`	`mixed`	On every read (`wpmcf_get_global()`, `wpmcf_the_global()`, `[wpmcf_global]`), before `{{ }}` evaluation.
`wpmcf/global/the_escaped`	Free	`string $escaped`, `string $key`, `array $args`	`string` safe text	In `wpmcf_the_global()` and the shortcode after escaping.
`wpmcf/global/the_html`	Free	`string $markup`, `string $key`, `array $args`, `string $escaped`	`string` safe HTML	Last step of printing; `$markup` includes the wrapper.
`wpmcf/global/the_password`	Free	`bool $allow`	`bool` (default `false`)	Decides whether a password variable can be printed or read through `{{ glb.* }}`.

php

add_filter( 'wpmcf/global/value', function ( $value, $key ) {
    return $key === 'phone' ? preg_replace( '/\s+/', ' ', (string) $value ) : $value;
}, 10, 2 );

Variables

`wpmcf/variables/context`


Plan	Free
Arguments	`EvaluationContext $context`
Returns	`EvaluationContext`
Runs	At the start of every top-level evaluation (not for nested blocks). Add request data with `$context->withMeta( $key, $value )`; Programmatic SEO uses it to give field values on a generated page the page's data row.

php

add_filter( 'wpmcf/variables/context', fn ( $ctx ) => $ctx->withMeta( 'campaign', 'spring-sale' ) );

`wpmcf/variables/allowed_options`


Plan	Free
Arguments	`string[] $options`
Returns	`string[]` option names `fn.option()` may read
Default	`blogname`, `blogdescription`, `siteurl`, `home`, `date_format`, `time_format`, `timezone_string`, `gmt_offset`, `start_of_week`
Runs	On every `fn.option()` call.

Add only options that are safe on a public page. See Security.

Field groups, location rules and storage

`wpmcf/fields/initial_values`


Plan	Free (Business adds the translation prefill)
Arguments	`array $values`, `FieldGroupDTO $group`, `WP_Post $post`
Returns	`array` of storage column => value
Default	`[]`
Runs	On a post edit screen when the post has no stored row for the group yet. Use it to prefill a new post (a new translation is prefilled from its original this way).

`wpmcf/fields/translation_ui`


Plan	Free (set to `true` by the Business multilingual module)
Arguments	`bool $show`
Returns	`bool`
Default	`false`
Runs	When field builder data is prepared. `true` shows the per-field translation mode (copy, translate, ignore).

`wpmcf/fields/schema_background_rows`


Plan	Free
Arguments	`int $rows`
Returns	`int`
Default	`100000`
Runs	When a table change is planned. Changes on tables with more rows than this run in the background; a change that rewrites stored values switches at 5,000 rows at most.

`wpmcf/field_groups/builder_pages`


Plan	Free
Arguments	`string[] $page_ids`
Returns	`string[]`
Default	`['field-groups']`
Runs	When screen data is localized. Pages in the list receive the field type metadata (`wpmcfData.fieldTypes`), so a screen that embeds the field builder can use it.

`wpmcf/field_groups/managed_by`


Plan	Free
Arguments	`?string $managed_by`, `string $group_key`
Returns	`?string`. A non-empty string marks the group as maintained outside the editor (`php` for groups registered with `wpmcf_register_field_group()`).
Default	`null`
Runs	When a field group is returned over REST. A managed group is read-only in the editor and refuses `PUT` and `DELETE` with `409 wpmcf_managed_by_code`.

`wpmcf/location/params`


Plan	Free
Arguments	`array $params`
Returns	`array<string, string[]>`: location parameter => the contexts it applies to
Default	`[]`
Runs	When location rules are checked. Valid contexts are `post_edit`, `user_edit`, `term_edit`, `comment_edit`, `menu_item_edit`, `widget_edit`, `options_page` and `order_edit`. A name that matches a built-in parameter is ignored.

`wpmcf/location/actual_value`


Plan	Free
Arguments	`?string $value`, `string $param`, `LocationContext $context`, `array $context_bag`
Returns	`?string`: the value the rule's parameter is compared against on this screen; `null` means "the rule does not match"
Default	`null`
Runs	For every rule whose parameter is not built in.

`wpmcf/location/ui_params`


Plan	Free
Arguments	`array $params`
Returns	`array` of rule builder entries `{ param, group, label, noun, screen, choices: [ { value, label } ] }`
Default	`[]`
Runs	When field builder data is prepared (`wpmcfData.locationParams`).

`wpmcf/location/options_pages`


Plan	Free
Arguments	`array $pages`
Returns	`array` of `{ value: string, label: string }`
Default	`[]` (the Options Pages module fills it)
Runs	When the rule builder asks which options pages exist.

Shortcodes, queries and options pages

`wpmcf/shortcode/can_view`


Plan	Free
Arguments	`bool $visible`, `string $context`, `int $object_id`
Returns	`bool`
Default	Post: the visitor can read it and it is not password-protected (editors always can). User: the visitor themself, the author of the post being displayed, or someone with `list_users`. Term: its taxonomy is publicly viewable. Comment: approved on a viewable post, or the visitor can edit it. Widget and options: `true`.
Runs	When a shortcode, block or builder element asks for a value of an explicit object (`id="…"`). `$context` is `post`, `user`, `term`, `comment`, `widget` or `options`. The PHP API is not restricted.

Options values inside post content are checked separately: the post's author must hold a capability from wpmcf/options/capabilities (default manage_options). This filter then receives that result with context options and ID 0. Outside any post, templates and widgets are trusted; REST and ajax requests need the capability themselves.

`wpmcf/options/capabilities`


Plan	Free
Arguments	`string[] $capabilities`, `string $group_key`
Returns	`string[]` capabilities; holding any of them lets an author's content print this group's options values
Default	`[]`, which means `manage_options`
Runs	When options values appear in post content (shortcode, block, builder) and the author must be checked.

php

add_filter( 'wpmcf/options/capabilities', fn ( $caps, $group ) => $group === 'contact' ? [ 'edit_others_posts' ] : $caps, 10, 2 );

`wpmcf/query/public_orderby`


Plan	Free
Arguments	`bool $allow`, `WP_Query $query`
Returns	`bool`
Default	`false`
Runs	On the front-end main query when the URL's own `orderby=wpmcf:group.field` is the ordering. Return `true` to honor field ordering that a visitor requested. Ordering set by your code is always honored.

Admin screens

`wpmcf/admin/localize_data`


Plan	Free
Arguments	`array $data`, `string $page_id`
Returns	`array`, the data printed as `window.wpmcfData`
Runs	When a plugin screen's script is localized. Add keys for your own script; do not remove existing keys.

`wpmcf/admin/docs_links`


Plan	Free
Arguments	`array<string, string> $links` topic => URL
Returns	`array<string, string>`
Default	`[]`
Runs	When help links are built. Known topics: `home`, `getting-started`, `field-groups`, `field-types`, `location-rules`, `template-functions`, `global-data`, `post-types`, `taxonomies`, `pseo`, `health`, `support`. Other keys and non-URL values are dropped.

`wpmcf/onboarding/checklist`


Plan	Free
Arguments	`array $items`, `array $state`
Returns	`array` of items `{ id, title, description, done, manual, action_label, action_url }`
Runs	When the dashboard checklist is built. `$state` is the stored onboarding state (`goal`, `done`, ...).

Admin columns

Hook	Plan	Arguments	Returns	Runs
`wpmcf/admin_columns/columns`	Free	`array $columns`, `string $kind`, `string $subtype`	`array` of descriptors `{ key, label, group, field, sortable }`	Before columns are added to a list table. `$kind` is `post`, `term` or `user`; `$subtype` is the post type or taxonomy.
`wpmcf/admin_columns/value`	Free	`string $html`, `FieldDTO $field`, `FieldGroupDTO $group`, `int $object_id`, `string $kind`	`string` escaped HTML of one cell; empty shows the "No value" placeholder	For each cell rendered.
`wpmcf/admin_columns/filterable`	Pro	`bool $enabled`, `array $column`, `FieldDTO $field`, `string $kind`	`bool`	When a column would get a filter control. `false` opts it out.
`wpmcf/admin_columns/editable`	Pro	`bool $enabled`, `array $column`, `FieldDTO $field`, `string $kind`	`bool`	When a column would get inline (quick and bulk) editing. `false` opts it out.

php

add_filter( 'wpmcf/admin_columns/editable', function ( $enabled, $column ) {
    return $column['field'] === 'price' ? false : $enabled;
}, 10, 2 );

Post types and taxonomies

Hook	Plan	Arguments	Returns	Runs
`wpmcf/post_types/register_args`	Free	`array $args`, `string $name`, `array $definition`	`array` for `register_post_type()`	Right before registration.
`wpmcf/taxonomies/register_args`	Free	`array $args`, `string $name`, `array $definition`	`array` for `register_taxonomy()`	Right before registration.
`wpmcf/post_types/allowed_callbacks`	Free	`string[] $functions`, `string $arg`	`string[]` function names	When a stored definition names a callback (such as `register_meta_box_cb`). Default `[]`: no function is allowed. A name is used only if listed here and the function exists.
`wpmcf/taxonomies/allowed_callbacks`	Free	`string[] $functions`, `string $arg`	`string[]`	Same for taxonomies. Default: WordPress's own `_update_post_term_count` and `_update_generic_term_count` for `update_count_callback`, otherwise `[]`.

php

add_filter( 'wpmcf/post_types/register_args', function ( $args, $name ) {
    if ( $name === 'book' ) {
        $args['menu_icon'] = 'dashicons-book';
    }
    return $args;
}, 10, 2 );

Local JSON

Hook	Plan	Arguments	Returns	Runs
`wpmcf/local_json/save_path`	Free	`string $path`	`string` folder (empty disables)	When definitions are saved. Default: `wpmcf-json` in the active theme.
`wpmcf/local_json/load_paths`	Free	`string[] $paths`	`string[]` folders	When definitions are read. Default: the save folder, plus the parent theme's `wpmcf-json` for a child theme.
`wpmcf/local_json/enabled`	Free	`bool $enabled`	`bool`	Whether saving to Local JSON is on. Default: the save folder exists. Return `true` to turn it on without a folder.

See Local JSON and version control.

Background jobs and database

Hook	Plan	Arguments	Returns	Runs
`wpmcf/jobs/batch_seconds`	Free	`int $seconds`	`int` (at least 1)	Each time a background batch starts. Default `20`: a batch stops taking new work after that many seconds (or at 80% of the memory limit). Lower it on slow hosts.
`wpmcf/database/migrations`	Free	`AbstractMigration[] $migrations`	`AbstractMigration[]`	When the schema manager is created. A module adds its own migrations, hooked from its provider's `register()`.

php

add_filter( 'wpmcf/jobs/batch_seconds', fn () => 10 );

Page cache

Hook	Plan	Arguments	Returns	Runs
`wpmcf/cache/enabled`	Free	`bool $enabled`	`bool`	Before every purge. Default: the Settings option "clear page caches". `false` stops all purging.
`wpmcf/cache/adapters`	Free	`CacheAdapter[] $adapters`	`CacheAdapter[]`	When the purger resolves which cache plugins to talk to (once per request). Add an adapter for a cache plugin that is not built in.

php

add_filter( 'wpmcf/cache/enabled', '__return_false' );   // never touch page caches

Page builders

`wpmcf/integrations/elementor/widgets`


Plan	Free
Arguments	`array<string, class-string> $widgets` id => class
Returns	`array` of classes extending `Integrations\Elementor\Widgets\ComponentWidget`
Default	`['field' => FieldWidget::class]`
Runs	When the Elementor widgets are registered.

Licensing (Pro)

Hook	Plan	Arguments	Returns	Runs
`wpmcf/licensing/grace_days`	Pro	`int $days`	`int` (negative values count as 0)	When the end of the grace period after a license expired is computed. Default `14`, or the value of the constant `WPMCF_PSEO_GRACE_DAYS`. Generated pages keep serving for that many days.
`wpmcf/licensing/expired_downloads`	Pro	`array $links`	`array` of `{ label, url }`	When the expiry notice is drawn: download links for data the owner can still take out (data tables add each table's CSV).

AI (Pro)

`wpmcf/ai/providers`


Plan	Pro
Arguments	`array<string, Provider> $providers`
Returns	`array<string, Provider>`, id => provider (entries that are not `Provider` objects are dropped)
Default	`openai`, `anthropic`, `gemini`
Runs	The first time the provider list is needed. Add or replace a provider, for example a stub in tests.

Data tables (Pro)

Hook	Plan	Arguments	Returns	Runs
`wpmcf/data_tables/feed_hosts`	Pro	`string[] $hosts`	`string[]` host patterns (`*` wildcard)	When a CSV feed URL is checked. Default: `docs.google.com`, `doc-*-sheets.googleusercontent.com`. Add the hosts your CSV links live on. Redirects are checked again.
`wpmcf/data_tables/feed_max_bytes`	Pro	`int $bytes`	`int` (at least 1024)	Before a feed is downloaded. Default 20 MB.
`wpmcf/data_tables/feed_timeout`	Pro	`int $seconds`	`int`	Per feed request. Default 30.
`wpmcf/data_tables/import_max_bytes`	Pro	`int $bytes`	`int`	When an uploaded CSV is accepted. Default 50 MB.
`wpmcf/import/fallback_encoding`	Pro	`string $encoding`, `string $locale`	`string`	When a CSV is not UTF-8: the Windows code page to try (`1252`, `1254`, ...), chosen from the locale by default.
`wpmcf/data_tables/usage`	Pro	`array $usage`	`array<string, string[]>` table key => labels	When the data tables list shows "used by". Add `$usage[ $table_key ][] = 'My module'`.

php

add_filter( 'wpmcf/data_tables/feed_hosts', function ( $hosts ) {
    $hosts[] = 'example.com';
    return $hosts;
} );

Forms (Pro)

Hook	Plan	Arguments	Returns	Runs
`wpmcf/forms/verify_submission`	Pro	`bool\|WP_Error $verified`, `FormDTO $form`, `array $request`	`true`, `false`, or a `WP_Error` whose message the visitor sees	After the built-in checks passed. Use it for CAPTCHA or Turnstile. `$request` is the unslashed, unsanitized `$_POST`.
`wpmcf/forms/rate_limit`	Pro	`array $limit`, `FormDTO $form`, `int $user_id`	`array{max: int, window: int}`	Per submission. Default `max` 5 per `window` 600 seconds; `max` 0 means no limit.
`wpmcf/forms/client_ip`	Pro	`string $ip`	`string` valid IP	When the visitor IP is read for the rate limiter. Default: `REMOTE_ADDR`, or the header named by the constant `WPMCF_CLIENT_IP_HEADER`. An invalid value falls back to `REMOTE_ADDR`.
`wpmcf/forms/upload_max_bytes`	Pro	`int $bytes`, `FieldDTO $field`, `?object $context`	`int` (at least 1)	For each file field. Default: the smaller of the server upload limit and the plugin cap. `$context` is the form or connection.
`wpmcf/forms/guest_file_types`	Pro	`string[] $extensions`, `FieldDTO $field`	`string[]`	For a file field without its own list when the visitor cannot upload files. Default: `jpg, jpeg, png, gif, webp, pdf, txt, csv, doc, docx, odt, xls, xlsx, ods`.
`wpmcf/forms/registration_roles`	Pro	`string[] $roles`	`string[]` role names	When a registration form lists assignable roles. Narrow only: it starts with the roles that carry no powerful capability, and roles you add that are unsafe are ignored.
`wpmcf/forms/password_is_strong`	Pro	`bool $strong`, `string $password`, `string $login`	`bool`	When a registration password is checked. Default: 10 or more characters, at least 2 of the 4 character classes, contains a letter, not containing the login.
`wpmcf/forms/connection_plugins`	Pro	`array<string, FormPlugin> $plugins`	`array` id => adapter	When connections to other form plugins are set up. Add an object implementing `Pro\Forms\Connections\FormPlugin`.

php

add_filter( 'wpmcf/forms/verify_submission', function ( $ok, $form, $request ) {
    if ( empty( $request['cf-turnstile-response'] ) ) {
        return new WP_Error( 'captcha', 'Please complete the check.' );
    }
    return $ok;
}, 10, 3 );

Programmatic SEO (Pro)

`wpmcf/pseo/conversion/skip_meta_keys`


Plan	Pro
Arguments	`string[] $keys`
Returns	`string[]` post meta keys that are not copied from the page template to a converted post
Default	`_edit_lock`, `_edit_last`, `_wp_old_slug`, `_wp_old_date`, `_elementor_css`, `_wp_trash_meta_status`, `_wp_trash_meta_time`
Runs	For each converted page.

JavaScript filter

wpmcf.settings.tabs (@wordpress/hooks): a map of Settings section ID to React component, used with the wpmcf/settings/register_sections action to add a tab to the Settings screen.

Was this page helpful?

Still stuck? Contact support

Hooks reference: filters

Contents

Reading and printing field values

wpmcf/field/value

wpmcf/field/the_escaped

wpmcf/field/the_html

wpmcf/field/the_password

wpmcf/field/resolve_variables

wpmcf/field/repeater_html

wpmcf/field/flexible_content_html

Global Data output

Variables

wpmcf/variables/context

wpmcf/variables/allowed_options