[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Entity actions API.
   4   *
   5   * An action definition is the serializable subset of the DataViews Action
   6   * API: every property that is plain data (`id`, `label`, `isPrimary`,
   7   * `supportsBulk`, `context`, `modalHeader`, …). Properties that are
   8   * JavaScript callbacks, components, or elements (`callback`, `RenderModal`,
   9   * `isEligible`, `icon`, a `label` that depends on the items, …) cannot be
  10   * declared here. They are provided by a script module registered for the
  11   * entity along with its actions: its default export maps action ids to the
  12   * properties of each action that are JavaScript. An entity can have several
  13   * modules. Each module applies to the actions it was registered with, see
  14   * {@see wp_get_registered_entity_action_modules()}.
  15   *
  16   * Actions are registered on the `wp_entity_actions_api_init` action, and only there,
  17   * with {@see wp_register_entity_actions()} and {@see wp_unregister_entity_actions()}. The
  18   * other functions read the registry. WordPress core registers its own
  19   * actions the same way, from packages/core-actions.
  20   *
  21   * @package WordPress
  22   * @subpackage Entity Actions
  23   * @since 7.2.0
  24   */
  25  
  26  /**
  27   * Registers actions for an entity, see
  28   * {@see WP_Entity_Actions_Registry::register()}.
  29   *
  30   * It only runs on the `wp_entity_actions_api_init` action.
  31   *
  32   * @since 7.2.0
  33   *
  34   * @param string      $origin        Who registers the actions: `core`, or
  35   *                                   the slug of the plugin or theme.
  36   * @param string      $kind          The entity kind (e.g. `postType`).
  37   * @param string      $name          The entity name (e.g. `page`).
  38   * @param array[]     $actions       The list of action definitions, each with an `id`.
  39   * @param string|null $script_module The id of the script module providing
  40   *                                   the JavaScript parts of the actions, if any.
  41   * @return string[] The ids of the actions registered, in the order of the
  42   *                  call. Empty when none is.
  43   */
  44  function wp_register_entity_actions( $origin, $kind, $name, $actions, $script_module = null ) {
  45      return WP_Entity_Actions_Registry::get_instance()->register( $origin, $kind, $name, $actions, $script_module );
  46  }
  47  
  48  /**
  49   * Unregisters actions of an entity, see
  50   * {@see WP_Entity_Actions_Registry::unregister()}.
  51   *
  52   * It only runs on the `wp_entity_actions_api_init` action.
  53   *
  54   * @since 7.2.0
  55   *
  56   * @param string        $kind The entity kind (e.g. `postType`).
  57   * @param string        $name The entity name (e.g. `page`).
  58   * @param string[]|null $ids  The ids of the actions to unregister. Default
  59   *                            null, every action of the entity.
  60   * @return array[] The list of the definitions unregistered, in
  61   *                 registration order. Empty when none is.
  62   */
  63  function wp_unregister_entity_actions( $kind, $name, $ids = null ) {
  64      return WP_Entity_Actions_Registry::get_instance()->unregister( $kind, $name, $ids );
  65  }
  66  
  67  /**
  68   * Returns the actions registered for the given entity.
  69   *
  70   * @since 7.2.0
  71   *
  72   * @param string $kind The entity kind (e.g. `postType`).
  73   * @param string $name The entity name (e.g. `page`).
  74   * @return array[] The list of registered action definitions, in
  75   *                 registration order. Empty until the `init` action has
  76   *                 completed: a read before then is refused.
  77   */
  78  function wp_get_registered_entity_actions( $kind, $name ) {
  79      return WP_Entity_Actions_Registry::get_instance()->get_registered( $kind, $name );
  80  }
  81  
  82  /**
  83   * Returns the ids of the script modules registered for the given entity.
  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   * @return array<string, string[]> The ids of the actions each module
  90   *                                 applies to, keyed by module id, in
  91   *                                 registration order. Empty until the
  92   *                                 `init` action has completed: a read
  93   *                                 before then is refused.
  94   */
  95  function wp_get_registered_entity_action_modules( $kind, $name ) {
  96      return WP_Entity_Actions_Registry::get_instance()->get_registered_action_modules( $kind, $name );
  97  }
  98  
  99  /**
 100   * Returns the ids of all script modules registered for any entity.
 101   *
 102   * @since 7.2.0
 103   *
 104   * @return array<string, array<string, string[]>> The lists of module ids,
 105   *                                                keyed by kind, then by
 106   *                                                name. Empty until the
 107   *                                                `init` action has
 108   *                                                completed: a read before
 109   *                                                then is refused.
 110   */
 111  function wp_get_all_registered_entity_action_modules() {
 112      return WP_Entity_Actions_Registry::get_instance()->get_all_registered_action_modules();
 113  }
 114  
 115  /**
 116   * Declares the script modules of the entity actions as dependencies of the
 117   * editor script.
 118   *
 119   * The editor imports the script modules of an entity on demand, with a dynamic
 120   * `import()` the browser resolves through the import map of the page. Listing
 121   * the modules as dynamic `module_dependencies` of the `wp-editor` script adds
 122   * them to the import map of every page that loads the editor script: the post
 123   * editor, the site editor, and the pages booted by `@wordpress/boot`, whose
 124   * prerequisites depend on it. A dynamic dependency is only listed in the
 125   * import map; the module is fetched when it is imported.
 126   *
 127   * Reading the registry fires `wp_entity_actions_api_init`, so the actions and their
 128   * script modules are registered on demand. It only reads the registry on the
 129   * pages that load the editor script, not on every admin request (heartbeat,
 130   * Ajax, other screens). It runs on `admin_footer`, the last action before the
 131   * import map is printed that fires both in the admin template and in the pages
 132   * rendered outside it, which print the import map themselves. By then `init`
 133   * has completed, so the post types and supports the actions derive from are
 134   * final.
 135   * The registry only accepts registrations while the action fires, so the
 136   * modules declared here are the modules of every action the page can show.
 137   *
 138   * The `admin_footer` action passes it no argument, so the global registry is
 139   * used. In other scenarios (tests), the scripts are given directly.
 140   *
 141   * @since 7.2.0
 142   *
 143   * @param WP_Scripts|null $scripts The scripts registry. Defaults to the global one.
 144   */
 145  function _wp_add_entity_action_modules_to_editor_script( $scripts = null ) {
 146      if ( ! $scripts instanceof WP_Scripts ) {
 147          $scripts = wp_scripts();
 148      }
 149  
 150      // The actions are loaded by `usePostActions()` of the editor script, so
 151      // every screen showing them loads it.
 152      if ( ! $scripts->query( 'wp-editor', 'enqueued' ) && ! $scripts->query( 'wp-editor', 'done' ) ) {
 153          return;
 154      }
 155  
 156      $kinds = wp_get_all_registered_entity_action_modules();
 157      if ( empty( $kinds ) ) {
 158          return;
 159      }
 160  
 161      $dependencies = $scripts->get_data( 'wp-editor', 'module_dependencies' );
 162      $dependencies = is_array( $dependencies ) ? $dependencies : array();
 163  
 164      $declared = array();
 165      foreach ( $dependencies as $dependency ) {
 166          $declared[] = is_array( $dependency ) ? $dependency['id'] : $dependency;
 167      }
 168  
 169      $added = false;
 170      foreach ( $kinds as $entities ) {
 171          foreach ( $entities as $modules ) {
 172              foreach ( $modules as $module ) {
 173                  if ( ! in_array( $module, $declared, true ) ) {
 174                      $dependencies[] = array(
 175                          'id'     => $module,
 176                          'import' => 'dynamic',
 177                      );
 178                      $declared[]     = $module;
 179                      $added          = true;
 180                  }
 181              }
 182          }
 183      }
 184  
 185      if ( $added ) {
 186          // `add_data()` replaces the value, hence the merge above.
 187          $scripts->add_data( 'wp-editor', 'module_dependencies', $dependencies );
 188      }
 189  }
 190  
 191  /**
 192   * Preloads the actions of the post type the post editor edits.
 193   *
 194   * The actions menu of the post editor reads them from the `wp/v2/entity-actions`
 195   * route as it loads, see `useEntityActions()` in
 196   * packages/editor/src/dataviews/entity-actions-loader.ts. The path must match the
 197   * request of the `getEntityActionsConfig` core data resolver, see
 198   * packages/core-data/src/resolvers.js.
 199   *
 200   * @since 7.2.0
 201   *
 202   * @param array                   $paths   REST API paths to preload.
 203   * @param WP_Block_Editor_Context $context Block editor context.
 204   * @return array Filtered preload paths.
 205   */
 206  function _wp_preload_entity_actions( $paths, $context ) {
 207      if ( 'core/edit-post' === $context->name && isset( $context->post ) ) {
 208          $paths[] = add_query_arg(
 209              array(
 210                  'kind' => 'postType',
 211                  'name' => $context->post->post_type,
 212              ),
 213              '/wp/v2/entity-actions'
 214          );
 215      }
 216  
 217      return $paths;
 218  }