gutenberg / lib / compat / wordpress-7.1 / icons.php

icons.php in Gutenberg 24.1.0, at lib/compat/wordpress-7.1/icons.php

154 lines 5.4 KB

Raw Download Zip

1	<?php
2	/**
3	* Icons API functions.
4	*
5	* @package gutenberg
6	*/
7
8	if ( ! function_exists( 'wp_register_icon_collection' ) ) {
9	/**
10	* Registers a new icon collection.
11	*
12	* @param string $slug Icon collection slug.
13	* @param array $args {
14	* Arguments for registering an icon collection.
15	*
16	* @type string $label Required. A human-readable label for the icon collection.
17	* @type string $description Optional. A human-readable description for the icon collection.
18	* @type bool $public Optional. Whether the collection and its icons are exposed through
19	* the REST API and selectable in the editor's Icon block. Icons in
20	* non-public collections remain available via {@see wp_get_icon()}.
21	* Default true.
22	* }
23	* @return bool True if the icon collection was registered successfully, else false.
24	*/
25	function wp_register_icon_collection( $slug, $args ) {
26	return WP_Icon_Collections_Registry::get_instance()->register( $slug, $args );
27	}
28	}
29
30	if ( ! function_exists( 'wp_unregister_icon_collection' ) ) {
31	/**
32	* Unregisters an icon collection.
33	*
34	* @param string $slug Icon collection slug.
35	* @return bool True if the icon collection was unregistered successfully, else false.
36	*/
37	function wp_unregister_icon_collection( $slug ) {
38	return WP_Icon_Collections_Registry::get_instance()->unregister( $slug );
39	}
40	}
41
42	if ( ! function_exists( 'wp_register_icon' ) ) {
43	/**
44	* Registers a new icon.
45	*
46	* @param string $icon_name Namespaced icon name in the form "collection/icon-name"
47	* (e.g. "my-plugin/arrow-left"). The "core" collection is
48	* reserved for WordPress core icons; third-party code should
49	* register icons under its own collection rather than the
50	* "core" collection.
51	* @param array $args {
52	* List of properties for the icon.
53	*
54	* @type string $label Required. A human-readable label for the icon.
55	* @type string $content Optional. SVG markup for the icon.
56	* If not provided, the content will be retrieved from the `file_path` if set.
57	* If both `content` and `file_path` are not set, the icon will not be registered.
58	* @type string $file_path Optional. The full path to the file containing the icon content.
59	* }
60	* @return bool True if the icon was registered successfully, else false.
61	*/
62	function wp_register_icon( $icon_name, $args ) {
63	return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
64	}
65	}
66
67	if ( ! function_exists( 'wp_unregister_icon' ) ) {
68	/**
69	* Unregisters an icon.
70	*
71	* @param string $icon_name Namespaced icon name in the form "collection/icon-name"
72	* (e.g. "core/arrow-left").
73	* @return bool True if the icon was unregistered successfully, else false.
74	*/
75	function wp_unregister_icon( $icon_name ) {
76	return WP_Icons_Registry::get_instance()->unregister( $icon_name );
77	}
78	}
79
80	if ( ! function_exists( 'wp_get_icon' ) ) {
81	/**
82	* Returns the SVG markup for a registered icon.
83	*
84	* @since 7.1.0
85	*
86	* @param string $name The namespaced icon name (e.g. 'core/plus',
87	* 'core/arrow-down', 'my-plugin/custom-icon').
88	* @param array $args {
89	* Optional. Arguments for the icon.
90	*
91	* @type int\|null $size Width and height in pixels. Pass null to leave the
92	* SVG's intrinsic dimensions untouched. Non-numeric
93	* values are ignored. Default 24.
94	* @type string $class Additional CSS class names. Multiple classes may be
95	* provided as a space-separated string.
96	* @type string $label Accessible label. If provided, the SVG gets
97	* role="img" and aria-label. If omitted, the SVG
98	* gets aria-hidden="true" and focusable="false".
99	* }
100	* @return string SVG markup for the icon, or empty string if not found.
101	*/
102	function wp_get_icon( $name, $args = array() ) {
103	$icon = WP_Icons_Registry::get_instance()->get_registered_icon( $name );
104	if ( is_null( $icon ) ) {
105	return '';
106	}
107
108	$svg = $icon['content'];
109	if ( empty( $svg ) ) {
110	return '';
111	}
112
113	$args = wp_parse_args(
114	$args,
115	array(
116	'size' => 24,
117	'class' => '',
118	'label' => '',
119	)
120	);
121
122	$processor = new WP_HTML_Tag_Processor( $svg );
123	if ( ! $processor->next_tag( 'svg' ) ) {
124	return '';
125	}
126
127	if ( is_numeric( $args['size'] ) ) {
128	$size = absint( $args['size'] );
129	$processor->set_attribute( 'width', (string) $size );
130	$processor->set_attribute( 'height', (string) $size );
131	}
132
133	if ( ! empty( $args['class'] ) ) {
134	foreach ( preg_split( '/\s+/', $args['class'], -1, PREG_SPLIT_NO_EMPTY ) as $class_name ) {
135	$processor->add_class( $class_name );
136	}
137	}
138
139	if ( ! empty( $args['label'] ) ) {
140	$processor->set_attribute( 'role', 'img' );
141	$processor->set_attribute( 'aria-label', $args['label'] );
142	$processor->remove_attribute( 'aria-hidden' );
143	$processor->remove_attribute( 'focusable' );
144	} else {
145	$processor->set_attribute( 'aria-hidden', 'true' );
146	$processor->set_attribute( 'focusable', 'false' );
147	$processor->remove_attribute( 'role' );
148	$processor->remove_attribute( 'aria-label' );
149	}
150
151	return $processor->get_updated_html();
152	}
153	}
154