[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Icons API: Icon registration and rendering helper functions.
   4   *
   5   * @package WordPress
   6   * @subpackage Icons
   7   * @since 7.1.0
   8   */
   9  
  10  /**
  11   * Registers a new icon collection.
  12   *
  13   * @since 7.1.0
  14   * @since 7.2.0 Added the `public` property.
  15   *
  16   * @param string $slug Icon collection slug.
  17   * @param array  $args {
  18   *     Arguments for registering an icon collection.
  19   *
  20   *     @type string $label       Required. A human-readable label for the icon collection.
  21   *     @type string $description Optional. A human-readable description for the icon collection.
  22   *     @type bool   $public      Optional. Whether the collection and its icons are exposed through
  23   *                               the REST API, and therefore selectable in the editor's icon picker.
  24   *                               Icons in non-public collections stay available to server-side code
  25   *                               via {@see wp_get_icon()}. Default true.
  26   * }
  27   * @return bool True if the icon collection was registered successfully, else false.
  28   *
  29   * @phpstan-param lowercase-string&non-empty-string $slug
  30   */
  31  function wp_register_icon_collection( $slug, $args ) {
  32      return WP_Icon_Collections_Registry::get_instance()->register( $slug, $args );
  33  }
  34  
  35  /**
  36   * Unregisters an icon collection.
  37   *
  38   * @since 7.1.0
  39   *
  40   * @param string $slug Icon collection slug.
  41   * @return bool True if the icon collection was unregistered successfully, else false.
  42   */
  43  function wp_unregister_icon_collection( $slug ) {
  44      return WP_Icon_Collections_Registry::get_instance()->unregister( $slug );
  45  }
  46  
  47  /**
  48   * Registers a new icon.
  49   *
  50   * @since 7.1.0
  51   * @since 7.2.0 Added the `keywords` property.
  52   *
  53   * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  54   *                          (e.g. "my-plugin/arrow-left"). The "core" and "core-admin"
  55   *                          collections are reserved for WordPress core icons; third-party
  56   *                          code should register icons under its own collection rather than
  57   *                          a reserved one.
  58   * @param array  $args      {
  59   *     List of properties for the icon.
  60   *
  61   *     @type string   $label     Required. A human-readable label for the icon.
  62   *     @type string   $content   Optional. SVG markup for the icon.
  63   *                               If not provided, the content will be retrieved from the `file_path` if set.
  64   *                               If both `content` and `file_path` are not set, the icon will not be registered.
  65   *     @type string   $file_path Optional. The full path to the file containing the icon content.
  66   *     @type string[] $keywords  Optional. Additional search terms for the icon, matched by
  67   *                               `get_registered_icons()` alongside the name and label.
  68   * }
  69   * @return bool True if the icon was registered successfully, else false.
  70   *
  71   * @phpstan-param lowercase-string&non-falsy-string $icon_name
  72   */
  73  function wp_register_icon( $icon_name, $args ) {
  74      return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
  75  }
  76  
  77  /**
  78   * Unregisters an icon.
  79   *
  80   * @since 7.1.0
  81   *
  82   * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  83   *                          (e.g. "core/arrow-left").
  84   * @return bool True if the icon was unregistered successfully, else false.
  85   */
  86  function wp_unregister_icon( $icon_name ) {
  87      return WP_Icons_Registry::get_instance()->unregister( $icon_name );
  88  }
  89  
  90  /**
  91   * Registers the default icon collections.
  92   *
  93   * @since 7.1.0
  94   * @access private
  95   */
  96  function _wp_register_default_icon_collections() {
  97      wp_register_icon_collection(
  98          'core',
  99          array(
 100              'label'       => __( 'WordPress' ),
 101              'description' => __( 'Default icon collection.' ),
 102          )
 103      );
 104      wp_register_icon_collection(
 105          'core-admin',
 106          array(
 107              'label'       => __( 'WordPress Admin' ),
 108              'description' => __( 'Icon collection used by the WordPress admin interface.' ),
 109              'public'      => false,
 110          )
 111      );
 112  }
 113  
 114  /**
 115   * Registers the default core and core-admin icons from the manifest.
 116   *
 117   * @since 7.1.0
 118   * @access private
 119   */
 120  function _wp_register_default_icons() {
 121      $icons_directory = ABSPATH . WPINC . '/images/icon-library/';
 122      $manifest_path   = ABSPATH . WPINC . '/assets/icon-library-manifest.php';
 123  
 124      if ( ! is_readable( $manifest_path ) ) {
 125          wp_trigger_error(
 126              __FUNCTION__,
 127              __( 'Core icon collection manifest is missing or unreadable.' )
 128          );
 129          return;
 130      }
 131  
 132      /**
 133       * @var array<lowercase-string&non-falsy-string, array{
 134       *     label: string,
 135       *     filePath: non-empty-string,
 136       *     collections: non-empty-list<lowercase-string&non-falsy-string>,
 137       *     keywords?: list<string>,
 138       *     dashicons?: non-empty-list<non-falsy-string>
 139       * }> $collection
 140       */
 141      $collection = include $manifest_path;
 142  
 143      if ( empty( $collection ) ) {
 144          wp_trigger_error(
 145              __FUNCTION__,
 146              __( 'Core icon collection manifest is empty or invalid.' )
 147          );
 148          return;
 149      }
 150  
 151      foreach ( $collection as $icon_name => $icon_data ) {
 152          if (
 153              empty( $icon_data['filePath'] )
 154              || ! is_string( $icon_data['filePath'] )
 155          ) {
 156              _doing_it_wrong(
 157                  __FUNCTION__,
 158                  __( 'Core icon collection manifest must provide a valid "filePath" for each icon.' ),
 159                  '7.0.0'
 160              );
 161              return;
 162          }
 163  
 164          if ( empty( $icon_data['collections'] ) || ! is_array( $icon_data['collections'] ) ) {
 165              _doing_it_wrong(
 166                  __FUNCTION__,
 167                  __( 'Core icon collection manifest must provide a non-empty "collections" array for each icon.' ),
 168                  '7.2.0'
 169              );
 170              return;
 171          }
 172  
 173          $icon_args = array(
 174              'label'     => $icon_data['label'],
 175              'file_path' => $icons_directory . $icon_data['filePath'],
 176          );
 177  
 178          if ( isset( $icon_data['keywords'] ) ) {
 179              $icon_args['keywords'] = $icon_data['keywords'];
 180          }
 181  
 182          foreach ( $icon_data['collections'] as $collection_slug ) {
 183              wp_register_icon( $collection_slug . '/' . $icon_name, $icon_args );
 184          }
 185      }
 186  }
 187  
 188  /**
 189   * Checks whether a value has the form of a namespaced icon name, i.e. "collection/icon-name".
 190   *
 191   * @since 7.2.0
 192   *
 193   * @param mixed $icon_name The value to check.
 194   * @return bool True if the value has the form of a namespaced icon name, else false.
 195   */
 196  function wp_is_valid_icon_name( $icon_name ) {
 197      return is_string( $icon_name )
 198          && preg_match( '#^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?/[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$#D', $icon_name );
 199  }
 200  
 201  /**
 202   * Returns the SVG markup for a registered icon.
 203   *
 204   * @since 7.1.0
 205   *
 206   * @param string $name The namespaced icon name (e.g. 'core/plus',
 207   *                     'core/arrow-down', 'my-plugin/custom-icon').
 208   * @param array  $args {
 209   *     Optional. Arguments for the icon. Default empty array.
 210   *
 211   *     @type int|null $size  Width and height in pixels. Pass null to leave the
 212   *                           SVG's intrinsic dimensions untouched. Default 24.
 213   *     @type string   $class Additional CSS class names. Multiple classes may be
 214   *                           provided as a space-separated string. Default empty string.
 215   *     @type string   $label Accessible label. If provided, the SVG gets
 216   *                           role="img" and aria-label. If omitted, the SVG
 217   *                           gets aria-hidden="true" and focusable="false".
 218   *                           Default empty string.
 219   * }
 220   * @return string SVG markup for the icon, or empty string if not found.
 221   */
 222  function wp_get_icon( $name, $args = array() ) {
 223      $icon = WP_Icons_Registry::get_instance()->get_registered_icon( $name );
 224      if ( is_null( $icon ) ) {
 225          return '';
 226      }
 227  
 228      $svg = $icon['content'];
 229      if ( empty( $svg ) ) {
 230          return '';
 231      }
 232  
 233      $args = wp_parse_args(
 234          $args,
 235          array(
 236              'size'  => 24,
 237              'class' => '',
 238              'label' => '',
 239          )
 240      );
 241  
 242      $processor = new WP_HTML_Tag_Processor( $svg );
 243      if ( ! $processor->next_tag( 'svg' ) ) {
 244          return '';
 245      }
 246  
 247      if ( is_numeric( $args['size'] ) ) {
 248          $size = absint( $args['size'] );
 249          $processor->set_attribute( 'width', (string) $size );
 250          $processor->set_attribute( 'height', (string) $size );
 251      }
 252  
 253      if ( ! empty( $args['class'] ) ) {
 254          foreach ( preg_split( '/\s+/', $args['class'], -1, PREG_SPLIT_NO_EMPTY ) as $class_name ) {
 255              $processor->add_class( $class_name );
 256          }
 257      }
 258  
 259      if ( ! empty( $args['label'] ) ) {
 260          $processor->set_attribute( 'role', 'img' );
 261          $processor->set_attribute( 'aria-label', $args['label'] );
 262          $processor->remove_attribute( 'aria-hidden' );
 263          $processor->remove_attribute( 'focusable' );
 264      } else {
 265          $processor->set_attribute( 'aria-hidden', 'true' );
 266          $processor->set_attribute( 'focusable', 'false' );
 267          $processor->remove_attribute( 'role' );
 268          $processor->remove_attribute( 'aria-label' );
 269      }
 270  
 271      return $processor->get_updated_html();
 272  }