Skip to content
Developer API

Developer API overview

3 min read

Mass Custom Fields stores each field group in its own database table (see Field groups). Everything on this page is how your code gets values in and out of those tables. All of it is in the free plugin.

You want to

Use

Page

Read a value in a template

wpmcf_get_field(), wpmcf_has_field()

Reading values

Print a value safely

wpmcf_the_field(), wpmcf_the_option_field(), wpmcf_the_global()

Output formats and escaping

Save or clear a value from code

wpmcf_update_field(), wpmcf_delete_field()

Writing values

Point at a user, term, comment or options page

"user_3", "term_5", "option"

Object references

Print a value in content

[wpmcf_field], [wpmcf_global]

Shortcodes

Show a value in the block editor

WPM Field block, WPM Fields Block Bindings source

Blocks and Block Bindings

Filter or sort posts by field value

wpmcf_query, orderby wpmcf:group.field, wpmcf_query_posts()

Querying posts

Read or write values over HTTP

the wpmcf attribute on /wp/v2/posts

REST API

Use site-wide Global Data

wpmcf_get_global() and friends

Global Data functions

Verify or read a Password field

wpmcf_check_password(), wpmcf_get_password()

Password helpers and security

Look up an exact signature


Function reference

Fix something that does not work


Troubleshooting

The two keys

Almost every function takes a group key and a field key: the Key of the field group and the Key of the field, exactly as shown in WPM Fields › Field Groups. Both are lower-case letters, digits and underscores. The functions run sanitize_key() on them, so 'Listing' and 'listing' are the same key.

php
$price = wpmcf_get_field( 'listing', 'price' );   // group "listing", field "price"

Only top-level fields have a database column. To reach a value inside a Group or Repeater field, read the container and pass a path (see Reading values).

The object

Most functions take an optional third argument, the object the value belongs to:

php
wpmcf_get_field( 'listing', 'price' );               // the current post (inside the loop)
wpmcf_get_field( 'listing', 'price', 42 );           // post 42
wpmcf_get_field( 'profile', 'bio', 'user_3' );       // user 3
wpmcf_get_field( 'brand',   'color', 'term_5' );     // term 5
wpmcf_get_field( 'company', 'phone', 'option' );     // the options-page row

See Object references for every accepted form.

The $args array

The last argument is an array of options. The ones that matter most:

Key

Used by

Meaning

default

get / has / the

Value to use when the field has no value

path, sub_key

get / has / the

Reach into a Group or Repeater value

context

any function that takes an object

post, user, term, comment, widget or options

format

the_* only

auto, html, attr, url, js, post_html

wrap

the_* only

false removes the <span> wrapper

Raw versus escaped: the one rule

Function family

Returns or prints

Escaped?

wpmcf_get_*

returns the raw value

No. You must escape it for where you print it.

wpmcf_the_*

prints formatted HTML

Yes. Safe to echo as is.

[wpmcf_field], [wpmcf_global], the block

print formatted HTML

Yes.

php
// Raw value: escape it yourself.
echo '<a href="' . esc_url( wpmcf_get_field( 'listing', 'website' ) ) . '">Website</a>';

// Printing function: already escaped.
wpmcf_the_field( 'listing', 'title' );

Fault tolerance

The template functions never throw. If the plugin is not booted yet, the object is invalid, or reading fails, they return the default you passed (or null / false) and the error is logged in WPM Fields › Settings › Health. A broken field cannot break the page. When WP_DEBUG is on, a bad object argument also raises a _doing_it_wrong() notice.

Where things are not covered here

The plugin's own REST namespace

wpmcf/v1 exists for the plugin's admin screens. It is not a public API: nearly every route requires the manage_options capability (see REST API). To read or write values over HTTP, use the wpmcf attribute on the core post endpoints instead.

Was this page helpful?

Still stuck? Contact support