[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   *
  15   * @param string $slug Icon collection slug.
  16   * @param array  $args {
  17   *     Arguments for registering an icon collection.
  18   *
  19   *     @type string $label       Required. A human-readable label for the icon collection.
  20   *     @type string $description Optional. A human-readable description for the icon collection.
  21   * }
  22   * @return bool True if the icon collection was registered successfully, else false.
  23   */
  24  function wp_register_icon_collection( $slug, $args ) {
  25      return WP_Icon_Collections_Registry::get_instance()->register( $slug, $args );
  26  }
  27  
  28  /**
  29   * Unregisters an icon collection.
  30   *
  31   * @since 7.1.0
  32   *
  33   * @param string $slug Icon collection slug.
  34   * @return bool True if the icon collection was unregistered successfully, else false.
  35   */
  36  function wp_unregister_icon_collection( $slug ) {
  37      return WP_Icon_Collections_Registry::get_instance()->unregister( $slug );
  38  }
  39  
  40  /**
  41   * Registers a new icon.
  42   *
  43   * @since 7.1.0
  44   * @since 7.2.0 Added the `public` and `keywords` properties.
  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   *     @type bool     $public    Optional. Whether the icon is exposed through the REST API, and
  60   *                               therefore selectable in the editor's icon picker. Non-public icons
  61   *                               stay available to server-side code via {@see wp_get_icon()}.
  62   *                               Default true.
  63   *     @type string[] $keywords  Optional. Additional search terms for the icon, matched by
  64   *                               `get_registered_icons()` alongside the name and label.
  65   * }
  66   * @return bool True if the icon was registered successfully, else false.
  67   */
  68  function wp_register_icon( $icon_name, $args ) {
  69      return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
  70  }
  71  
  72  /**
  73   * Unregisters an icon.
  74   *
  75   * @since 7.1.0
  76   *
  77   * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  78   *                          (e.g. "core/arrow-left").
  79   * @return bool True if the icon was unregistered successfully, else false.
  80   */
  81  function wp_unregister_icon( $icon_name ) {
  82      return WP_Icons_Registry::get_instance()->unregister( $icon_name );
  83  }
  84  
  85  /**
  86   * Registers the default icon collections.
  87   *
  88   * @since 7.1.0
  89   * @access private
  90   */
  91  function _wp_register_default_icon_collections() {
  92      wp_register_icon_collection(
  93          'core',
  94          array(
  95              'label'       => __( 'WordPress' ),
  96              'description' => __( 'Default icon collection.' ),
  97          )
  98      );
  99  }
 100  
 101  /**
 102   * Registers the default core icons from the manifest.
 103   *
 104   * @since 7.1.0
 105   * @access private
 106   */
 107  function _wp_register_default_icons() {
 108      $icons_directory = ABSPATH . WPINC . '/images/icon-library/';
 109      $manifest_path   = ABSPATH . WPINC . '/assets/icon-library-manifest.php';
 110  
 111      if ( ! is_readable( $manifest_path ) ) {
 112          wp_trigger_error(
 113              __FUNCTION__,
 114              __( 'Core icon collection manifest is missing or unreadable.' )
 115          );
 116          return;
 117      }
 118  
 119      $collection = include $manifest_path;
 120  
 121      if ( empty( $collection ) ) {
 122          wp_trigger_error(
 123              __FUNCTION__,
 124              __( 'Core icon collection manifest is empty or invalid.' )
 125          );
 126          return;
 127      }
 128  
 129      foreach ( $collection as $icon_name => $icon_data ) {
 130          if (
 131              empty( $icon_data['filePath'] )
 132              || ! is_string( $icon_data['filePath'] )
 133          ) {
 134              _doing_it_wrong(
 135                  __FUNCTION__,
 136                  __( 'Core icon collection manifest must provide a valid "filePath" for each icon.' ),
 137                  '7.0.0'
 138              );
 139              return;
 140          }
 141  
 142          $icon_args = array(
 143              'label'     => $icon_data['label'],
 144              'file_path' => $icons_directory . $icon_data['filePath'],
 145          );
 146  
 147          if ( isset( $icon_data['public'] ) ) {
 148              $icon_args['public'] = $icon_data['public'];
 149          }
 150  
 151          if ( isset( $icon_data['keywords'] ) ) {
 152              $icon_args['keywords'] = $icon_data['keywords'];
 153          }
 154  
 155          wp_register_icon( 'core/' . $icon_name, $icon_args );
 156      }
 157  }
 158  
 159  /**
 160   * Returns the SVG markup for a registered icon.
 161   *
 162   * @since 7.1.0
 163   *
 164   * @param string $name The namespaced icon name (e.g. 'core/plus',
 165   *                     'core/arrow-down', 'my-plugin/custom-icon').
 166   * @param array  $args {
 167   *     Optional. Arguments for the icon. Default empty array.
 168   *
 169   *     @type int|null $size  Width and height in pixels. Pass null to leave the
 170   *                           SVG's intrinsic dimensions untouched. Default 24.
 171   *     @type string   $class Additional CSS class names. Multiple classes may be
 172   *                           provided as a space-separated string. Default empty string.
 173   *     @type string   $label Accessible label. If provided, the SVG gets
 174   *                           role="img" and aria-label. If omitted, the SVG
 175   *                           gets aria-hidden="true" and focusable="false".
 176   *                           Default empty string.
 177   * }
 178   * @return string SVG markup for the icon, or empty string if not found.
 179   */
 180  function wp_get_icon( $name, $args = array() ) {
 181      $icon = WP_Icons_Registry::get_instance()->get_registered_icon( $name );
 182      if ( is_null( $icon ) ) {
 183          return '';
 184      }
 185  
 186      $svg = $icon['content'];
 187      if ( empty( $svg ) ) {
 188          return '';
 189      }
 190  
 191      $args = wp_parse_args(
 192          $args,
 193          array(
 194              'size'  => 24,
 195              'class' => '',
 196              'label' => '',
 197          )
 198      );
 199  
 200      $processor = new WP_HTML_Tag_Processor( $svg );
 201      if ( ! $processor->next_tag( 'svg' ) ) {
 202          return '';
 203      }
 204  
 205      if ( is_numeric( $args['size'] ) ) {
 206          $size = absint( $args['size'] );
 207          $processor->set_attribute( 'width', (string) $size );
 208          $processor->set_attribute( 'height', (string) $size );
 209      }
 210  
 211      if ( ! empty( $args['class'] ) ) {
 212          foreach ( preg_split( '/\s+/', $args['class'], -1, PREG_SPLIT_NO_EMPTY ) as $class_name ) {
 213              $processor->add_class( $class_name );
 214          }
 215      }
 216  
 217      if ( ! empty( $args['label'] ) ) {
 218          $processor->set_attribute( 'role', 'img' );
 219          $processor->set_attribute( 'aria-label', $args['label'] );
 220          $processor->remove_attribute( 'aria-hidden' );
 221          $processor->remove_attribute( 'focusable' );
 222      } else {
 223          $processor->set_attribute( 'aria-hidden', 'true' );
 224          $processor->set_attribute( 'focusable', 'false' );
 225          $processor->remove_attribute( 'role' );
 226          $processor->remove_attribute( 'aria-label' );
 227      }
 228  
 229      return $processor->get_updated_html();
 230  }