Bootstrap field collections by oandregal · Pull Request #76332 · WordPress/gutenberg

oandregal · 2026-03-09T18:10:41Z

What?

Introduces a Field Collections API — a server-side registration system for defining a collection of fields for an entity.

A field collection is a PHP structure that includes:

An identifier for the collection: id, kind, name.
A list of fields:
- Fields are defined in PHP, via the declarative Fields API (works across DataViews/DataForm).
- Optionally, fields can provide JavaScript code to extend the core functionality for properties that cannot be serializable (e.g., a function defining a render method of a field).
A list of strings representing WordPress module scripts. These scripts contain the JavaScript extensions to fields.

Why

Part of #74865

How

PHP API to register and read collections at lib/compat/wordpress-7.1/field-collections.php:

gutenberg_register_field_collection( $id, $kind, $name, $fields, $fields_modules );
gutenberg_get_field_collections( $kind, $name );
gutenberg_get_all_field_collections();
gutenberg_enqueue_field_collections_loader();

REST API Endpoint that exposes the collection data at lib/compat/wordpress-7.1/class-gutenberg-rest-field-collections-controller.php:

http://<site>/wp-json/wp/v2/field-collections?kind=KIND&name=NAME

A useFieldCollections( kind, name ) JavaScript hook (code) that request the collection data (REST Endpoint), imports dynamically the WordPress script modules for the collection (JavaScript extensions), and merges it together for consumers to use.

Field Collection definitions for core/Gutenberg:

Registration of the field collections at lib/compat/wordpress-7.1/field-collections-register-core-collections.php
The definition for each collection at packages/field-collections/src/collections.

Extensibility

The goal is to make it easy to tweak the small things and the complex ones possible.

The API introduces a way for 3rd parties to register their own collections, see example for postType-attachment. Additionally, we wanted to auto-register fields for all (Custom) Post Types, while providing a mechanism to extend the defaults. The API supports three use cases:

A plugin registers a CPT and wants to register its own collection. Uses gutenberg_register_field_collection. Example.
A plugin wants to add/update/remove an existing field of a collection. For example, the postType/page wants to disable hiding the title field. It hooks into the gutenberg_field_collection_fields filter and updates its output:

add_filter(
	'gutenberg_field_collection_fields',
	function ( $fields, $id, $kind, $name ) {
		if ( 'postType' !== $kind || 'page' !== $name ) {
			return $fields;
		}

		foreach ( $fields as &$field ) {
			if ( 'title' === $field['id'] ) {
				$field['enableHiding'] = false;
			}
		}
		unset( $field );

		return $fields;
	},
	10,
	4
);

A plugin wants to add/update some JavaScript extension. For example, adding a different render method for the title field. It needs to prepare a module script and attach it to the list of filter modules for that collection:

add_filter(
	'gutenberg_field_collection_modules',
	function ( $modules, $id, $kind, $name ) {
		if ( 'postType' === $kind && 'page' === $name ) {
			$modules[] = '@wordpress/field-collections/postType-page';
		}

		return $modules;
	},
	10,
	4
);

Status

Prototype, not ready to ship.

This API is inspired by prior prototypes implemented by @youknowriad, @gigitux, and other folks in the Woo realm. It's also vibe coded and not fully human reviewed yet. The focus right now is to understand how to support all the use cases we want via the API surface.

Open questions:

Migration/Deprecation:
- Field definitions: from @wordpress/fields and @wordpress/media-fields to @wordpress/field-collections.
- Data store: from editor to a dedicated field-collections store (e.g., registerEntityField API that was available only when Gutenberg was active).

Test

Site Editor: Pages, Templates, Patterns.
Enable experiment for DataForm in Editor Inspector.

github-actions · 2026-03-09T18:10:51Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: oandregal <oandregal@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-03-09T18:23:27Z

Size Change: +120 kB (+1.39%)

Total Size: 8.72 MB

📦 View Changed

