wppaste
WordPress

WP_View_Config_Data

Since
7.1.0
Source
wp-includes/class-wp-view-config-data.php:58
Holds an entity's view configuration while it is being built.

Description

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.

Compatibility

WordPress
since 7.1.0
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in 1 of the 5 tracked releases, added in 7.1.0.

Hooks and filters fired · 1

Every hook that fires from inside WP_View_Config_Data, in the order it appears in the class, grouped by the method that fires it.

WP_View_Config_Data::apply_filters()

  1. apply_filters( {$kind,} )filter line 187

Properties · 2

$configarrayprivate
The configuration being contributed to.
$defaultsarrayprivate
The default configuration.

Methods · 14

  • __construct()Constructor.
  • get_data()Returns the current configuration array.
  • apply_filters()Applies the entity view configuration filter and returns the result.
  • set()Replaces whole top-level keys, leaving the rest of the configuration alone.
  • remove()Removes named properties from the configuration, leaving the rest alone.
  • replace()Replaces list values while merging the rest of a partial configuration.
  • merge()Merges a partial configuration into the existing one.
  • apply()Applies a patch to the configuration, top-level key by top-level key.
  • strip_nulls()Recursively drops every property whose value is `null` from a value.
  • merge_properties()Merges an incoming value into the current one, recursing by value shape.
  • remove_properties()Removes the properties a spec names from the current value.
  • remove_list_member()Removes the first list member matching an identity, leaving the rest.
  • merge_list_by_identity()Merges an incoming list into the current one by member identity.
  • list_item_identity()Resolves the identity used to match a list member against another.

Source code

View on Trac View on GitHub 

class WP_View_Config_Data { 	/**	 * The latest supported configuration schema version.	 *	 * @since 7.1.0	 * @var int	 */	const LATEST_VERSION = 1; 	/**	 * The documented top-level configuration keys.	 *	 * @since 7.1.0	 * @var string[]	 */	const CONFIG_KEYS = array( 'default_view', 'default_layouts', 'view_list', 'form' ); 	/**	 * The configuration being contributed to.	 *	 * @since 7.1.0	 * @var array	 */	private $config; 	/**	 * The default configuration.	 *	 * @since 7.1.0	 * @var array	 */	private $defaults; 	/**	 * Constructor.	 *	 * @since 7.1.0	 *	 * @param array $config The base configuration to contribute to.	 */	public function __construct( array $config ) {		$this->config   = $config;		$this->defaults = $config;	} 	/**	 * 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.	 *	 * @since 7.1.0	 *	 * @return array The configuration.	 */	private function get_data() {		return $this->config;	} 	/**	 * Applies the entity view configuration filter and returns the result.	 *	 * Exposes the container through the dynamic	 * `get_entity_view_config_{$kind}_{$name}` filter (with the dynamic portions	 * lowercased), 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.	 *	 * @since 7.1.0	 *	 * @param string $kind The entity kind (e.g. `postType`).	 * @param string $name The entity name (e.g. `page`).	 * @return array The filtered configuration, limited to the documented keys.	 */	public function apply_filters( $kind, $name ) {		/**		 * Filters the view configuration for a given entity.

Changelog

Introduced in 7.1.0.

Signature, return type and hooks compared across 1 parsed release.

About this page

Parsed data
Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/class-wp-view-config-data.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.