[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> class-wp-view-config-data.php (summary)

WP_View_Config_Data class

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

Defines 1 class

WP_View_Config_Data:: (14 methods):
  __construct()
  get_data()
  apply_filters()
  set()
  remove()
  replace()
  merge()
  apply()
  strip_nulls()
  merge_properties()
  remove_properties()
  remove_list_member()
  merge_list_by_identity()
  list_item_identity()


Class: WP_View_Config_Data  - X-Ref

Holds an entity's view configuration while it is being built.

An instance of this class is what `get_entity_view_config_{$kind}_{$name}`
filter callbacks receive: a callback changes the configuration by calling
methods on the instance and returning it. The configuration has four
top-level keys — `default_view`, `default_layouts`, `view_list`, and
`form` — and there are three ways to contribute. They form a gradient of how
deep the replacement reaches:

- The `merge()` method merges partial changes (patches) into what is already
there: `default_view`, `default_layouts`, and the `form` settings by key,
and the `view_list` entries by view `slug` identity. This is what plugins
should use: patches compose with core's configuration and with other
plugins'.
- `replace()` applies a patch the same way `merge()` does, with one
difference: a list in the patch replaces the current list wholesale
instead of merging into it by member identity. It shouldn't be the
default choice — a callback that replaces a list stops inheriting core's
future additions to it — but it's useful when a contributor needs to pin
a list to an exact set of members.
- `set()` goes one step further: it replaces each top-level key the patch
names wholesale, dropping whatever that key held instead of merging into
it. It's for a callback that owns a key outright and wants to pin it to an
exact shape without the inherited default leaking through a key-by-key
merge.

All three touch only the top-level keys the patch names — an omitted key
keeps whatever it had, and a top-level `null` value drops the key it names,
which resets it to its default. They differ only in how deep the replacement
reaches once a key is named: `merge()` and `replace()` merge the value in
key by key (an associative array merges member by member, a nested `null`
deletes just that leaf, a scalar replaces just that value), while `set()`
swaps the whole value. A nested `null` deletes just the leaf it names in
every case. A patch value whose shape does not match the current value —
an associative array where a list lives, or the reverse — is rejected with
a notice rather than merged, and an empty array under `merge()` is a
no-op. Each patch also declares the configuration schema
version it was written against (currently 1), so a future WordPress release
that changes the configuration shape can migrate existing patches forward
instead of breaking them.

Where those three write values, `remove()` deletes them: it takes a spec of
names — a list to delete entries at a level, or a nested map to reach deeper —
and prunes just what it names, mirroring the configuration's shape all the way
down to individual list members.

__construct( array $config )   X-Ref
Constructor.

param: array $config The base configuration to contribute to.

get_data()   X-Ref
Returns the current configuration array.

Deliberately private: filter callbacks receive the container, not the
materialized configuration, so they cannot read the built result and
become coupled to a specific configuration shape or schema version. Only
the class itself reconciles the container back into an array.

return: array The configuration.

apply_filters( $kind, $name )   X-Ref
Applies the entity view configuration filter and returns the result.

Exposes the container through the dynamic
`get_entity_view_config_{$kind}_{$name}` filter so that core and third
parties can provide the configuration for a specific entity, then
reconciles the filtered container back into a plain configuration array,
limited to the documented configuration keys.

return: array The filtered configuration, limited to the documented keys.
param: string $kind The entity kind (e.g. `postType`).
param: string $name The entity name (e.g. `page`).

set( array $patch, int $version )   X-Ref
Replaces whole top-level keys, leaving the rest of the configuration alone.

Like merge() and replace(), set() applies a patch of top-level keys and
touches only the keys the patch names: a key the patch omits keeps whatever
it had, and a `null` value drops the key it names (which resets it to its
default). The difference is depth — where merge() and replace() merge a
named key's value into the current one key by key, set() swaps the whole
value in wholesale, dropping whatever the key held before. A `null` nested
within that value still drops the property it names, so set() honours
nulls at every depth just as merge() and replace() do.

Use it when a callback owns a key outright and wants to pin it to an exact
shape, without the inherited default leaking through a key-by-key merge.

A patch that declares an unsupported schema version is rejected and does
not change anything.

return: WP_View_Config_Data The instance, for chaining.
param: array $patch   The partial configuration whose named keys to replace.
param: int   $version The schema version the patch was authored against.

remove( array $spec, int $version )   X-Ref
Removes named properties from the configuration, leaving the rest alone.

Where merge(), replace(), and set() take a patch of *values* to write,
remove() takes a spec of *names* to delete, and its shape mirrors the
configuration it prunes:

- A list of names deletes each named entry from the value at that level: a
key from an associative array, or the member with a matching identity
(`id`, `slug`, `field`, or a bare scalar) from a list.
- An associative array maps a name to a nested spec, recursing into that
entry's value to delete from within it.

Naming a top-level configuration key is the one exception: like a `null`
value in a patch, it resets that key to its default rather than dropping it
outright, so top-level removal and top-level `null` compose the same way.

So `array( 'default_view' )` resets the whole `default_view` key to its
default, `array( 'default_view' => array( 'sort' ) )` drops just its `sort`
property, and `array( 'default_view' => array( 'fields' => array( 'f2' ) ) )`
drops the `f2` member from its `fields` list. A name that is not present is
ignored, and a list is renumbered after a member is removed.

A spec that declares an unsupported schema version is rejected and does not
change anything.

return: WP_View_Config_Data The instance, for chaining.
param: array $spec    The names to remove, keyed to match the configuration shape.
param: int   $version The schema version the spec was authored against.

replace( array $patch, int $version )   X-Ref
Replaces list values while merging the rest of a partial configuration.

Takes the same arguments as merge() and applies the patch the same way,
with one difference: a list in the patch replaces the current list
wholesale instead of merging into it by member identity. Associative
arrays still merge key by key, `null` still drops what it names, and a
scalar still replaces the current value.

It shouldn't be the default choice — a callback that replaces a list
stops inheriting core's future additions to it — but it's useful when a
contributor needs to pin a list to an exact set of members.

The shape rule applies here too: a patch value whose shape does not match
the current value — an associative array where a list lives, or a
non-empty list where an associative value lives — is rejected with a
notice and leaves the current value unchanged. An empty array is exempt,
so replacing a list with an empty list still clears it.

A patch that declares an unsupported schema version is rejected and does
not change anything.

return: WP_View_Config_Data The instance, for chaining.
param: array $patch   The partial configuration to apply.
param: int   $version The schema version the patch was authored against.

merge( array $patch, int $version )   X-Ref
Merges a partial configuration into the existing one.

Applies a patch of top-level keys and touches only the keys the patch
names: a key the patch omits keeps whatever it had, and a `null` value
drops the key it names (which resets it to its default). Each named key's
value is then merged into the current one by value shape:

- a scalar replaces the current value;
- an associative array merges key by key, with a nested `null` deleting
just the leaf it names;
- a list merges into the current list by member identity.

Identity is the member's value cast to a string: a bare scalar is its own
identity, and a map is identified by the value of the first of the
well-known identity keys (`id`, `slug`, `field`) it carries. A member
whose identity matches one already present merges into it in place, keeping
its position; a member with no identity is appended to the end of the list.

For example, given this patch:

```php
array(
'default_view' => array( 'search' => 'new search', 'fields' => array( 'newField' ) ),
'default_layouts' => array( 'grid' => array( 'layout' => array( 'badgeFields' => array( 'newField' ) ) ) ),
'view_list' => array( array( 'slug' => 'table', 'title' => 'New title' ) ),
)
```

- default_view will be updated so the search string is 'new search' and the newField is appended to the list of fields.
- default_layouts will be updated so that newField is appended to the badgeFields.
- view_list will be updated so that the view with slug 'table' has its title changed to 'New title'.

A patch value only merges into a current value of the same shape: an
associative array where a list lives, or a non-empty list where an
associative value lives, is rejected with a notice and leaves the current
value unchanged. An empty array merges nothing and is a no-op — clear a
list with replace() and an empty list, or reset a key to its default with
a top-level `null`.

A patch that declares an unsupported schema version is rejected and does
not change anything.

return: WP_View_Config_Data The instance, for chaining.
param: array $patch   The partial configuration to merge.
param: int   $version The schema version the patch was authored against.

apply( array $patch, int $version, $method, $mode )   X-Ref
Applies a patch to the configuration, top-level key by top-level key.

Shared by merge(), replace(), and set(); the three differ only in how the
value of a named key is applied, which is carried by $mode:

- `merge`   merges the value into the current one, lists by member identity;
- `replace` merges the value in the same way but swaps lists wholesale;
- `set`     swaps the whole value in wholesale, without merging.

In every mode a top-level `null` resets the key it names to its default, a
nested `null` drops the property it names, and an omitted key is left
untouched, so all three treat nulls the same way at every depth.

return: WP_View_Config_Data The instance, for chaining.
param: array  $patch   The partial configuration to apply.
param: int    $version The schema version the patch was authored against.
param: string $method  The public method the patch was passed to, for misuse reporting.
param: string $mode    How to apply each named key's value: `merge`, `replace`, or `set`.

strip_nulls( $value )   X-Ref
Recursively drops every property whose value is `null` from a value.

set() swaps a named key's value in wholesale rather than merging it into
the current one, so it has no existing leaf for a nested `null` to delete
the way merge() and replace() do. Stripping nulls here gives a nested
`null` the same "drop the property it names" meaning under set() that it
carries everywhere else. The same applies to a list replace() swaps in
wholesale. A list is renumbered after a member is removed so removed
entries do not leave gaps.

return: mixed The value with every `null` property removed, recursively.
param: mixed $value The value to strip nulls from.

merge_properties( $current, $incoming, $replace_lists )   X-Ref
Merges an incoming value into the current one, recursing by value shape.

This is the core of the merge algorithm and is applied at every nesting
level: a scalar (or `null`) in $incoming replaces $current outright, an
associative array merges key by key (recursing here for each key, with a
`null` value deleting that key), and a list either replaces $current
wholesale ($replace_lists) or merges into it by member identity. The
$replace_lists flag is carried down through associative nesting so that,
under replace(), every list reached along the way is swapped wholesale.

An array in $incoming only merges into a current value of the same shape.
A non-empty mismatch — an associative array where a list lives, or a
non-empty list where an associative value lives — is reported with
_doing_it_wrong() and leaves the current value unchanged, so a malformed
patch cannot silently destroy configuration. An empty array is
shape-ambiguous and merges nothing, so it is a no-op: clearing a list is
spelled replace() with an empty list, and resetting a key is spelled
`null`.

return: mixed The merged value.
param: mixed $current       The current value.
param: mixed $incoming      The incoming value.
param: bool  $replace_lists Whether a list in $incoming replaces the current list

remove_properties( $current, $spec )   X-Ref
Removes the properties a spec names from the current value.

The mirror of merge_properties(), applied at every nesting level: a list in
$spec names entries to delete from $current — associative keys are unset,
and list members are matched by identity (list_item_identity) and dropped —
while an associative $spec recurses into each named entry to prune from
within it. A name absent from $current is ignored, and a list is renumbered
after members are removed so it keeps sequential keys.

return: mixed The pruned value.
param: mixed $current The current value.
param: mixed $spec    The names to remove from it.

remove_list_member( array $members, $identity )   X-Ref
Removes the first list member matching an identity, leaving the rest.

return: array The list with the matching member removed, if any.
param: array $members  The current list.
param: mixed $identity The identity of the member to remove.

merge_list_by_identity( array $current, array $incoming )   X-Ref
Merges an incoming list into the current one by member identity.

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.

return: array The merged list.
param: array $current  The current list.
param: array $incoming The incoming list.

list_item_identity( $item )   X-Ref
Resolves the identity used to match a list member against another.

The identity is simply the member's value cast to a string, regardless of
which key carries it: a bare scalar is its own identity, and a map is
identified by the value of the first of the well-known identity keys
(`id`, `slug`, `field`) it carries. Because the key is not part of
the identity, a bare field like `'f3'` matches any map carrying that
value, whether it appears as `array( 'id' => 'f3' )`,
`array( 'slug' => 'f3' )`, and so on — this lets the same shorthand target
lists keyed by different fields. Casting to string keeps numeric
identities matching whether they arrive as an int or a string. Anything
else (e.g. a nested list) has no identity and never matches, so it is
always appended.

return: string|null The identity, or null when the member has none.
param: mixed $item The list member.



Generated : Thu Jul 30 08:20:17 2026 Cross-referenced by PHPXref