Icons: Add a non-public state to the icon public property.

Icons can now be registered with `'public' => false`, which keeps them in the
registry and reachable from server-side code via `wp_get_icon()`, while hiding
them from the icons REST API and therefore from the editor's icon picker.

This mirrors the tri-state `public` property in the Gutenberg icons manifest:

- omitted: the icon stays in the JS library and is not shipped to core
- `true`:  shipped to core and exposed through the REST API
- `false`: shipped to core and registered, but not exposed through the REST API

`WP_Icons_Registry::register()` accepts and validates the new property,
`_wp_register_default_icons()` forwards it when the core manifest carries it,
and `WP_REST_Icons_Controller` omits non-public icons from `get_items()` and
reports them as not found from `get_icon()`.

Without this, a synced `icon-library-manifest.php` carrying `'public' => false`
would fail to register the flagged icons at all, since the registry rejects a
registration containing any unknown property.

Author: fushar

src/wp-includes/class-wp-icons-registry.php

@@ -46,6 +46,7 @@ protected function __construct() {}
 	 *
 	 * @since 7.0.0
 	 * @since 7.1.0 The icon name must be namespaced in the form "collection/icon-name".
+	 * @since 7.2.0 Added the `public` property.
 	 *
 	 * @param string $icon_name       Namespaced icon name in the form "collection/icon-name"
 	 *                                (e.g. "core/arrow-left").
@@ -57,6 +58,10 @@ protected function __construct() {}
 	 *                             If not provided, the content will be retrieved from the `file_path` if set.
 	 *                             If both `content` and `file_path` are not set, the icon will not be registered.
 	 *     @type string $file_path Optional. The full path to the file containing the icon content.
+	 *     @type bool   $public    Optional. Whether the icon is exposed through the REST API, and
+	 *                             therefore selectable in the editor's icon picker. Non-public icons
+	 *                             stay available to server-side code via {@see wp_get_icon()}.
+	 *                             Default true.
 	 * }
 	 * @return bool True if the icon was registered with success and false otherwise.
 	 */
@@ -101,7 +106,7 @@ public function register( $icon_name, $icon_properties ) {
 			return false;
 		}
 
