[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WP_View_Config_Data class
   4   *
   5   * @package WordPress
   6   * @since 7.1.0
   7   */
   8  
   9  /**
  10   * Holds an entity's view configuration while it is being built.
  11   *
  12   * An instance of this class is what `get_entity_view_config_{$kind}_{$name}`
  13   * filter callbacks receive: a callback changes the configuration by calling
  14   * methods on the instance and returning it. The configuration has four
  15   * top-level keys — `default_view`, `default_layouts`, `view_list`, and
  16   * `form` — and there are three ways to contribute. They form a gradient of how
  17   * deep the replacement reaches:
  18   *
  19   * - The `merge()` method merges partial changes (patches) into what is already
  20   *   there: `default_view`, `default_layouts`, and the `form` settings by key,
  21   *   and the `view_list` entries by view `slug` identity. This is what plugins
  22   *   should use: patches compose with core's configuration and with other
  23   *   plugins'.
  24   * - `replace()` applies a patch the same way `merge()` does, with one
  25   *   difference: a list in the patch replaces the current list wholesale
  26   *   instead of merging into it by member identity. It shouldn't be the
  27   *   default choice — a callback that replaces a list stops inheriting core's
  28   *   future additions to it — but it's useful when a contributor needs to pin
  29   *   a list to an exact set of members.
  30   * - `set()` goes one step further: it replaces each top-level key the patch
  31   *   names wholesale, dropping whatever that key held instead of merging into
  32   *   it. It's for a callback that owns a key outright and wants to pin it to an
  33   *   exact shape without the inherited default leaking through a key-by-key
  34   *   merge.
  35   *
  36   * All three touch only the top-level keys the patch names — an omitted key
  37   * keeps whatever it had, and a top-level `null` value drops the key it names,
  38   * which resets it to its default. They differ only in how deep the replacement
  39   * reaches once a key is named: `merge()` and `replace()` merge the value in
  40   * key by key (an associative array merges member by member, a nested `null`
  41   * deletes just that leaf, a scalar replaces just that value), while `set()`
  42   * swaps the whole value. A nested `null` deletes just the leaf it names in
  43   * every case. A patch value whose shape does not match the current value —
  44   * an associative array where a list lives, or the reverse — is rejected with
  45   * a notice rather than merged, and an empty array under `merge()` is a
  46   * no-op. Each patch also declares the configuration schema
  47   * version it was written against (currently 1), so a future WordPress release
  48   * that changes the configuration shape can migrate existing patches forward
  49   * instead of breaking them.
  50   *
  51   * Where those three write values, `remove()` deletes them: it takes a spec of
  52   * names — a list to delete entries at a level, or a nested map to reach deeper —
  53   * and prunes just what it names, mirroring the configuration's shape all the way
  54   * down to individual list members.
  55   *
  56   * @since 7.1.0
  57   */
  58  class WP_View_Config_Data {
  59  
  60      /**
  61       * The latest supported configuration schema version.
  62       *
  63       * @since 7.1.0
  64       * @var int
  65       */
  66      const LATEST_VERSION = 1;
  67  
  68      /**
  69       * The documented top-level configuration keys.
  70       *
  71       * @since 7.1.0
  72       * @var string[]
  73       */
  74      const CONFIG_KEYS = array( 'default_view', 'default_layouts', 'view_list', 'form' );
  75  
  76      /**
  77       * The configuration being contributed to.
  78       *
  79       * @since 7.1.0
  80       * @var array
  81       */
  82      private $config;
  83  
  84      /**
  85       * The default configuration.
  86       *
  87       * @since 7.1.0
  88       * @var array
  89       */
  90      private $defaults;
  91  
  92      /**
  93       * Constructor.
  94       *
  95       * @since 7.1.0
  96       *
  97       * @param array $config The base configuration to contribute to.
  98       */
  99  	public function __construct( array $config ) {
 100          $this->config   = $config;
 101          $this->defaults = $config;
 102      }
 103  
 104      /**
 105       * Returns the current configuration array.
 106       *
 107       * Deliberately private: filter callbacks receive the container, not the
 108       * materialized configuration, so they cannot read the built result and
 109       * become coupled to a specific configuration shape or schema version. Only
 110       * the class itself reconciles the container back into an array.
 111       *
 112       * @since 7.1.0
 113       *
 114       * @return array The configuration.
 115       */
 116  	private function get_data() {
 117          return $this->config;
 118      }
 119  
 120      /**
 121       * Applies the entity view configuration filter and returns the result.
 122       *
 123       * Exposes the container through the dynamic
 124       * `get_entity_view_config_{$kind}_{$name}` filter (with the dynamic portions
 125       * lowercased), so that core and third parties can provide the configuration for a specific entity,
 126       * then reconciles the filtered container back into a plain configuration array,
 127       * limited to the documented configuration keys.
 128       *
 129       * @since 7.1.0
 130       *
 131       * @param string $kind The entity kind (e.g. `postType`).
 132       * @param string $name The entity name (e.g. `page`).
 133       * @return array The filtered configuration, limited to the documented keys.
 134       */
 135  	public function apply_filters( $kind, $name ) {
 136          /**
 137           * Filters the view configuration for a given entity.
 138           *
 139           * The dynamic portions of the hook name, `$kind` and `$name`, refer to the
 140           * entity kind (e.g. `postType`) and the entity name (e.g. `page`),
 141           * lowercased — so the `postType`/`page` entity maps to the
 142           * `get_entity_view_config_posttype_page` hook.
 143           *
 144           * Callbacks receive a WP_View_Config_Data object and change the
 145           * configuration through its methods. Each write method takes the schema
 146           * version the change was authored against as its second argument,
 147           * and returns the object for chaining:
 148           *
 149           * - `merge( $patch, $version )` merges a partial change into the current
 150           *   configuration. It touches only the top-level keys the patch names, and
 151           *   merges each named value into the current one by shape: a scalar
 152           *   replaces, an associative array merges key by key, and a list merges by
 153           *   member identity (`id`, `slug`, or `field`). A `null` value drops the
 154           *   key it names, resetting it to its default.
 155           * - `replace( $patch, $version )` applies a patch exactly like `merge()`,
 156           *   but swaps any list it names wholesale instead of merging that list by
 157           *   member identity.
 158           * - `set( $patch, $version )` also touches only the keys the patch names,
 159           *   but swaps each named value in wholesale, dropping whatever the key held
 160           *   before — for a callback that owns those keys outright.
 161           * - `remove( $spec, $version )` deletes named properties. The spec mirrors
 162           *   the configuration shape: a list of names deletes entries at that level,
 163           *   and a nested map recurses to prune from within a named value, down to
 164           *   individual list members.
 165           *
 166           * A change that declares an unsupported schema version is rejected and does
 167           * not alter anything. As with any filter, each callback's return value is
 168           * passed to the next callback as `$data`, so callbacks must return the
 169           * container they received: a callback that returns nothing, or any other
 170           * value, hands that result to every callback hooked at a later priority
 171           * instead of the container. Since the write methods return the container,
 172           * a callback can end with `return $data->merge( $patch, $version );`.
 173           *
 174           * @since 7.1.0
 175           *
 176           * @param WP_View_Config_Data $data   The view configuration container
 177           *                                    for the entity, exposing the
 178           *                                    `default_view`, `default_layouts`,
 179           *                                    `view_list`, and `form` keys.
 180           * @param array               $entity {
 181           *     The entity the configuration is built for.
 182           *
 183           *     @type string $kind The entity kind.
 184           *     @type string $name The entity name.
 185           * }
 186           */
 187          apply_filters(
 188              wp_get_entity_view_config_hook_name( $kind, $name ),
 189              $this,
 190              array(
 191                  'kind' => $kind,
 192                  'name' => $name,
 193              )
 194          );
 195  
 196          // Discard any keys the filter introduced that are not part of the
 197          // documented configuration shape.
 198          return array_intersect_key( $this->get_data(), array_flip( self::CONFIG_KEYS ) );
 199      }
 200  
 201      /**
 202       * Replaces whole top-level keys, leaving the rest of the configuration alone.
 203       *
 204       * Like merge() and replace(), set() applies a patch of top-level keys and
 205       * touches only the keys the patch names: a key the patch omits keeps whatever
 206       * it had, and a `null` value drops the key it names (which resets it to its
 207       * default). The difference is depth — where merge() and replace() merge a
 208       * named key's value into the current one key by key, set() swaps the whole
 209       * value in wholesale, dropping whatever the key held before. A `null` nested
 210       * within that value still drops the property it names, so set() honours
 211       * nulls at every depth just as merge() and replace() do.
 212       *
 213       * Use it when a callback owns a key outright and wants to pin it to an exact
 214       * shape, without the inherited default leaking through a key-by-key merge.
 215       *
 216       * A patch that declares an unsupported schema version is rejected and does
 217       * not change anything.
 218       *
 219       * @since 7.1.0
 220       *
 221       * @param array $patch   The partial configuration whose named keys to replace.
 222       * @param int   $version The schema version the patch was authored against.
 223       * @return WP_View_Config_Data The instance, for chaining.
 224       */
 225  	public function set( array $patch, int $version ) {
 226          return $this->apply( $patch, $version, __METHOD__, 'set' );
 227      }
 228  
 229      /**
 230       * Removes named properties from the configuration, leaving the rest alone.
 231       *
 232       * Where merge(), replace(), and set() take a patch of *values* to write,
 233       * remove() takes a spec of *names* to delete, and its shape mirrors the
 234       * configuration it prunes:
 235       *
 236       * - A list of names deletes each named entry from the value at that level: a
 237       *   key from an associative array, or the member with a matching identity
 238       *   (`id`, `slug`, `field`, or a bare scalar) from a list.
 239       * - An associative array maps a name to a nested spec, recursing into that
 240       *   entry's value to delete from within it.
 241       *
 242       * Naming a top-level configuration key is the one exception: like a `null`
 243       * value in a patch, it resets that key to its default rather than dropping it
 244       * outright, so top-level removal and top-level `null` compose the same way.
 245       *
 246       * So `array( 'default_view' )` resets the whole `default_view` key to its
 247       * default, `array( 'default_view' => array( 'sort' ) )` drops just its `sort`
 248       * property, and `array( 'default_view' => array( 'fields' => array( 'f2' ) ) )`
 249       * drops the `f2` member from its `fields` list. A name that is not present is
 250       * ignored, and a list is renumbered after a member is removed.
 251       *
 252       * A spec that declares an unsupported schema version is rejected and does not
 253       * change anything.
 254       *
 255       * @since 7.1.0
 256       *
 257       * @param array $spec    The names to remove, keyed to match the configuration shape.
 258       * @param int   $version The schema version the spec was authored against.
 259       * @return WP_View_Config_Data The instance, for chaining.
 260       */
 261  	public function remove( array $spec, int $version ) {
 262          if ( $version <= 0 || $version > self::LATEST_VERSION ) {
 263              _doing_it_wrong(
 264                  __METHOD__,
 265                  esc_html__( 'A view configuration patch must declare a supported schema version.' ),
 266                  '7.1.0'
 267              );
 268  
 269              return $this;
 270          }
 271  
 272          // A flat list names top-level keys to reset; a map recurses into each
 273          // named key to prune from within its value.
 274          $spec_is_list = array_is_list( $spec );
 275          foreach ( $spec as $spec_key => $spec_value ) {
 276              $key = $spec_is_list ? $spec_value : $spec_key;
 277  
 278              if ( ! in_array( $key, self::CONFIG_KEYS, true ) ) {
 279                  _doing_it_wrong(
 280                      __METHOD__,
 281                      sprintf(
 282                          /* translators: %s: the configuration key. */
 283                          esc_html__( '"%s" is not a documented view configuration key.' ),
 284                          esc_html( $key )
 285                      ),
 286                      '7.1.0'
 287                  );
 288                  continue;
 289              }
 290  
 291              if ( $spec_is_list ) {
 292                  // Removing a top-level key resets it to its default, just as a
 293                  // null patch value does.
 294                  $this->config[ $key ] = $this->defaults[ $key ] ?? array();
 295              } elseif ( array_key_exists( $key, $this->config ) ) {
 296                  $this->config[ $key ] = $this->remove_properties( $this->config[ $key ], $spec_value );
 297              }
 298          }
 299  
 300          return $this;
 301      }
 302  
 303      /**
 304       * Replaces list values while merging the rest of a partial configuration.
 305       *
 306       * Takes the same arguments as merge() and applies the patch the same way,
 307       * with one difference: a list in the patch replaces the current list
 308       * wholesale instead of merging into it by member identity. Associative
 309       * arrays still merge key by key, `null` still drops what it names, and a
 310       * scalar still replaces the current value.
 311       *
 312       * It shouldn't be the default choice — a callback that replaces a list
 313       * stops inheriting core's future additions to it — but it's useful when a
 314       * contributor needs to pin a list to an exact set of members.
 315       *
 316       * The shape rule applies here too: a patch value whose shape does not match
 317       * the current value — an associative array where a list lives, or a
 318       * non-empty list where an associative value lives — is rejected with a
 319       * notice and leaves the current value unchanged. An empty array is exempt,
 320       * so replacing a list with an empty list still clears it.
 321       *
 322       * A patch that declares an unsupported schema version is rejected and does
 323       * not change anything.
 324       *
 325       * @since 7.1.0
 326       *
 327       * @param array $patch   The partial configuration to apply.
 328       * @param int   $version The schema version the patch was authored against.
 329       * @return WP_View_Config_Data The instance, for chaining.
 330       */
 331  	public function replace( array $patch, int $version ) {
 332          return $this->apply( $patch, $version, __METHOD__, 'replace' );
 333      }
 334  
 335      /**
 336       * Merges a partial configuration into the existing one.
 337       *
 338       * Applies a patch of top-level keys and touches only the keys the patch
 339       * names: a key the patch omits keeps whatever it had, and a `null` value
 340       * drops the key it names (which resets it to its default). Each named key's
 341       * value is then merged into the current one by value shape:
 342       *
 343       * - a scalar replaces the current value;
 344       * - an associative array merges key by key, with a nested `null` deleting
 345       *   just the leaf it names;
 346       * - a list merges into the current list by member identity.
 347       *
 348       * Identity is the member's value cast to a string: a bare scalar is its own
 349       * identity, and a map is identified by the value of the first of the
 350       * well-known identity keys (`id`, `slug`, `field`) it carries. A member
 351       * whose identity matches one already present merges into it in place, keeping
 352       * its position; a member with no identity is appended to the end of the list.
 353       *
 354       * For example, given this patch:
 355       *
 356       * ```php
 357       * array(
 358       *   'default_view' => array( 'titleField' => 'newTitleField', 'fields' => array( 'newField' ) ),
 359       *   'default_layouts' => array( 'grid' => array( 'layout' => array( 'badgeFields' => array( 'newField' ) ) ) ),
 360       *   'view_list' => array( array( 'slug' => 'table', 'title' => 'New title' ) ),
 361       * )
 362       * ```
 363       *
 364       * - default_view will be updated so the titleField is 'newTitleField' and the newField is appended to the list of fields.
 365       * - default_layouts will be updated so that newField is appended to the badgeFields.
 366       * - view_list will be updated so that the view with slug 'table' has its title changed to 'New title'.
 367       *
 368       * A patch value only merges into a current value of the same shape: an
 369       * associative array where a list lives, or a non-empty list where an
 370       * associative value lives, is rejected with a notice and leaves the current
 371       * value unchanged. An empty array merges nothing and is a no-op — clear a
 372       * list with replace() and an empty list, or reset a key to its default with
 373       * a top-level `null`.
 374       *
 375       * A patch that declares an unsupported schema version is rejected and does
 376       * not change anything.
 377       *
 378       * @since 7.1.0
 379       *
 380       * @param array $patch   The partial configuration to merge.
 381       * @param int   $version The schema version the patch was authored against.
 382       * @return WP_View_Config_Data The instance, for chaining.
 383       */
 384  	public function merge( array $patch, int $version ) {
 385          return $this->apply( $patch, $version, __METHOD__, 'merge' );
 386      }
 387  
 388      /**
 389       * Applies a patch to the configuration, top-level key by top-level key.
 390       *
 391       * Shared by merge(), replace(), and set(); the three differ only in how the
 392       * value of a named key is applied, which is carried by $mode:
 393       *
 394       * - `merge`   merges the value into the current one, lists by member identity;
 395       * - `replace` merges the value in the same way but swaps lists wholesale;
 396       * - `set`     swaps the whole value in wholesale, without merging.
 397       *
 398       * In every mode a top-level `null` resets the key it names to its default, a
 399       * nested `null` drops the property it names, and an omitted key is left
 400       * untouched, so all three treat nulls the same way at every depth.
 401       *
 402       * @since 7.1.0
 403       *
 404       * @param array  $patch   The partial configuration to apply.
 405       * @param int    $version The schema version the patch was authored against.
 406       * @param string $method  The public method the patch was passed to, for misuse reporting.
 407       * @param string $mode    How to apply each named key's value: `merge`, `replace`, or `set`.
 408       * @return WP_View_Config_Data The instance, for chaining.
 409       */
 410  	private function apply( array $patch, int $version, $method, $mode ) {
 411          if ( $version <= 0 || $version > self::LATEST_VERSION ) {
 412              _doing_it_wrong(
 413                  esc_html( $method ),
 414                  esc_html__( 'A view configuration patch must declare a supported schema version.' ),
 415                  '7.1.0'
 416              );
 417  
 418              return $this;
 419          }
 420  
 421          foreach ( $patch as $key => $value ) {
 422              if ( ! in_array( $key, self::CONFIG_KEYS, true ) ) {
 423                  _doing_it_wrong(
 424                      esc_html( $method ),
 425                      sprintf(
 426                          /* translators: %s: the configuration key. */
 427                          esc_html__( '"%s" is not a documented view configuration key.' ),
 428                          esc_html( $key )
 429                      ),
 430                      '7.1.0'
 431                  );
 432                  continue;
 433              }
 434  
 435              // A null patch value makes the top-level property reset to defaults.
 436              if ( null === $value ) {
 437                  $this->config[ $key ] = $this->defaults[ $key ] ?? array();
 438                  continue;
 439              }
 440  
 441              // set() swaps the whole value in; merge()/replace() merge it into the
 442              // current one, differing only in how they treat lists. In every mode a
 443              // nested null still drops the property it names.
 444              $this->config[ $key ] = 'set' === $mode
 445                  ? $this->strip_nulls( $value )
 446                  : $this->merge_properties( $this->config[ $key ] ?? array(), $value, 'replace' === $mode );
 447          }
 448  
 449          return $this;
 450      }
 451  
 452      /**
 453       * Recursively drops every property whose value is `null` from a value.
 454       *
 455       * set() swaps a named key's value in wholesale rather than merging it into
 456       * the current one, so it has no existing leaf for a nested `null` to delete
 457       * the way merge() and replace() do. Stripping nulls here gives a nested
 458       * `null` the same "drop the property it names" meaning under set() that it
 459       * carries everywhere else. The same applies to a list replace() swaps in
 460       * wholesale. A list is renumbered after a member is removed so removed
 461       * entries do not leave gaps.
 462       *
 463       * @since 7.1.0
 464       *
 465       * @param mixed $value The value to strip nulls from.
 466       * @return mixed The value with every `null` property removed, recursively.
 467       */
 468  	private function strip_nulls( $value ) {
 469          if ( ! is_array( $value ) ) {
 470              return $value;
 471          }
 472  
 473          $result = array();
 474          foreach ( $value as $key => $item ) {
 475              // A null value drops the property it names.
 476              if ( null === $item ) {
 477                  continue;
 478              }
 479  
 480              $result[ $key ] = $this->strip_nulls( $item );
 481          }
 482  
 483          // Renumber a list so a removed member does not leave a gap.
 484          return array_is_list( $value ) ? array_values( $result ) : $result;
 485      }
 486  
 487      /**
 488       * Merges an incoming value into the current one, recursing by value shape.
 489       *
 490       * This is the core of the merge algorithm and is applied at every nesting
 491       * level: a scalar (or `null`) in $incoming replaces $current outright, an
 492       * associative array merges key by key (recursing here for each key, with a
 493       * `null` value deleting that key), and a list either replaces $current
 494       * wholesale ($replace_lists) or merges into it by member identity. The
 495       * $replace_lists flag is carried down through associative nesting so that,
 496       * under replace(), every list reached along the way is swapped wholesale.
 497       *
 498       * An array in $incoming only merges into a current value of the same shape.
 499       * A non-empty mismatch — an associative array where a list lives, or a
 500       * non-empty list where an associative value lives — is reported with
 501       * _doing_it_wrong() and leaves the current value unchanged, so a malformed
 502       * patch cannot silently destroy configuration. An empty array is
 503       * shape-ambiguous and merges nothing, so it is a no-op: clearing a list is
 504       * spelled replace() with an empty list, and resetting a key is spelled
 505       * `null`.
 506       *
 507       * @since 7.1.0
 508       *
 509       * @param mixed $current       The current value.
 510       * @param mixed $incoming      The incoming value.
 511       * @param bool  $replace_lists Whether a list in $incoming replaces the current list
 512       *                             wholesale instead of merging into it by member identity.
 513       * @return mixed The merged value.
 514       */
 515  	private function merge_properties( $current, $incoming, $replace_lists ) {
 516          // Scalar properties are merged as-is.
 517          if ( ! is_array( $incoming ) ) {
 518              return $incoming;
 519          }
 520  
 521          // Numerical indexed arrays are expected to be lists (sequential integer keys starting at 0).
 522          if ( array_is_list( $incoming ) ) {
 523              // A non-empty list only lands where a list (or nothing) lives, under
 524              // merge() and replace() alike. An empty array is shape-ambiguous and
 525              // exempt, so replace() with an empty list can still clear a list.
 526              if ( array() !== $incoming && is_array( $current ) && ! array_is_list( $current ) && array() !== $current ) {
 527                  _doing_it_wrong(
 528                      __METHOD__,
 529                      esc_html__( 'A view configuration patch value must match the shape of the value it patches: a list merges into a list, and an associative array into an associative array.' ),
 530                      '7.1.0'
 531                  );
 532                  return $current;
 533              }
 534  
 535              // replace() takes an incoming list as-is; merge() merges it by member identity.
 536              if ( $replace_lists ) {
 537                  // As-is except for nulls: a list swapped in wholesale has no
 538                  // existing leaf for a null to delete (the same rationale as
 539                  // set()), so a null member is dropped rather than stored.
 540                  return $this->strip_nulls( $incoming );
 541              }
 542  
 543              // An empty list has no members to merge, and an empty array is
 544              // shape-ambiguous, so merging one is a no-op rather than a reset.
 545              if ( array() === $incoming ) {
 546                  return $current;
 547              }
 548  
 549              return $this->merge_list_by_identity(
 550                  is_array( $current ) && array_is_list( $current ) ? $current : array(),
 551                  $incoming
 552              );
 553          }
 554  
 555          // Consider any other array as associative (keys are strings).
 556          if ( is_array( $current ) && array_is_list( $current ) && array() !== $current ) {
 557              _doing_it_wrong(
 558                  __METHOD__,
 559                  esc_html__( 'A view configuration patch value must match the shape of the value it patches: a list merges into a list, and an associative array into an associative array.' ),
 560                  '7.1.0'
 561              );
 562              return $current;
 563          }
 564  
 565          $result = is_array( $current ) && ! array_is_list( $current ) ? $current : array();
 566          foreach ( $incoming as $key => $value ) {
 567              // A null patch value deletes the property.
 568              if ( null === $value ) {
 569                  unset( $result[ $key ] );
 570                  continue;
 571              }
 572  
 573              $result[ $key ] = $this->merge_properties(
 574                  array_key_exists( $key, $result ) ? $result[ $key ] : array(),
 575                  $value,
 576                  $replace_lists
 577              );
 578          }
 579  
 580          return $result;
 581      }
 582  
 583      /**
 584       * Removes the properties a spec names from the current value.
 585       *
 586       * The mirror of merge_properties(), applied at every nesting level: a list in
 587       * $spec names entries to delete from $current — associative keys are unset,
 588       * and list members are matched by identity (list_item_identity) and dropped —
 589       * while an associative $spec recurses into each named entry to prune from
 590       * within it. A name absent from $current is ignored, and a list is renumbered
 591       * after members are removed so it keeps sequential keys.
 592       *
 593       * @since 7.1.0
 594       *
 595       * @param mixed $current The current value.
 596       * @param mixed $spec    The names to remove from it.
 597       * @return mixed The pruned value.
 598       */
 599  	private function remove_properties( $current, $spec ) {
 600          if ( ! is_array( $current ) || ! is_array( $spec ) ) {
 601              return $current;
 602          }
 603  
 604          $current_is_list = array_is_list( $current );
 605  
 606          if ( array_is_list( $spec ) ) {
 607              // Each entry names something to delete from the current value.
 608              foreach ( $spec as $name ) {
 609                  if ( $current_is_list ) {
 610                      $current = $this->remove_list_member( $current, $name );
 611                  } else {
 612                      unset( $current[ $name ] );
 613                  }
 614              }
 615          } else {
 616              // Each key names an entry to recurse into and prune from within.
 617              foreach ( $spec as $name => $subspec ) {
 618                  if ( $current_is_list ) {
 619                      foreach ( $current as $index => $member ) {
 620                          if ( $this->list_item_identity( $member ) === (string) $name ) {
 621                              $current[ $index ] = $this->remove_properties( $member, $subspec );
 622                              break;
 623                          }
 624                      }
 625                  } elseif ( array_key_exists( $name, $current ) ) {
 626                      $current[ $name ] = $this->remove_properties( $current[ $name ], $subspec );
 627                  }
 628              }
 629          }
 630  
 631          // Renumber so a list from which a member was removed keeps sequential keys.
 632          return $current_is_list ? array_values( $current ) : $current;
 633      }
 634  
 635      /**
 636       * Removes the first list member matching an identity, leaving the rest.
 637       *
 638       * @since 7.1.0
 639       *
 640       * @param array $members  The current list.
 641       * @param mixed $identity The identity of the member to remove.
 642       * @return array The list with the matching member removed, if any.
 643       */
 644  	private function remove_list_member( array $members, $identity ) {
 645          foreach ( $members as $index => $member ) {
 646              if ( $this->list_item_identity( $member ) === (string) $identity ) {
 647                  unset( $members[ $index ] );
 648                  break;
 649              }
 650          }
 651  
 652          return $members;
 653      }
 654  
 655      /**
 656       * Merges an incoming list into the current one by member identity.
 657       *
 658       * A member of the incoming list whose identity matches one already present
 659       * merges into it in place, keeping its position; an unmatched member is
 660       * appended to the end, except a literal `null`, which carries no identity
 661       * and holds nothing to merge and so is dropped. An appended member has no
 662       * existing leaf for a nested `null` to delete (the same rationale as set()),
 663       * so its nulls are stripped rather than stored. A matched member's contents
 664       * merge recursively with the same rules (merge_properties), so the
 665       * identity-aware merge applies at
 666       * any nesting level: each key named by the patch is substituted while the
 667       * others are left intact, and a list nested inside a member merges by
 668       * identity just like the list it lives in.
 669       *
 670       * @since 7.1.0
 671       *
 672       * @param array $current  The current list.
 673       * @param array $incoming The incoming list.
 674       * @return array The merged list.
 675       */
 676  	private function merge_list_by_identity( array $current, array $incoming ) {
 677          $result = $current;
 678          foreach ( $incoming as $item ) {
 679              // A null member carries no identity and holds nothing to merge,
 680              // so it is dropped rather than appended as a literal null.
 681              if ( null === $item ) {
 682                  continue;
 683              }
 684  
 685              $identity = $this->list_item_identity( $item );
 686  
 687              // Find the index of the existing member with the same identity, if any.
 688              // If there's none, append the incoming member to the end of the list.
 689              $index = null;
 690              if ( null !== $identity ) {
 691                  foreach ( $result as $i => $existing ) {
 692                      if ( $this->list_item_identity( $existing ) === $identity ) {
 693                          $index = $i;
 694                          break;
 695                      }
 696                  }
 697              }
 698              if ( null === $index ) {
 699                  // An appended member has no existing leaf for a nested null to
 700                  // delete, so nulls are dropped rather than stored.
 701                  $result[] = $this->strip_nulls( $item );
 702                  continue;
 703              }
 704  
 705              // Otherwise, merge the incoming member into the existing one in place.
 706              $result[ $index ] = $this->merge_properties( $result[ $index ], $item, false );
 707          }
 708  
 709          return $result;
 710      }
 711  
 712      /**
 713       * Resolves the identity used to match a list member against another.
 714       *
 715       * The identity is simply the member's value cast to a string, regardless of
 716       * which key carries it: a bare scalar is its own identity, and a map is
 717       * identified by the value of the first of the well-known identity keys
 718       * (`id`, `slug`, `field`) it carries. Because the key is not part of
 719       * the identity, a bare field like `'f3'` matches any map carrying that
 720       * value, whether it appears as `array( 'id' => 'f3' )`,
 721       * `array( 'slug' => 'f3' )`, and so on — this lets the same shorthand target
 722       * lists keyed by different fields. Casting to string keeps numeric
 723       * identities matching whether they arrive as an int or a string. Anything
 724       * else (e.g. a nested list) has no identity and never matches, so it is
 725       * always appended.
 726       *
 727       * @since 7.1.0
 728       *
 729       * @param mixed $item The list member.
 730       * @return string|null The identity, or null when the member has none.
 731       */
 732  	private function list_item_identity( $item ) {
 733          if ( is_scalar( $item ) ) {
 734              return (string) $item;
 735          }
 736  
 737          if ( is_array( $item ) && ! array_is_list( $item ) ) {
 738              foreach ( array( 'id', 'slug', 'field' ) as $key ) {
 739                  if ( isset( $item[ $key ] ) && is_scalar( $item[ $key ] ) ) {
 740                      return (string) $item[ $key ];
 741                  }
 742              }
 743          }
 744  
 745          return null;
 746      }
 747  }