|
| 1 | +<?php |
| 2 | +/** |
| 3 | + * Icons API: WP_Icon_Collections_Registry class |
| 4 | + * |
| 5 | + * @package WordPress |
| 6 | + * @since 7.1.0 |
| 7 | + */ |
| 8 | + |
| 9 | +/** |
| 10 | + * Core class used for interacting with registered icon collections. |
| 11 | + * |
| 12 | + * Icons are always associated with a single collection. Collections act as |
| 13 | + * a namespace for icons and allow grouping icons coming from different |
| 14 | + * sources (e.g. core, Font Awesome, Google Material Icons). |
| 15 | + * |
| 16 | + * @since 7.1.0 |
| 17 | + */ |
| 18 | +class WP_Icon_Collections_Registry { |
| 19 | + |
| 20 | + /** |
| 21 | + * Registered icon collections array. |
| 22 | + * |
| 23 | + * @since 7.1.0 |
| 24 | + * @var array[] |
| 25 | + */ |
| 26 | + protected $registered_collections = array(); |
| 27 | + |
| 28 | + /** |
| 29 | + * Container for the main instance of the class. |
| 30 | + * |
| 31 | + * @since 7.1.0 |
| 32 | + * @var WP_Icon_Collections_Registry|null |
| 33 | + */ |
| 34 | + protected static $instance = null; |
| 35 | + |
| 36 | + /** |
| 37 | + * Registers an icon collection. |
| 38 | + * |
| 39 | + * @since 7.1.0 |
| 40 | + * |
| 41 | + * @param string $collection_slug Icon collection slug. |
| 42 | + * @param array $collection_properties { |
| 43 | + * List of properties for the icon collection. |
| 44 | + * |
| 45 | + * @type string $label Required. A human-readable label for the icon collection. |
| 46 | + * @type string $description Optional. A human-readable description for the icon collection. |
| 47 | + * } |
| 48 | + * @return bool True if the collection was registered successfully, false otherwise. |
| 49 | + */ |
| 50 | + public function register( $collection_slug, $collection_properties ) { |
| 51 | + if ( ! isset( $collection_slug ) || ! is_string( $collection_slug ) ) { |
| 52 | + _doing_it_wrong( |
| 53 | + __METHOD__, |
| 54 | + __( 'Icon collection slug must be a string.' ), |
| 55 | + '7.1.0' |
| 56 | + ); |
| 57 | + return false; |
| 58 | + } |
| 59 | + |
| 60 | + if ( ! preg_match( '/^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$/', $collection_slug ) ) { |
| 61 | + _doing_it_wrong( |
| 62 | + __METHOD__, |
| 63 | + __( 'Icon collection slug must start and end with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, and underscores.' ), |
| 64 | + '7.1.0' |
| 65 | + ); |
| 66 | + return false; |
| 67 | + } |
| 68 | + |
| 69 | + if ( $this->is_registered( $collection_slug ) ) { |
| 70 | + _doing_it_wrong( |
| 71 | + __METHOD__, |
| 72 | + __( 'Icon collection is already registered.' ), |
| 73 | + '7.1.0' |
| 74 | + ); |
| 75 | + return false; |
| 76 | + } |
| 77 | + |
| 78 | + if ( ! is_array( $collection_properties ) ) { |
| 79 | + _doing_it_wrong( |
| 80 | + __METHOD__, |
| 81 | + __( 'Icon collection properties must be an array.' ), |
| 82 | + '7.1.0' |
| 83 | + ); |
| 84 | + return false; |
| 85 | + } |
| 86 | + |
| 87 | + $allowed_keys = array_fill_keys( array( 'label', 'description' ), 1 ); |
| 88 | + foreach ( array_keys( $collection_properties ) as $key ) { |
| 89 | + if ( ! array_key_exists( $key, $allowed_keys ) ) { |
| 90 | + _doing_it_wrong( |
| 91 | + __METHOD__, |
| 92 | + sprintf( |
| 93 | + /* translators: %s: The name of a user-provided key. */ |
| 94 | + __( 'Invalid icon collection property: "%s".' ), |
| 95 | + $key |
| 96 | + ), |
| 97 | + '7.1.0' |
| 98 | + ); |
| 99 | + return false; |
| 100 | + } |
| 101 | + } |
| 102 | + |
| 103 | + if ( ! isset( $collection_properties['label'] ) || ! is_string( $collection_properties['label'] ) ) { |
| 104 | + _doing_it_wrong( |
| 105 | + __METHOD__, |
| 106 | + __( 'Icon collection label must be a string.' ), |
| 107 | + '7.1.0' |
| 108 | + ); |
| 109 | + return false; |
| 110 | + } |
| 111 | + |
| 112 | + if ( isset( $collection_properties['description'] ) && ! is_string( $collection_properties['description'] ) ) { |
| 113 | + _doing_it_wrong( |
| 114 | + __METHOD__, |
| 115 | + __( 'Icon collection description must be a string.' ), |
| 116 | + '7.1.0' |
| 117 | + ); |
| 118 | + return false; |
| 119 | + } |
| 120 | + |
| 121 | + $defaults = array( |
| 122 | + 'description' => '', |
| 123 | + ); |
| 124 | + |
| 125 | + $collection = array_merge( |
| 126 | + $defaults, |
| 127 | + $collection_properties, |
| 128 | + array( 'slug' => $collection_slug ) |
| 129 | + ); |
| 130 | + |
| 131 | + $this->registered_collections[ $collection_slug ] = $collection; |
| 132 | + |
| 133 | + return true; |
| 134 | + } |
| 135 | + |
| 136 | + /** |
| 137 | + * Unregisters an icon collection. |
| 138 | + * |
| 139 | + * Any icons registered under the given collection are also unregistered. |
| 140 | + * |
| 141 | + * @since 7.1.0 |
| 142 | + * |
| 143 | + * @param string $collection_slug Icon collection slug. |
| 144 | + * @return bool True if the collection was unregistered successfully, false otherwise. |
| 145 | + */ |
| 146 | + public function unregister( $collection_slug ) { |
| 147 | + if ( ! $this->is_registered( $collection_slug ) ) { |
| 148 | + _doing_it_wrong( |
| 149 | + __METHOD__, |
| 150 | + sprintf( |
| 151 | + /* translators: %s: Icon collection slug. */ |
| 152 | + __( 'Icon collection "%s" not found.' ), |
| 153 | + $collection_slug |
| 154 | + ), |
| 155 | + '7.1.0' |
| 156 | + ); |
| 157 | + return false; |
| 158 | + } |
| 159 | + |
| 160 | + $icons_registry = WP_Icons_Registry::get_instance(); |
| 161 | + foreach ( $icons_registry->get_registered_icons() as $icon ) { |
| 162 | + if ( isset( $icon['collection'] ) && $icon['collection'] === $collection_slug ) { |
| 163 | + $icons_registry->unregister( $icon['name'] ); |
| 164 | + } |
| 165 | + } |
| 166 | + |
| 167 | + unset( $this->registered_collections[ $collection_slug ] ); |
| 168 | + |
| 169 | + return true; |
| 170 | + } |
| 171 | + |
| 172 | + /** |
| 173 | + * Retrieves an array containing the properties of a registered icon collection. |
| 174 | + * |
| 175 | + * @since 7.1.0 |
| 176 | + * |
| 177 | + * @param string $collection_slug Icon collection slug. |
| 178 | + * @return array|null Registered collection properties, or `null` if the collection is not registered. |
| 179 | + */ |
| 180 | + public function get_registered( $collection_slug ) { |
| 181 | + if ( ! $this->is_registered( $collection_slug ) ) { |
| 182 | + return null; |
| 183 | + } |
| 184 | + |
| 185 | + return $this->registered_collections[ $collection_slug ]; |
| 186 | + } |
| 187 | + |
| 188 | + /** |
| 189 | + * Retrieves all registered icon collections. |
| 190 | + * |
| 191 | + * @since 7.1.0 |
| 192 | + * |
| 193 | + * @return array[] Array of arrays containing the registered icon collections properties. |
| 194 | + */ |
| 195 | + public function get_all_registered() { |
| 196 | + return array_values( $this->registered_collections ); |
| 197 | + } |
| 198 | + |
| 199 | + /** |
| 200 | + * Checks if an icon collection is registered. |
| 201 | + * |
| 202 | + * @since 7.1.0 |
| 203 | + * |
| 204 | + * @param string|null $collection_slug Icon collection slug. |
| 205 | + * @return bool True if the icon collection is registered, false otherwise. |
| 206 | + */ |
| 207 | + public function is_registered( $collection_slug ) { |
| 208 | + return isset( $collection_slug, $this->registered_collections[ $collection_slug ] ); |
| 209 | + } |
| 210 | + |
| 211 | + /** |
| 212 | + * Utility method to retrieve the main instance of the class. |
| 213 | + * |
| 214 | + * The instance will be created if it does not exist yet. |
| 215 | + * |
| 216 | + * @since 7.1.0 |
| 217 | + * |
| 218 | + * @return WP_Icon_Collections_Registry The main instance. |
| 219 | + */ |
| 220 | + public static function get_instance() { |
| 221 | + if ( null === self::$instance ) { |
| 222 | + self::$instance = new self(); |
| 223 | + } |
| 224 | + |
| 225 | + return self::$instance; |
| 226 | + } |
| 227 | +} |
0 commit comments