Metadata and Custom Fields

All of them wrap add_metadata() and its siblings, which take the object type first (Multisite adds wp_blogmeta). Storage and query cost are on Database Schema. Surprising behaviours:

register_meta( $object_type, $meta_key, $args ) records a key in the global registry; register_post_meta() and register_term_meta() also set the post type or taxonomy as object_subtype. Register on init, for a specific subtype whenever there is one: a key registered without a subtype applies to every post type or taxonomy that does not register its own.

REST also requires the post type to support custom-fields; without it, the meta field is missing even for registered keys. Core registers one such key itself: footnotes (6.3, for the Footnotes block), which is why it appears in the outputs below.

The REST API, the edit screen and the Custom Fields panel check current_user_can( 'edit_post_meta', $post_id, $meta_key ) (or add_post_meta, delete_post_meta, and the same for term, user and comment). map_meta_cap() resolves these meta capabilities in two steps:

The callback receives $allowed, $meta_key, $object_id, $user_id, $cap and $caps; its result is combined with step 1, so what matters in can_edit_isbn() is the extra edit_others_lp_books (the book capability from Custom Post Types and Taxonomies). Returning true for a protected key opens it to REST writes. See also Roles and Capabilities API.

A key whose first character is an underscore is protected: is_protected_meta() returns true, the Custom Fields panel hides it, Block Bindings refuse it, and REST writes are denied unless an auth_callback allows them. Core keeps its own bookkeeping in protected keys, such as _thumbnail_id, _edit_lock, _wp_page_template and _wp_attached_file. The is_protected_meta filter can protect other keys or unprotect one.

Protection is about editing, not secrecy. _lp_stock_synced_at has show_in_rest, so it is in every REST response for a book, anonymous ones included; it only cannot be changed there. Data that must stay private (internal notes, supplier prices, personal data) stays out of show_in_rest, or is exposed through a REST field with its own permission check (see REST API: Extending It).

Keys with show_in_rest appear in the meta object of the posts, terms, users and comments endpoints. The site is the one from Local Development Environments, with maria.editor (Editor, ID 2) and tom.author (Author, ID 3, the author of book 4). Application passwords require HTTPS unless WP_ENVIRONMENT_TYPE is local:

Source: WP-CLI: wp user application-password create

An anonymous read shows every registered key, the protected one included, with its registered type. The Editor may change the ISBN and page count in one request; the Author of the same book may change the page count but not the ISBN:

Source: REST API Handbook: Authentication

Schema violations are rejected with 400 before anything is stored, the protected key is refused even to the Editor, null deletes a value (reads return the default), and an unauthenticated write fails the post permission check before meta is looked at (the same requests as above, as maria.editor, except the last):

Source: REST API Handbook: Modifying Responses

Three more rules matter in practice. A value equal to the stored one is skipped before the capability check, so the block editor, which resends all meta on every save, does not fail for an Author who cannot edit lp_isbn. A request that cannot authenticate (a wrong application password, or a cookie request without the wp_rest nonce) continues as anonymous and fails on the permission check, as the last call shows. And because lp_isbn has revisions_enabled, every ISBN change creates a revision carrying the value: GET /wp/v2/lp_book/4/revisions returns it in each revision’s meta, and restoring a revision restores the ISBN while the other keys, not revisioned, are left alone.

The same registration, permission and REST rules apply to the other object types:

Source: WP-CLI: wp term meta, WP-CLI: wp user meta

The anonymous user read works because the users endpoint publicly lists authors of published REST-enabled posts, with their show_in_rest meta. Register user meta for REST only when it is meant to be public, and never put personal data in such a key (see Privacy and Personal Data); persisted_preferences is core’s own user meta for editor preferences. Comments have no subtypes: a reader rating is stored with wp comment meta add 2 lp_rating 5 (or add_comment_meta()) and registered with register_meta( 'comment', 'lp_rating', ... ).