-		$allowed_keys = array_fill_keys( array( 'label', 'content', 'file_path' ), 1 );
+		$allowed_keys = array_fill_keys( array( 'label', 'content', 'file_path', 'public' ), 1 );
 		foreach ( array_keys( $icon_properties ) as $key ) {
 			if ( ! array_key_exists( $key, $allowed_keys ) ) {
 				_doing_it_wrong(
@@ -139,6 +144,15 @@ public function register( $icon_name, $icon_properties ) {
 			return false;
 		}
 
+		if ( isset( $icon_properties['public'] ) && ! is_bool( $icon_properties['public'] ) ) {
+			_doing_it_wrong(
+				__METHOD__,
+				__( 'Icon public property must be a boolean.' ),
+				'7.2.0'
+			);
+			return false;
+		}
+
 		if (
 			( ! isset( $icon_properties['content'] ) && ! isset( $icon_properties['file_path'] ) ) ||
 			( isset( $icon_properties['content'] ) && isset( $icon_properties['file_path'] ) )

src/wp-includes/icons.php

@@ -41,6 +41,7 @@ function wp_unregister_icon_collection( $slug ) {
  * Registers a new icon.
  *
  * @since 7.1.0
+ * @since 7.2.0 Added the `public` property.
  *
  * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  *                          (e.g. "my-plugin/arrow-left"). The "core" collection is
@@ -55,6 +56,10 @@ function wp_unregister_icon_collection( $slug ) {
  *                             If not provided, the content will be retrieved from the `file_path` if set.
  *                             If both `content` and `file_path` are not set, the icon will not be registered.
  *     @type string $file_path Optional. The full path to the file containing the icon content.
+ *     @type bool   $public    Optional. Whether the icon is exposed through the REST API, and
+ *                             therefore selectable in the editor's icon picker. Non-public icons
+ *                             stay available to server-side code via {@see wp_get_icon()}.
+ *                             Default true.
  * }
  * @return bool True if the icon was registered successfully, else false.
  */
@@ -132,13 +137,21 @@ function _wp_register_default_icons() {
 			return;
 		}
 
-		wp_register_icon(
-			'core/' . $icon_name,
-			array(
-				'label'     => $icon_data['label'],
-				'file_path' => $icons_directory . $icon_data['filePath'],
-			)
+		$icon_args = array(
+			'label'     => $icon_data['label'],
+			'file_path' => $icons_directory . $icon_data['filePath'],
 		);
+
+		/*
+		 * The manifest only carries `public` for non-public icons, and an absent
+		 * property already means public. Forwarding it unconditionally would send
+		 * the key to registries that predate it, which reject unknown properties.
+		 */
+		if ( isset( $icon_data['public'] ) ) {
+			$icon_args['public'] = $icon_data['public'];
+		}
+
+		wp_register_icon( 'core/' . $icon_name, $icon_args );
 	}
 }
 

src/wp-includes/rest-api/endpoints/class-wp-rest-icons-controller.php

@@ -143,6 +143,7 @@ public function get_item_permissions_check( $request ) {
 	 *
 	 * @since 7.0.0
 	 * @since 7.1.0 Supports filtering by collection.
+	 * @since 7.2.0 Icons registered as non-public are omitted.
 	 *
 	 * @param WP_REST_Request $request Full details about the request.
 	 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
@@ -167,6 +168,9 @@ public function get_items( $request ) {
 		$icons    = WP_Icons_Registry::get_instance()->get_registered_icons( $search );
 
 		foreach ( $icons as $icon ) {
+			if ( false === ( $icon['public'] ?? true ) ) {
+				continue;
+			}
 			if ( null !== $collection && ( ! isset( $icon['collection'] ) || $icon['collection'] !== $collection ) ) {
 				continue;
 			}
@@ -198,6 +202,7 @@ public function get_item( $request ) {
 	 * Retrieves a specific icon from the registry.
 	 *
 	 * @since 7.0.0
+	 * @since 7.2.0 Icons registered as non-public are reported as not found.
 	 *
 	 * @param string $name Icon name.
 	 * @return array|WP_Error Icon data on success, or WP_Error object on failure.
@@ -206,7 +211,7 @@ public function get_icon( $name ) {
 		$registry = WP_Icons_Registry::get_instance();
 		$icon     = $registry->get_registered_icon( $name );
 
-		if ( null === $icon ) {
+		if ( null === $icon || false === ( $icon['public'] ?? true ) ) {
 			return new WP_Error(
 				'rest_icon_not_found',
 				sprintf(

tests/phpunit/tests/icons/wpIconsRegistry.php

@@ -453,4 +453,27 @@ public function test_get_content_returns_null_for_invalid_file( $contents, $exte
 
 		$this->assertNull( $icon['content'] );
 	}
+
+	/**
+	 * Should reject a `public` property that is not a boolean.
+	 *
+	 * @ticket TODO
+	 *
+	 * @covers ::register
+	 *
+	 * @expectedIncorrectUsage WP_Icons_Registry::register
+	 */
+	public function test_register_rejects_non_boolean_public_property() {
+		$result = $this->registry->register(
+			'test-collection/invalid-visibility',
+			array(
+				'label'   => 'Icon',
+				'content' => '<svg></svg>',
+				'public'  => 'yes',
+			)
+		);
+
+		$this->assertFalse( $result );
+		$this->assertFalse( $this->registry->is_registered( 'test-collection/invalid-visibility' ) );
+	}
 }

tests/phpunit/tests/icons/wpRestIconsController.php

@@ -537,4 +537,76 @@ public function test_get_item_requires_authentication() {
 
 		$this->assertErrorResponse( 'rest_cannot_view', $response, 401 );
 	}
+
+	/**
+	 * Test that icons registered as non-public are omitted from the collection.
+	 *
+	 * @ticket TODO
+	 *
+	 * @covers ::get_items
+	 */
+	public function test_get_items_omits_non_public_icons() {
+		wp_register_icon_collection( 'rest-visibility-list', array( 'label' => 'REST Visibility' ) );
+		wp_register_icon(
+			'rest-visibility-list/visible',
+			array(
+				'label'   => 'Visible',
+				'content' => '<svg><path d="M0 0"/></svg>',
+			)
+		);
+		wp_register_icon(
+			'rest-visibility-list/hidden',
+			array(
+				'label'   => 'Hidden',
+				'content' => '<svg><path d="M1 1"/></svg>',
+				'public'  => false,
+			)
+		);
+
+		wp_set_current_user( self::$editor_id );
+
+		$request  = new WP_REST_Request( 'GET', '/wp/v2/icons' );
+		$response = rest_get_server()->dispatch( $request );
+
+		$this->assertSame( 200, $response->get_status() );
+
+		$names = wp_list_pluck( $response->get_data(), 'name' );
+		$this->assertContains( 'rest-visibility-list/visible', $names );
+		$this->assertNotContains( 'rest-visibility-list/hidden', $names );
+
+		wp_unregister_icon_collection( 'rest-visibility-list' );
+	}
+
+	/**
+	 * Test that a non-public icon is reported as not found by name, while
+	 * remaining available to server-side code.
+	 *
+	 * @ticket TODO
+	 *
+	 * @covers ::get_item
+	 * @covers ::get_icon
+	 */
+	public function test_get_item_returns_404_for_non_public_icon() {
+		wp_register_icon_collection( 'rest-visibility-single', array( 'label' => 'REST Visibility' ) );
+		wp_register_icon(
+			'rest-visibility-single/hidden',
+			array(
+				'label'   => 'Hidden',
+				'content' => '<svg><path d="M1 1"/></svg>',
+				'public'  => false,
+			)
+		);
+
+		wp_set_current_user( self::$editor_id );
+
+		$request  = new WP_REST_Request( 'GET', '/wp/v2/icons/rest-visibility-single/hidden' );
+		$response = rest_get_server()->dispatch( $request );
+
+		$this->assertErrorResponse( 'rest_icon_not_found', $response, 404 );
+
+		// The icon is hidden from the REST API, not unregistered.
+		$this->assertStringContainsString( '<svg', wp_get_icon( 'rest-visibility-single/hidden' ) );
+
+		wp_unregister_icon_collection( 'rest-visibility-single' );
+	}
 }