Filename	Size	Change
`build/modules/field-collections/loader.min.js`	59 B	+59 B (new file)	🆕
`build/modules/field-collections/postType-attachment.min.js`	39.4 kB	+39.4 kB (new file)	🆕
`build/modules/field-collections/postType-default.min.js`	67.6 kB	+67.6 kB (new file)	🆕
`build/modules/field-collections/postType-page.min.js`	1.41 kB	+1.41 kB (new file)	🆕
`build/modules/field-collections/postType-wp_block.min.js`	37.4 kB	+37.4 kB (new file)	🆕
`build/modules/field-collections/postType-wp_template.min.js`	1.02 kB	+1.02 kB (new file)	🆕
`build/scripts/editor/index.min.js`	445 kB	-28.9 kB (-6.11%)	✅
`build/scripts/field-collections/index.min.js`	1.63 kB	+1.63 kB (new file)	🆕
`build/scripts/private-apis/index.min.js`	1.13 kB	+8 B (+0.71%)

_{compressed-size-action}

ntsekouras · 2026-03-13T09:29:49Z

+ * REST API: Gutenberg_REST_Field_Collections_Controller class
+ *
+ * @package gutenberg
+ * @since 20.8.0


Nit: We should update the proper version before mergin.

ntsekouras · 2026-03-13T09:30:03Z

+ * @since 20.8.0
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {


I don't think we need this check.

ntsekouras · 2026-03-13T09:34:23Z

+	 * @return array Collection parameters.
+	 */
+	public function get_collection_params() {
+		$params = parent::get_collection_params();


Nit: We probably only want 'context' => $this->get_context_param(), from get_collection_params. We don't support search or pagination.

ntsekouras · 2026-03-13T09:46:19Z

 		supportsPagination: true,
 	},
+	{
+		label: __( 'Field Collection' ),


Should this be plural?

ntsekouras · 2026-03-13T09:49:07Z

+		label: __( 'Field Collection' ),
+		name: 'fieldCollection',
+		kind: 'root',
+		baseURL: '/wp/v2/field-collections',


Even though view context seems to be the default, should we be explicit like icons and fonts(baseURLParams: { context: 'view' },)?

ntsekouras · 2026-03-13T10:11:15Z

+	'filterBy'      => false,
+);
+
+gutenberg_register_field_collection(


Should we wrap this in a rest_api_init hook?

ntsekouras · 2026-03-13T10:13:09Z

+	// Check if collection with same ID already exists.
+	foreach ( $gutenberg_field_collections as $existing_collection ) {
+		if ( $existing_collection['id'] === $id ) {
+			return;


Should we add a _doing_it_wrong here?

ntsekouras · 2026-03-13T10:16:19Z

+}
+
+// Global storage for registered field collections.
+global $gutenberg_field_collections;


It's definitely fine to start with a global, but have you considered a registry?

ntsekouras · 2026-03-13T10:18:24Z

 				);
 			} );
