[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)
Search

title

Body

[close]

/wp-includes/ -> class-wp-entity-fields-registry.php (summary)

[Source view] [Print] [Project Stats]

Entity Fields API: WP_Entity_Fields_Registry class

File Size: 1029 lines (36 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

WP_Entity_Fields_Registry:: (22 methods):
  get_instance()
  register()
  update()
  unregister()
  register_collection()
  get_collection_fields()
  get_registered()
  get_all_registered()
  get_registered_field_modules()
  get_all_registered_field_modules()
  initialize()
  doing_entity_fields_api_init()
  report_unknown_types()
  validate_arguments()
  validate_entity()
  skip_invalid_definitions()
  skip_invalid_ids()
  get_collection()
  read_collection_fields()
  require_file()
  add_field_module()
  forget_empty_entity()


Class: WP_Entity_Fields_Registry  - X-Ref

Holds the fields registered for entities.

The registry maps an entity, identified by its kind and name, to its
registered field definitions keyed by id, in registration order, each
with the origins that registered and updated it, and to the script modules
registered for it, each with the ids of the fields it applies to.
register() adds fields, update() changes registered ones, and both
validate the definitions before storing them: a field that cannot be
stored is reported and skipped, and the rest of the call is stored.
register_collection() adds the fields a folder declares, see it for the
format.

Fields are registered on the `wp_entity_fields_api_init` action, and only
there, with wp_register_entity_fields(), wp_update_entity_fields(), and
wp_unregister_entity_fields(): register(), update(), and unregister() refuse
to run while the action is not firing.

The registry is filled lazily: the first time its fields are read, it
fires the `wp_entity_fields_api_init` action, on which the default fields of every
post type and the fields of plugins are registered. A read before `init`
has completed is refused, see initialize().

Once the action has fired the registry does not change: every reader of
a request, the REST controller as well as the import map of the editor
script, sees the same fields.

get_instance()   X-Ref
Returns the singleton instance.

return: WP_Entity_Fields_Registry The registry.

register( $origin, $kind, $name, $fields, $script_module = null )   X-Ref
Registers fields for an entity.

The fields must be new: a field with the id of a registered field is
reported and skipped, and so is every definition after the first of an
id that appears more than once in the call. The rest of the fields of
the call are registered: a field another plugin got to first does not
cost a plugin the others. A definition that is not an array with a
non-empty string `id` is reported and skipped the same way. To change
a registered field, see update(); to replace it, unregister it first.
The script module, if any, applies to every field the call registers.
A field whose `type` DataViews does not provide is reported and
registered anyway.

The origin is stored as the `origin` property of each field, as
`registeredBy`, replacing any `origin` the definition sets.

param: string      $origin        Who registers the fields: `core`, or
param: string      $kind          The entity kind (e.g. `postType`).
param: string      $name          The entity name (e.g. `page`).
param: array[]     $fields        The list of field definitions, each with an `id`.
param: string|null $script_module The id of the script module providing
return: string[] The ids of the fields registered, in the order of the

update( $origin, $kind, $name, $fields, $script_module = null )   X-Ref
Updates registered fields of an entity.

Each definition is merged into the registered field with its id,
property by property; the field keeps its position. The fields must be
registered: a field that is not is reported and skipped, and so is a
definition that is not an array with a non-empty string `id`; the rest
of the fields of the call are updated. The script module, if any,
applies to every field the call updates, on top of the modules the
fields have. A field whose `type` DataViews does not provide is
reported and updated anyway.

The origin is appended to the `updatedBy` list of the `origin` property
of each field, once; the rest of the `origin` property cannot be
updated, and any `origin` the definition sets is ignored.

Like register(), it only runs on the `wp_entity_fields_api_init` action.

param: string      $origin        Who updates the fields: `core`, or
param: string      $kind          The entity kind (e.g. `postType`).
param: string      $name          The entity name (e.g. `page`).
param: array[]     $fields        The list of partial field definitions,
param: string|null $script_module The id of the script module providing
return: string[] The ids of the fields updated, in the order of the

unregister( $kind, $name, $ids = null )   X-Ref
Unregisters fields of an entity.

Unregistering a field removes its registered definition and
drops it from the script modules that applied to it (a module left with
no field is forgotten). Unregistering every field forgets the entity:
its registered fields and script modules.

Like register(), it only runs on the `wp_entity_fields_api_init` action, and an
invalid entity is reported and unregisters nothing. An id that is not a
non-empty string is reported and skipped, like a definition register()
cannot store.

param: string        $kind The entity kind (e.g. `postType`).
param: string        $name The entity name (e.g. `page`).
param: string[]|null $ids  The ids of the fields to unregister. Default
return: array[] The list of the definitions unregistered, in

register_collection( $directory )   X-Ref
Registers the fields of a field collection.

A collection is a folder whose `index.php` returns its configuration, with
a folder per field whose `field.php` returns the serializable part of the
field (see get_collection_fields()). Each file is required without
sharing the variables of the caller, see require_file(). The JavaScript
parts of the fields, if any, ship in the script module of the
collection. The configuration is an array with these keys:

- `origin` (required): who registers the fields: `core`, or the slug of
the plugin or theme. See register().
- `kind` (required): the entity kind, e.g. `postType`.
- `name` (required): the entity name, e.g. `wp_template`.
- `module` (optional): the id of the script module providing the
JavaScript parts of the fields. Every field of the collection is
registered with it.

The collection registers its fields on the entity, after the fields
registered on it before, in the alphabetical order of their folders.
register() skips a field already registered for the entity, and
registers the rest of the collection. Like register(), it does not check
that the entity exists: the `/wp/v2/entity-fields` route only serves the fields
of the entities the REST API exposes.

Fields that apply to several entities, such as the defaults every post
type derives from its supports, are registered in code: a
`wp_entity_fields_api_init` callback can read their definitions from files with
get_collection_fields() and register them on each entity with
register().

Like register(), it only runs on the `wp_entity_fields_api_init` action. An
invalid configuration is reported with _doing_it_wrong() and skipped. So
is an invalid `field.php`, see get_collection_fields(): the rest of the
fields of the collection are registered.

param: string $directory The directory of the collection.
return: bool Whether the collection is valid and all of its fields are

get_collection_fields( $directory )   X-Ref
Returns the fields of a field collection.

A collection holds a folder per field, whose `field.php` returns the
serializable part of the field, see register_collection().

param: string $directory The directory of the collection.
return: array<string, array> The fields of the collection, keyed by id, in

get_registered( $kind, $name )   X-Ref
Returns the fields registered for an entity.

param: string $kind The entity kind (e.g. `postType`).
param: string $name The entity name (e.g. `page`).
return: array[] The list of field definitions, in registration order.

get_all_registered()   X-Ref
Returns the fields registered for every entity.

return: array<string, array<string, array[]>> The lists of field

get_registered_field_modules( $kind, $name )   X-Ref
No description

get_all_registered_field_modules()   X-Ref
Returns the ids of the script modules registered for every entity.

return: array<string, array<string, string[]>> The lists of module ids,

initialize()   X-Ref
No description

doing_entity_fields_api_init( $method )   X-Ref
Checks that the `wp_entity_fields_api_init` action is firing, as register(),
update(), and unregister() require.

Outside the action a registration would either come before the
defaults, which could then not be registered, or after the fields have been read
and the import map of the editor script built from them. Refusing
keeps the registry immutable once read.

param: string $method The calling method, for the notice.
return: bool Whether the action is firing.

report_unknown_types( $method, $kind, $name, $fields )   X-Ref
Reports the fields whose `type` is not one the REST schema of the
fields lists, with _doing_it_wrong(). Those are the types DataViews
provides a control for: a misspelt type is otherwise silent, the field
renders without a control. A missing `type` is fine.

param: string  $method The calling method, for the notice.
param: string  $kind   The entity kind.
param: string  $name   The entity name.
param: array[] $fields The field definitions.

validate_arguments( $method, $origin, $kind, $name, $fields, $script_module )   X-Ref
Validates the arguments of register() and update().

param: string $method        The calling method, for the notice.
param: mixed  $origin        The origin.
param: mixed  $kind          The entity kind.
param: mixed  $name          The entity name.
param: mixed  $fields        The field definitions.
param: mixed  $script_module The script module id, if any.
return: bool Whether the call may proceed: the `wp_entity_fields_api_init` action

validate_entity( $method, $kind, $name )   X-Ref
Checks that the entity kind and name are non-empty strings, reporting
them with _doing_it_wrong() otherwise.

param: string $method The calling method, for the notice.
param: mixed  $kind   The entity kind.
param: mixed  $name   The entity name.
return: bool Whether both are valid.

skip_invalid_definitions( $method, $kind, $name, $fields )   X-Ref
Drops the definitions that are not an array with a non-empty string
`id`, reporting their positions in the call with _doing_it_wrong():
like a duplicated field, an invalid definition does not cost the call
its other fields.

param: string  $method The calling method, for the notice.
param: string  $kind   The entity kind.
param: string  $name   The entity name.
param: array[] $fields The list of field definitions.
return: array[] The valid definitions, in the order of the call.

skip_invalid_ids( $method, $kind, $name, $ids )   X-Ref
Drops the ids that are not a non-empty string, reporting their
positions in the call with _doing_it_wrong(): like an invalid
definition, an invalid id does not cost the call its other ids.

param: string $method The calling method, for the notice.
param: string $kind   The entity kind.
param: string $name   The entity name.
param: array  $ids    The ids of the fields.
return: string[] The valid ids, in the order of the call.

get_collection( $method, $directory )   X-Ref
Reads and validates a field collection, see register_collection() for
its format.

An invalid configuration is reported with _doing_it_wrong(): the
collection is skipped.

param: string $method    The calling method, for the notice.
param: string $directory The directory of the collection.
return: array|null The configuration of the collection, with the `module`

read_collection_fields( $method, $directory )   X-Ref
Reads the fields of a field collection, see get_collection_fields().

The id of a field is used as a key, so it is checked before: a
`field.php` that does not return an array with a non-empty string id
is reported with _doing_it_wrong() and skipped, and so is one whose
id an earlier folder of the collection took. The rest of the fields
are read.

param: string $method    The calling method, for the notice.
param: string $directory The directory of the collection.
return: array {

require_file( $file )   X-Ref
Requires a file without sharing the variables of the caller: this is
about variable scope.

param: string $file The path of the file.
return: mixed The return value of the file.

add_field_module( $kind, $name, $ids, $script_module )   X-Ref
Applies a script module to fields of an entity, after the fields it
already applies to.

param: string      $kind          The entity kind.
param: string      $name          The entity name.
param: string[]    $ids           The ids of the fields.
param: string|null $script_module The id of the script module, if any.

forget_empty_entity( $kind, $name )   X-Ref
Forgets an entity left without fields or script modules, and its kind
once no entity of the kind is left, so the registry only lists
entities that have some.

param: string $kind The entity kind.
param: string $name The entity name.


Generated : Tue Oct 20 08:20:34 2026 Cross-referenced by PHPXref