Removes named properties from the configuration, leaving the rest alone.
Description
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.
Parameters
$specarrayrequired- The names to remove, keyed to match the configuration shape.
$versionintrequired- The schema version the spec was authored against.
Source
public function remove( array $spec, int $version ) {
if ( $version <= 0 || $version > self::LATEST_VERSION ) {
_doing_it_wrong(
__METHOD__,
esc_html__( 'A view configuration patch must declare a supported schema version.' ),
'7.1.0'
);
return $this;
}
// A flat list names top-level keys to reset; a map recurses into each
// named key to prune from within its value.
$spec_is_list = array_is_list( $spec );
foreach ( $spec as $spec_key => $spec_value ) {
$key = $spec_is_list ? $spec_value : $spec_key;
if ( ! in_array( $key, self::CONFIG_KEYS, true ) ) {
_doing_it_wrong(
__METHOD__,
sprintf(
/* translators: %s: the configuration key. */
esc_html__( '"%s" is not a documented view configuration key.' ),
esc_html( $key )
),
'7.1.0'
);
continue;
}
if ( $spec_is_list ) {
// Removing a top-level key resets it to its default, just as a
// null patch value does.
$this->config[ $key ] = $this->defaults[ $key ] ?? array();
} elseif ( array_key_exists( $key, $this->config ) ) {
$this->config[ $key ] = $this->remove_properties( $this->config[ $key ], $spec_value );
}
}
return $this;
}
Changelog
| Version | Description |
|---|---|
| 7.1.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.