[Summary view] [Print] [Text view]

   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       * @since 7.2.0 Added the `public` property.
  41       *
  42       * @param string $collection_slug       Icon collection slug.
  43       * @param array  $collection_properties {
  44       *     List of properties for the icon collection.
  45       *
  46       *     @type string $label       Required. A human-readable label for the icon collection.
  47       *     @type string $description Optional. A human-readable description for the icon collection.
  48       *     @type bool   $public      Optional. Whether the collection and its icons are exposed through
  49       *                               the REST API, and therefore selectable in the editor's icon picker.
  50       *                               Icons in non-public collections stay available to server-side code
  51       *                               via {@see wp_get_icon()}. Default true.
  52       * }
  53       * @return bool True if the collection was registered successfully, false otherwise.
  54       *
  55       * @phpstan-param lowercase-string&non-empty-string $collection_slug
  56       */
  57  	public function register( $collection_slug, $collection_properties ) {
  58          if ( ! isset( $collection_slug ) || ! is_string( $collection_slug ) ) {
  59              _doing_it_wrong(
  60                  __METHOD__,
  61                  __( 'Icon collection slug must be a string.' ),
  62                  '7.1.0'
  63              );
  64              return false;
  65          }
  66  
  67          if ( ! preg_match( '/^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$/', $collection_slug ) ) {
  68              _doing_it_wrong(
  69                  __METHOD__,
  70                  __( 'Icon collection slug must start and end with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, and underscores.' ),
  71                  '7.1.0'
  72              );
  73              return false;
  74          }
  75  
  76          if ( $this->is_registered( $collection_slug ) ) {
  77              _doing_it_wrong(
  78                  __METHOD__,
  79                  __( 'Icon collection is already registered.' ),
  80                  '7.1.0'
  81              );
  82              return false;
  83          }
  84  
  85          if ( ! is_array( $collection_properties ) ) {
  86              _doing_it_wrong(
  87                  __METHOD__,
  88                  __( 'Icon collection properties must be an array.' ),
  89                  '7.1.0'
  90              );
  91              return false;
  92          }
  93  
  94          $allowed_keys = array_fill_keys( array( 'label', 'description', 'public' ), 1 );
  95          foreach ( array_keys( $collection_properties ) as $key ) {
  96              if ( ! array_key_exists( $key, $allowed_keys ) ) {
  97                  _doing_it_wrong(
  98                      __METHOD__,
  99                      sprintf(
 100                          /* translators: %s: The name of a user-provided key. */
 101                          __( 'Invalid icon collection property: "%s".' ),
 102                          $key
 103                      ),
 104                      '7.1.0'
 105                  );
 106                  return false;
 107              }
 108          }
 109  
 110          if ( ! isset( $collection_properties['label'] ) || ! is_string( $collection_properties['label'] ) ) {
 111              _doing_it_wrong(
 112                  __METHOD__,
 113                  __( 'Icon collection label must be a string.' ),
 114                  '7.1.0'
 115              );
 116              return false;
 117          }
 118  
 119          if ( isset( $collection_properties['description'] ) && ! is_string( $collection_properties['description'] ) ) {
 120              _doing_it_wrong(
 121                  __METHOD__,
 122                  __( 'Icon collection description must be a string.' ),
 123                  '7.1.0'
 124              );
 125              return false;
 126          }
 127  
 128          if ( array_key_exists( 'public', $collection_properties ) && ! is_bool( $collection_properties['public'] ) ) {
 129              _doing_it_wrong(
 130                  __METHOD__,
 131                  __( 'Icon collection public property must be a boolean.' ),
 132                  '7.2.0'
 133              );
 134              return false;
 135          }
 136  
 137          $defaults = array(
 138              'description' => '',
 139              'public'      => true,
 140          );
 141  
 142          $collection = array_merge(
 143              $defaults,
 144              $collection_properties,
 145              array( 'slug' => $collection_slug )
 146          );
 147  
 148          $this->registered_collections[ $collection_slug ] = $collection;
 149  
 150          return true;
 151      }
 152  
 153      /**
 154       * Unregisters an icon collection.
 155       *
 156       * Any icons registered under the given collection are also unregistered.
 157       *
 158       * @since 7.1.0
 159       *
 160       * @param string $collection_slug Icon collection slug.
 161       * @return bool True if the collection was unregistered successfully, false otherwise.
 162       */
 163  	public function unregister( $collection_slug ) {
 164          if ( ! $this->is_registered( $collection_slug ) ) {
 165              _doing_it_wrong(
 166                  __METHOD__,
 167                  sprintf(
 168                      /* translators: %s: Icon collection slug. */
 169                      __( 'Icon collection "%s" not found.' ),
 170                      $collection_slug
 171                  ),
 172                  '7.1.0'
 173              );
 174              return false;
 175          }
 176  
 177          $icons_registry = WP_Icons_Registry::get_instance();
 178          foreach ( $icons_registry->get_registered_icons() as $icon ) {
 179              if ( isset( $icon['collection'] ) && $icon['collection'] === $collection_slug ) {
 180                  $icons_registry->unregister( $icon['name'] );
 181              }
 182          }
 183  
 184          unset( $this->registered_collections[ $collection_slug ] );
 185  
 186          return true;
 187      }
 188  
 189      /**
 190       * Retrieves an array containing the properties of a registered icon collection.
 191       *
 192       * @since 7.1.0
 193       *
 194       * @param string $collection_slug Icon collection slug.
 195       * @return array|null Registered collection properties, or `null` if the collection is not registered.
 196       */
 197  	public function get_registered( $collection_slug ) {
 198          if ( ! $this->is_registered( $collection_slug ) ) {
 199              return null;
 200          }
 201  
 202          return $this->registered_collections[ $collection_slug ];
 203      }
 204  
 205      /**
 206       * Retrieves all registered icon collections.
 207       *
 208       * @since 7.1.0
 209       *
 210       * @return array[] Array of arrays containing the registered icon collections properties.
 211       */
 212  	public function get_all_registered() {
 213          return array_values( $this->registered_collections );
 214      }
 215  
 216      /**
 217       * Checks if an icon collection is registered.
 218       *
 219       * @since 7.1.0
 220       *
 221       * @param string|null $collection_slug Icon collection slug.
 222       * @return bool True if the icon collection is registered, false otherwise.
 223       */
 224  	public function is_registered( $collection_slug ) {
 225          return isset( $collection_slug, $this->registered_collections[ $collection_slug ] );
 226      }
 227  
 228      /**
 229       * Utility method to retrieve the main instance of the class.
 230       *
 231       * The instance will be created if it does not exist yet.
 232       *
 233       * @since 7.1.0
 234       *
 235       * @return WP_Icon_Collections_Registry The main instance.
 236       */
 237  	public static function get_instance() {
 238          self::$instance ??= new self();
 239  
 240          return self::$instance;
 241      }
 242  }