Title: WP_View_Config_Data::merge_list_by_identity
Published: August 20, 2026

---

# WP_View_Config_Data::merge_list_by_identity( array $current, array $incoming ): array

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#wp--skip-link--target)

This function’s access is marked private. This means it is not intended for use 
by plugin or theme developers, only by core. It is listed here for completeness.

Merges an incoming list into the current one by member identity.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#description)󠁿

A member of the incoming list whose identity matches one already present merges 
into it in place, keeping its position; an unmatched member is appended to the end,
except a literal `null`, which carries no identity and holds nothing to merge and
so is dropped. An appended member has no existing leaf for a nested `null` to delete(
the same rationale as set()), so its nulls are stripped rather than stored. A matched
member’s contents merge recursively with the same rules (merge_properties), so the
identity-aware merge applies at any nesting level: each key named by the patch is
substituted while the others are left intact, and a list nested inside a member 
merges by identity just like the list it lives in.

## 󠀁[Parameters](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#parameters)󠁿

 `$current`arrayrequired

The current list.

`$incoming`arrayrequired

The incoming list.

## 󠀁[Return](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#return)󠁿

 array The merged list.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#source)󠁿

    ```php
    private function merge_list_by_identity( array $current, array $incoming ) {
    	$result = $current;
    	foreach ( $incoming as $item ) {
    		// A null member carries no identity and holds nothing to merge,
    		// so it is dropped rather than appended as a literal null.
    		if ( null === $item ) {
    			continue;
    		}

    		$identity = $this->list_item_identity( $item );

    		// Find the index of the existing member with the same identity, if any.
    		// If there's none, append the incoming member to the end of the list.
    		$index = null;
    		if ( null !== $identity ) {
    			foreach ( $result as $i => $existing ) {
    				if ( $this->list_item_identity( $existing ) === $identity ) {
    					$index = $i;
    					break;
    				}
    			}
    		}
    		if ( null === $index ) {
    			// An appended member has no existing leaf for a nested null to
    			// delete, so nulls are dropped rather than stored.
    			$result[] = $this->strip_nulls( $item );
    			continue;
    		}

    		// Otherwise, merge the incoming member into the existing one in place.
    		$result[ $index ] = $this->merge_properties( $result[ $index ], $item, false );
    	}

    	return $result;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/class-wp-view-config-data.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/class-wp-view-config-data.php#L676)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/class-wp-view-config-data.php#L676-L710)

## 󠀁[Related](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#related)󠁿

| Uses | Description | 
| [WP_View_Config_Data::list_item_identity()](https://developer.wordpress.org/reference/classes/wp_view_config_data/list_item_identity/)`wp-includes/class-wp-view-config-data.php` |

Resolves the identity used to match a list member against another.

  | 
| [WP_View_Config_Data::strip_nulls()](https://developer.wordpress.org/reference/classes/wp_view_config_data/strip_nulls/)`wp-includes/class-wp-view-config-data.php` |

Recursively drops every property whose value is `null` from a value.

  | 
| [WP_View_Config_Data::merge_properties()](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_properties/)`wp-includes/class-wp-view-config-data.php` |

Merges an incoming value into the current one, recursing by value shape.

  |

| Used by | Description | 
| [WP_View_Config_Data::merge_properties()](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_properties/)`wp-includes/class-wp-view-config-data.php` |

Merges an incoming value into the current one, recursing by value shape.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wp_view_config_data/merge_list_by_identity/?output_format=md#changelog)󠁿

| Version | Description | 
| [7.1.0](https://developer.wordpress.org/reference/since/7.1.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_view_config_data%2Fmerge_list_by_identity%2F)
before being able to contribute a note or feedback.