Meta: Add label argument to register_meta function

With the introduction of Block Bindings, it became more common to see workflows where users need to see the custom fields that are available or connected. They were relying on the meta key, however it feelt too technical sometimes. The solution is adding a new label argument to include a human-readable name that can be used across the UI.

Props santosguillamot, mamaduka, gziolo, timothyblynjacobs, peterwilsoncc.
Fixes #61998.



git-svn-id: https://develop.svn.wordpress.org/trunk@59023 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/meta.php

@@ -1369,6 +1369,7 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
  * @since 5.3.0 Valid meta types expanded to include "array" and "object".
  * @since 5.5.0 The `$default` argument was added to the arguments array.
  * @since 6.4.0 The `$revisions_enabled` argument was added to the arguments array.
+ * @since 6.7.0 The `label` argument was added to the arguments array.
  *
  * @param string       $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
  *                                  or any other object type with an associated meta table.
@@ -1380,6 +1381,7 @@ function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype =
  *                                         the meta key will be registered on the entire object type. Default empty.
  *     @type string     $type              The type of data associated with this meta key.
  *                                         Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
+ *     @type string     $label             A human-readable label of the data attached to this meta key.
  *     @type string     $description       A description of the data attached to this meta key.
  *     @type bool       $single            Whether the meta key has one value per object, or an array of values per object.
  *     @type mixed      $default           The default value returned from get_metadata() if no value has been set yet.
@@ -1412,6 +1414,7 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
 	$defaults = array(
 		'object_subtype'    => '',
 		'type'              => 'string',
+		'label'             => '',
 		'description'       => '',
 		'default'           => '',
 		'single'            => false,

src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

@@ -478,6 +478,7 @@ protected function get_registered_fields() {
 
 			$default_schema = array(
 				'type'        => $default_args['type'],
+				'title'       => empty( $args['label'] ) ? '' : $args['label'],
 				'description' => empty( $args['description'] ) ? '' : $args['description'],
 				'default'     => isset( $args['default'] ) ? $args['default'] : null,
 			);

tests/phpunit/tests/meta/registerMeta.php

@@ -92,6 +92,7 @@ public function test_register_meta_with_post_object_type_populates_wp_meta_keys(
 				'' => array(
 					'flight_number' => array(
 						'type'              => 'string',
+						'label'             => '',
 						'description'       => '',
 						'single'            => false,
 						'sanitize_callback' => null,
@@ -117,6 +118,7 @@ public function test_register_meta_with_term_object_type_populates_wp_meta_keys(
 				'' => array(
 					'category_icon' => array(
 						'type'              => 'string',
+						'label'             => '',
 						'description'       => '',
 						'single'            => false,
 						'sanitize_callback' => null,
@@ -172,6 +174,7 @@ public function test_register_meta_with_current_sanitize_callback_populates_wp_m
 				'' => array(
 					'flight_number' => array(
 						'type'              => 'string',
+						'label'             => '',
 						'description'       => '',
 						'single'            => false,
 						'sanitize_callback' => array( $this, '_new_sanitize_meta_cb' ),
@@ -256,6 +259,19 @@ public function test_get_registered_meta_keys_with_invalid_type_is_empty() {
 		$this->assertEmpty( $meta_keys );
 	}
 
+	/**
+	 * @ticket 61998
+	 */
+	public function test_get_registered_meta_keys_label_arg() {
+		register_meta( 'post', 'registered_key1', array( 'label' => 'Field label' ) );
+
+		$meta_keys = get_registered_meta_keys( 'post' );
+
+		unregister_meta_key( 'post', 'registered_key1' );
+
+		$this->assertSame( 'Field label', $meta_keys['registered_key1']['label'] );
+	}
+
 	public function test_get_registered_meta_keys_description_arg() {
 		register_meta( 'post', 'registered_key1', array( 'description' => 'I\'m just a field, take a good look at me' ) );
 
@@ -340,6 +356,7 @@ public function test_register_meta_with_subtype_populates_wp_meta_keys( $type, $
 				$subtype => array(
 					'flight_number' => array(
 						'type'              => 'string',
+						'label'             => '',
 						'description'       => '',
 						'single'            => false,
 						'sanitize_callback' => null,
@@ -394,6 +411,7 @@ public function test_unregister_meta_without_subtype_keeps_subtype_meta_key( $ty
 				$subtype => array(
 					'flight_number' => array(
 						'type'              => 'string',
+						'label'             => '',
 						'description'       => '',
 						'single'            => false,
 						'sanitize_callback' => null,

tests/phpunit/tests/rest-api/rest-post-meta-fields.php

@@ -243,6 +243,18 @@ public function set_up() {
 			)
 		);
 
+		register_post_meta(
+			'post',
+			'with_label',
+			array(
+				'type'         => 'string',
+				'single'       => true,
+				'show_in_rest' => true,
+				'label'        => 'Meta Label',
+				'default'      => '',
+			)
+		);
+
 		/** @var WP_REST_Server $wp_rest_server */
 		global $wp_rest_server;
 		$wp_rest_server = new Spy_REST_Server();
@@ -3091,8 +3103,21 @@ public function test_default_is_added_to_schema() {
 		$response = rest_do_request( $request );
 
 		$schema = $response->get_data()['schema']['properties']['meta']['properties']['with_default'];
-		$this->assertArrayHasKey( 'default', $schema );
-		$this->assertSame( 'Goodnight Moon', $schema['default'] );
+		$this->assertArrayHasKey( 'default', $schema, 'Schema is expected to have the default property' );
+		$this->assertSame( 'Goodnight Moon', $schema['default'], 'Schema default is expected to be defined and contain the value of the meta default argument.' );
+	}
+
+	/**
+	 * @ticket 61998
+	 */
+	public function test_title_is_added_to_schema() {
+		$request  = new WP_REST_Request( 'OPTIONS', '/wp/v2/posts' );
+		$response = rest_do_request( $request );
+
+		$schema = $response->get_data()['schema']['properties']['meta']['properties']['with_label'];
+
+		$this->assertArrayHasKey( 'title', $schema, 'Schema is expected to have the title property' );
+		$this->assertSame( 'Meta Label', $schema['title'], 'Schema title is expected to be defined and contain the value of the meta label argument.' );
 	}
 
 	/**

tests/phpunit/tests/user/wpRegisterPersistedPreferencesMeta.php

@@ -31,6 +31,7 @@ public function test_should_register_persisted_preferences_meta() {
 		$this->assertSame(
 			array(
 				'type'              => 'object',
+				'label'             => '',
 				'description'       => '',
 				'single'            => true,
 				'sanitize_callback' => null,