+			( fieldCollections ?? [] ).forEach( ( collection: any ) => {
+				if (


It's fine if we don't handle the universal (name:null) in here, but we should add a TODO comment not to forget it with the follow ups.

oandregal · 2026-03-16T17:04:39Z

I'm going to leave this one in the backburner for a few days and will focus on the view/form config first.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

All fields except the content preview are now provided by server-side field collections: hand-written collections for the core post types and the dynamic postType-default registrar for every other REST-enabled post type. The preview field stays client-side because its render depends on editor internals the collections' script modules cannot import. Post types registered after init priority 100 no longer get any fields, as they have no server-side collection and the client-side fallback is gone. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Move the field collections out of @wordpress/fields into a new @wordpress/field-collections package that owns a dedicated, editor-free data store (core/field-collections) and a useFieldCollections hook. Previously the merged field registry lived in the core/editor store, so any screen needing field definitions had to depend on @wordpress/editor. The new package fetches definitions from GET /wp/v2/field-collections, lazily imports each collection's extension script module, and merges by field id — depending only on data/api-fetch/element/compose/url/private-apis (+ dataviews types). - Move collections/ to the new package; re-point extensions.ts to named @wordpress/fields imports; rename module handles to @wordpress/field-collections/{loader,postType-*}. - Move wpScriptModuleExports + wpCopyFiles to the new package; update the PHP glob path and loader id. Registration API, REST controller, and loader enqueue stay in lib/. - Carve the collection-field merge out of registerPostTypeSchema (keeps actions + the editor-only preview field); usePostFields now combines editor fields with useFieldCollections, preview-first. - Remove the now-unused root/fieldCollection core-data entity. - Add the package to the private-apis allowlist and root tsconfig. Tests: 12 JS unit tests (reducer/selector/resolver/hook) and the existing field-collections PHPUnit suite (24 tests) pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ns onto generator Add two filters so consumers can tailor any field collection — including an auto-generated one — without re-registering it: - gutenberg_field_collection_fields ( $fields, $id, $kind, $name ): remove, reorder, relabel, or add serializable field definitions. - gutenberg_field_collection_modules ( $modules, $id, $kind, $name ): append script modules of non-serializable extensions. To support multiple contributors, a collection's single fields_module string becomes a fields_modules array (REST, store types, hook, preload). The client loads every module, concatenates their extensions, and merges all entries matching a field id so a later module overrides an earlier one property by property (last wins). Refactor the post type collections onto the default generator as the single baseline: - Delete post, wp_navigation, wp_template_part — the generator reproduces them exactly and the default union module already covers their extensions. - Convert page, wp_template, wp_block to filter-based overrides that only tweak the title field plus a slim extensions module for its title behavior. - Keep attachment standalone (bespoke; opts out by registering its own collection, which the generator then skips). Update tests (new coverage for both filters and multi-module merge) and the README. The generic REST controller tests move off real post-type names onto a synthetic entity, since the override files register persistent filters that survive the test's collection-global reset. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-17T10:34:15Z

Flaky tests detected in 045514f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27697541734
📝 Reported issues:

[Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

Add an SVG (source) and PNG (rendered, for GitHub) diagram illustrating how a field is defined in two halves — serializable definitions in PHP and non-serializable extensions in JavaScript — registered server-side, exposed via REST, and re-merged in the client by useFieldCollections before screens consume the resulting Field[]. Embed the PNG near the top of the README. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

oandregal · 2026-06-17T15:31:44Z

+ *
+ * @see packages/vips/src/loader.ts — the reference pattern
+ */
+export {};


This is intentionally empty. It only exists so that there's a handle (@wordpress/field-collections/loader) to which "attach" the scripts that will be dynamically loaded.

In use-field-collections.ts, the collections load their non-serializable field extensions with a dynamic import:

const module = await import( handle );

where handle is a string like 'core/media-fields-module'.

For the browser to resolve that specifier to an actual URL at runtime, the handle must be present in the page's import map. And for WordPress to print import-map entries for them, the modules need to be reachable from the dependency graph of an enqueued module. Hence, this empty loader.

This is another place where we do the same.

The reason I went for an empty handle instead of making the modules a dependency of some site-editor's script is that the field modules can be loaded outside the site editor. Think of examples like the settings page, connectors, comments page, etc. We cannot assume every place that needs fields collections will be part of the site editor.

oandregal · 2026-06-17T15:52:22Z

+	function gutenberg_register_default_post_type_field_collections() {
+		$post_types = get_post_types( array( 'show_in_rest' => true ) );
+
+		foreach ( $post_types as $post_type ) {
+			if ( ! empty( gutenberg_get_field_collections( 'postType', $post_type ) ) ) {
+				continue;
+			}
+
+			gutenberg_register_field_collection(
+				"core/{$post_type}-fields",
+				'postType',
+				$post_type,
+				gutenberg_get_default_post_type_fields( $post_type ),
+				'@wordpress/field-collections/postType-default'
+			);
+		}
+	}
+}


If there's no collection defined for an existing post type, we automatically register a collection for it based on its declared supports.

The extensibility section of the PR describes the mechanisms a 3rd party can use to create or tweak collecitons. Essentially:

A 3rd party can register a collection for an existing post type and this default would be ignored.

A 3rd party can hook into any of the available filters to tweak an existing collection (e.g., to add/update/remove a field).

oandregal · 2026-06-17T15:55:19Z

-	excerptField,
-	featuredImageField,
-	dateField,
-	parentField,
-	passwordField,
-	commentStatusField,
-	pingStatusField,
-	discussionField,
-	slugField,
-	statusField,
-	authorField,
-	titleField,
-	templateField,
-	templateTitleField,
-	pageTitleField,
-	patternTitleField,
-	notesField,
-	scheduledDateField,
-	formatField,
-	postContentInfoField,
-	stickyField,


All the logic about whether to load this fields now lives in PHP at packages/field-collections/src/collections/postType-default/fields.php.

oandregal · 2026-06-17T16:01:10Z

I've pushed the latest I had and updated the PR description with the current state as well as documented some parts via comments.

This API has been inspired by prior prototypes implemented by @youknowriad, @gigitux, and other folks in the Woo realm. It's also vibe coded and not fully human reviewed yet. The focus right now is to understand how to support all the use cases we want via the API surface.

I won't have the availability to push this forward to make it part of WordPress 7.1, so, unless someone else picks it up it should have to wait until next cycle. @ntsekouras is taking care of coordinating everything for DataViews/DataForm in WordPress 7.1.

oandregal requested review from TimothyBJacobs, nerrad and spacedmonkey as code owners March 9, 2026 18:10

github-actions Bot added [Package] Core data /packages/core-data [Package] Editor /packages/editor labels Mar 9, 2026

oandregal added the [Type] Technical Prototype Offers a technical exploration into an idea as an example of what's possible label Mar 9, 2026

oandregal mentioned this pull request Mar 9, 2026

Register fields for entities in the server #74865

Open

oandregal requested review from ntsekouras and youknowriad March 9, 2026 18:14

oandregal commented Mar 9, 2026

View reviewed changes

Comment thread lib/compat/wordpress-7.1/field-collections-register-core-collections.php Outdated

oandregal commented Mar 9, 2026

View reviewed changes

Comment thread packages/editor/src/dataviews/store/private-actions.ts

ntsekouras force-pushed the try/register-field-collections branch from 1758f48 to 6271427 Compare March 13, 2026 08:36

oandregal marked this pull request as draft March 13, 2026 08:55

ntsekouras reviewed Mar 13, 2026

View reviewed changes

oandregal force-pushed the try/register-field-collections branch 2 times, most recently from 227da21 to cf8a102 Compare June 10, 2026 14:54

oandregal added 3 commits June 16, 2026 17:17

Bootstrap field collections API

d084749

Add fields_module

bc5d693

Field collections module

3932c5c

oandregal and others added 14 commits June 16, 2026 17:17

Collocate PHP and JS together

840ace8

Register all fields for page in PHP

d9d49b3

Bring back commentns and notes for post type

6efb5c7

Register all fields for wp_template in PHP

171bd53

Register all fields for wp_template_part in PHP

d6a82fa

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Register all fields for attachment in PHP

8134f1f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Remove client-side attachment fields ported to PHP

2444726

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Register all fields for post in PHP

4d95c38

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Register all fields for wp_block in PHP

8d41867

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Register all fields for wp_navigation in PHP

175f400

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Register default fields for all post types in PHP

2f62b82

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

oandregal force-pushed the try/register-field-collections branch from cf8a102 to 77a42d4 Compare June 17, 2026 10:00

github-actions Bot added [Package] Private APIs /packages/private-apis and removed [Package] Core data /packages/core-data labels Jun 17, 2026

oandregal requested a review from gigitux June 17, 2026 15:00

oandregal commented Jun 17, 2026

View reviewed changes

oandregal mentioned this pull request Jun 18, 2026

Experimental: Expand Editor Inspector: Use DataForm experiment to templates #76934

Merged

oandregal closed this Oct 16, 2026

oandregal deleted the try/register-field-collections branch October 16, 2026 10:50

Conversation

oandregal commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why

How

Extensibility

Status

Test

Uh oh!

github-actions Bot commented Mar 9, 2026

Uh oh!

github-actions Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oandregal commented Mar 16, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oandregal commented Jun 17, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

oandregal commented Mar 9, 2026 •

edited

Loading

github-actions Bot commented Mar 9, 2026 •

edited

Loading

github-actions Bot commented Jun 17, 2026 •

edited

Loading