[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       *
  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  }