[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Entity Fields API.
   4   *
   5   * A field definition is the serializable subset of the DataViews Field API:
   6   * every property that is plain data (`id`, `type`, `label`, `elements`,
   7   * `filterBy`, `isValid`, …). Properties that are JavaScript callbacks or
   8   * components (`render`, `Edit` as a component, `getValue`, `setValue`, `sort`,
   9   * `isVisible`, `getElements`, …) cannot be declared here. They are provided by
  10   * a script module registered for the entity along with its fields: its default
  11   * export maps field ids to the properties of each field that are JavaScript. An
  12   * entity can have several modules. Each module applies to the fields it was
  13   * registered with, see {@see wp_get_registered_entity_field_modules()}.
  14   *
  15   * Fields are registered on the `wp_entity_fields_api_init` action, and only there,
  16   * with {@see wp_register_entity_fields()}, {@see wp_update_entity_fields()}, and
  17   * {@see wp_unregister_entity_fields()}. The other functions read the registry.
  18   *
  19   * Fields can also be declared as files, grouped in a field collection, which
  20   * a `wp_entity_fields_api_init` callback registers with
  21   * {@see wp_register_entity_field_collection()}. A collection is for a single
  22   * entity. WordPress core registers its own fields this way, from
  23   * packages/core-fields: the defaults every post type derives from its
  24   * supports in code, the fields of single post types as collections.
  25   *
  26   * The registered fields are exposed by the `/wp/v2/entity-fields` REST API
  27   * route, see {@see WP_REST_Entity_Fields_Controller}.
  28   *
  29   * @package WordPress
  30   * @subpackage Entity Fields API
  31   * @since 7.2.0
  32   */
  33  
  34  /**
  35   * Registers fields for an entity, see
  36   * {@see WP_Entity_Fields_Registry::register()}.
  37   *
  38   * It only runs on the `wp_entity_fields_api_init` action.
  39   *
  40   * @since 7.2.0
  41   *
  42   * @param string      $origin        Who registers the fields: `core`, or
  43   *                                   the slug of the plugin or theme.
  44   * @param string      $kind          The entity kind (e.g. `postType`).
  45   * @param string      $name          The entity name (e.g. `page`).
  46   * @param array[]     $fields        The list of field definitions, each with an `id`.
  47   * @param string|null $script_module The id of the script module providing
  48   *                                   the JavaScript parts of the fields, if any.
  49   * @return string[] The ids of the fields registered, in the order of the
  50   *                  call. Empty when none is.
  51   */
  52  function wp_register_entity_fields( $origin, $kind, $name, $fields, $script_module = null ) {
  53      return WP_Entity_Fields_Registry::get_instance()->register( $origin, $kind, $name, $fields, $script_module );
  54  }
  55  
  56  /**
  57   * Updates registered fields of an entity, see
  58   * {@see WP_Entity_Fields_Registry::update()}.
  59   *
  60   * It only runs on the `wp_entity_fields_api_init` action.
  61   *
  62   * @since 7.2.0
  63   *
  64   * @param string      $origin        Who updates the fields: `core`, or
  65   *                                   the slug of the plugin or theme.
  66   * @param string      $kind          The entity kind (e.g. `postType`).
  67   * @param string      $name          The entity name (e.g. `page`).
  68   * @param array[]     $fields        The list of partial field definitions,
  69   *                                   each with the `id` of a registered field.
  70   * @param string|null $script_module The id of the script module providing
  71   *                                   the JavaScript parts of the fields, if any.
  72   * @return string[] The ids of the fields updated, in the order of the
  73   *                  call. Empty when none is.
  74   */
  75  function wp_update_entity_fields( $origin, $kind, $name, $fields, $script_module = null ) {
  76      return WP_Entity_Fields_Registry::get_instance()->update( $origin, $kind, $name, $fields, $script_module );
  77  }
  78  
  79  /**
  80   * Unregisters fields of an entity, see
  81   * {@see WP_Entity_Fields_Registry::unregister()}.
  82   *
  83   * It only runs on the `wp_entity_fields_api_init` action.
  84   *
  85   * @since 7.2.0
  86   *
  87   * @param string        $kind The entity kind (e.g. `postType`).
  88   * @param string        $name The entity name (e.g. `page`).
  89   * @param string[]|null $ids  The ids of the fields to unregister. Default
  90   *                            null, every field of the entity.
  91   * @return array[] The list of the definitions unregistered, in
  92   *                 registration order. Empty when none is.
  93   */
  94  function wp_unregister_entity_fields( $kind, $name, $ids = null ) {
  95      return WP_Entity_Fields_Registry::get_instance()->unregister( $kind, $name, $ids );
  96  }
  97  
  98  /**
  99   * Returns the fields registered for the given entity.
 100   *
 101   * @since 7.2.0
 102   *
 103   * @param string $kind The entity kind (e.g. `postType`).
 104   * @param string $name The entity name (e.g. `page`).
 105   * @return array[] The list of registered field definitions, in registration
 106   *                 order. Empty until the `init` action has completed: a
 107   *                 read before then is refused.
 108   */
 109  function wp_get_registered_entity_fields( $kind, $name ) {
 110      return WP_Entity_Fields_Registry::get_instance()->get_registered( $kind, $name );
 111  }
 112  
 113  /**
 114   * Returns the script modules registered for the given entity.
 115   *
 116   * @since 7.2.0
 117   *
 118   * @param string $kind The entity kind (e.g. `postType`).
 119   * @param string $name The entity name (e.g. `page`).
 120   * @return array[] {
 121   *     The script modules, in registration order. Empty until the `init`
 122   *     action has completed: a read before then is refused.
 123   *
 124   *     @type array ...$0 {
 125   *         @type string   $id     The id of the script module.
 126   *         @type string[] $fields The ids of the fields the module applies to,
 127   *                                in registration order.
 128   *     }
 129   * }
 130   */
 131  function wp_get_registered_entity_field_modules( $kind, $name ) {
 132      return WP_Entity_Fields_Registry::get_instance()->get_registered_field_modules( $kind, $name );
 133  }
 134  
 135  /**
 136   * Returns the ids of all script modules registered for any entity.
 137   *
 138   * @since 7.2.0
 139   *
 140   * @return array<string, array<string, string[]>> The lists of module ids,
 141   *                                                keyed by kind, then by
 142   *                                                name. Empty until the
 143   *                                                `init` action has
 144   *                                                completed: a read before
 145   *                                                then is refused.
 146   */
 147  function wp_get_all_registered_entity_field_modules() {
 148      return WP_Entity_Fields_Registry::get_instance()->get_all_registered_field_modules();
 149  }
 150  
 151  /**
 152   * Declares the script modules of the entity fields as dependencies of the
 153   * editor script, see _wp_add_entity_modules_to_editor_script().
 154   *
 155   * The fields are loaded by the editor package, see
 156   * packages/editor/src/dataviews/store/private-resolvers.ts in Gutenberg, which
 157   * means any screen that wants to use this mechanism needs to load the editor
 158   * script.
 159   *
 160   * It is hooked to `admin_footer` without arguments, so the global scripts
 161   * registry is used. In other scenarios (tests), the scripts are given directly.
 162   *
 163   * @since 7.2.0
 164   * @access private
 165   *
 166   * @param WP_Scripts|null $scripts Optional. The scripts registry. Default null,
 167   *                                 the global one.
 168   */
 169  function _wp_add_entity_field_modules_to_editor_script( $scripts = null ) {
 170      _wp_add_entity_modules_to_editor_script( $scripts, 'wp_get_all_registered_entity_field_modules' );
 171  }
 172  
 173  /**
 174   * Returns the fields of a field collection, see
 175   * {@see WP_Entity_Fields_Registry::get_collection_fields()}.
 176   *
 177   * @since 7.2.0
 178   *
 179   * @param string $directory The directory of the collection.
 180   * @return array<string, array> The fields of the collection, keyed by id, in
 181   *                              the alphabetical order of their folders.
 182   */
 183  function wp_get_entity_field_collection_fields( $directory ) {
 184      return WP_Entity_Fields_Registry::get_instance()->get_collection_fields( $directory );
 185  }
 186  
 187  /**
 188   * Registers the fields of a field collection, see
 189   * {@see WP_Entity_Fields_Registry::register_collection()} for the format of a
 190   * collection.
 191   *
 192   * Like wp_register_entity_fields(), it only runs on the `wp_entity_fields_api_init`
 193   * action.
 194   *
 195   * @since 7.2.0
 196   *
 197   * @param string $directory The directory of the collection.
 198   * @return bool Whether the collection is valid and all of its fields are
 199   *              registered. True as well when it has no fields.
 200   */
 201  function wp_register_entity_field_collection( $directory ) {
 202      return WP_Entity_Fields_Registry::get_instance()->register_collection( $directory );
 203  }
 204  
 205  /**
 206   * Preloads the fields of the post types the editors list.
 207   *
 208   * The editors read them from the `/wp/v2/entity-fields` route, see `useFields`
 209   * in packages/editor/src/dataviews/fields-loader/index.ts in Gutenberg. The
 210   * post editor reads those of the edited post in the post summary of its
 211   * inspector. The site editor reads those of the edited post, if any, and of
 212   * the post types of the screen it opens on. A path must match the request of
 213   * the `getFieldsConfig` core data resolver, see
 214   * packages/core-data/src/resolvers.js in Gutenberg.
 215   *
 216   * @since 7.2.0
 217   * @access private
 218   *
 219   * @param mixed $paths   REST API paths to preload.
 220   * @param mixed $context Optional. Block editor context. Default null.
 221   * @return mixed Filtered preload paths. See _wp_add_entity_preload_paths().
 222   */
 223  function _wp_preload_entity_fields( $paths, $context = null ) {
 224      return _wp_add_entity_preload_paths( $paths, $context, '/wp/v2/entity-fields' );
 225  }