A meta box is a PHP-rendered panel on the post edit screen; in the block editor it appears below the content (normal, advanced) or in the sidebar (side). lumen-catalog keeps one for the classic editor and for sites without the sidebar panel from Data Layer and Editor Extensibility; Plugin::boot() calls MetaBox::register() only when is_admin() is true.

Source: Plugin Handbook: Custom Meta Boxes

Each check in the save handler has a reason:

Two add_meta_box() callback arguments matter only in the block editor: __block_editor_compatible_meta_box set to false replaces a box known to break with a notice, and __back_compat_meta_box set to true hides a box that a block or panel has replaced, while keeping it in the classic editor.

The block editor saves the post through REST first, then submits the meta box areas as a separate form POST to post.php?post=4&action=edit&meta-box-loader=1, which runs save_post again with the box fields in $_POST (without an extra revision). A key edited both in a sidebar panel and in a meta box therefore ends with the meta box value, so each key should have one editing UI. Scripts that hook the classic form’s submit event, the classic title and content fields or TinyMCE do not work there. Before 7.1, a meta box also kept the post editor out of the iframe; since 7.1 the editor is always iframed and meta boxes stay outside the canvas.

A simulated form POST tests the handler without a browser: it fills $_POST as post.php would, with or without a fresh nonce, and saves the book as different users. Run it with wp eval-file metabox-save.php:

Source: WP-CLI: wp eval-file

Source: Code Reference: save_post_\{$post->post_type\} hook

The Editor’s save is stored, the same request without a nonce is ignored, the Author’s ISBN is skipped while the page count is saved, and an invalid ISBN and an impossible date (30 February) delete the rows.

In the block editor, meta with show_in_rest is part of the post entity in the core data store. A PluginDocumentSettingPanel (from @wordpress/editor) edits it with useEntityProp( 'postType', 'lp_book', 'meta' ) and saves it in the post’s REST request, under the same auth_callback; the lumen-catalog panel is on Data Layer and Editor Extensibility.

Block Bindings (6.5+) connect core block attributes to data without a custom block: a Paragraph bound to the core/post-meta source with the key lp_isbn shows each book’s ISBN, and since 6.7 the value can be edited in place. The source reads only keys registered with show_in_rest and not protected, on posts the visitor may read. Bindings for book meta, including a custom source, are on Block Bindings API.

The Custom Fields panel is the generic key-value editor that predates registered meta. It lists every unprotected key of the post, registered or not, as free text, and offers earlier keys in a drop-down. In the block editor it is off by default: Options menu (three dots), Preferences, General, turn on Custom fields under Advanced and reload the page. It exists only for post types that support custom-fields. It is handy for inspection, but a poor editor for structured data (plain strings, no validation beyond the sanitizer) and it submits after the REST save like a meta box, so sites that edit books through a dedicated panel or box keep it off.

Field plugins add a no-code interface for defining field groups, rich field types (relationships, repeaters, galleries, flexible layouts), location rules and options pages, and store values as ordinary metadata:

The trade-off: faster building and a friendlier UI, against a data model owned by the plugin and a migration if it is dropped. A distributed plugin like lumen-catalog registers its own meta; a site-specific build may reasonably use a field plugin, checking that fields reach REST when a headless front end or Block Bindings need them.

Older books teach meta boxes in a theme’s functions.php; content fields belong in a plugin, or a theme switch leaves the data uneditable. Pro WordPress registers post types without 'show_in_rest' => true, so those posts open in the classic editor and their meta never reaches REST, the editor’s data store or Block Bindings. Book-era meta box examples typically check a nonce or a capability but not both, skip the autosave check and store $_POST values without unslashing and sanitizing. None of the three books covers register_post_meta() arguments, REST schemas, auth_callback, revisions_enabled (6.4) or Block Bindings (6.5+), and the Custom Fields panel they show is now hidden in the editor’s preferences (full list: Where Older Books and Tutorials Are Outdated).

Custom Post Types and Taxonomies, Security for Developers, REST API: Using It, Posts and Pages (revisions), WP-CLI and Importing, Exporting and Migrating (meta in WXR files). WooCommerce product data is covered in Products and Product Types.