[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   *
  45   * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  46   *                          (e.g. "my-plugin/arrow-left"). The "core" collection is
  47   *                          reserved for WordPress core icons; third-party code should
  48   *                          register icons under its own collection rather than the
  49   *                          "core" collection.
  50   * @param array  $args {
  51   *     List of properties for the icon.
  52   *
  53   *     @type string $label     Required. A human-readable label for the icon.
  54   *     @type string $content   Optional. SVG markup for the icon.
  55   *                             If not provided, the content will be retrieved from the `file_path` if set.
  56   *                             If both `content` and `file_path` are not set, the icon will not be registered.
  57   *     @type string $file_path Optional. The full path to the file containing the icon content.
  58   * }
  59   * @return bool True if the icon was registered successfully, else false.
  60   */
  61  function wp_register_icon( $icon_name, $args ) {
  62      return WP_Icons_Registry::get_instance()->register( $icon_name, $args );
  63  }
  64  
  65  /**
  66   * Unregisters an icon.
  67   *
  68   * @since 7.1.0
  69   *
  70   * @param string $icon_name Namespaced icon name in the form "collection/icon-name"
  71   *                          (e.g. "core/arrow-left").
  72   * @return bool True if the icon was unregistered successfully, else false.
  73   */
  74  function wp_unregister_icon( $icon_name ) {
  75      return WP_Icons_Registry::get_instance()->unregister( $icon_name );
  76  }
  77  
  78  /**
  79   * Registers the default icon collections.
  80   *
  81   * @since 7.1.0
  82   * @access private
  83   */
  84  function _wp_register_default_icon_collections() {
  85      wp_register_icon_collection(
  86          'core',
  87          array(
  88              'label'       => __( 'WordPress' ),
  89              'description' => __( 'Default icon collection.' ),
  90          )
  91      );
  92  }
  93  
  94  /**
  95   * Registers the default core icons from the manifest.
  96   *
  97   * @since 7.1.0
  98   * @access private
  99   */
 100  function _wp_register_default_icons() {
 101      $icons_directory = ABSPATH . WPINC . '/images/icon-library/';
 102      $manifest_path   = ABSPATH . WPINC . '/assets/icon-library-manifest.php';
 103  
 104      if ( ! is_readable( $manifest_path ) ) {
 105          wp_trigger_error(
 106              __FUNCTION__,
 107              __( 'Core icon collection manifest is missing or unreadable.' )
 108          );
 109          return;
 110      }
 111  
 112      $collection = include $manifest_path;
 113  
 114      if ( empty( $collection ) ) {
 115          wp_trigger_error(
 116              __FUNCTION__,
 117              __( 'Core icon collection manifest is empty or invalid.' )
 118          );
 119          return;
 120      }
 121  
 122      foreach ( $collection as $icon_name => $icon_data ) {
 123          if (
 124              empty( $icon_data['filePath'] )
 125              || ! is_string( $icon_data['filePath'] )
 126          ) {
 127              _doing_it_wrong(
 128                  __FUNCTION__,
 129                  __( 'Core icon collection manifest must provide a valid "filePath" for each icon.' ),
 130                  '7.0.0'
 131              );
 132              return;
 133          }
 134  
 135          wp_register_icon(
 136              'core/' . $icon_name,
 137              array(
 138                  'label'     => $icon_data['label'],
 139                  'file_path' => $icons_directory . $icon_data['filePath'],
 140              )
 141          );
 142      }
 143  }
 144  
 145  /**
 146   * Returns the SVG markup for a registered icon.
 147   *
 148   * @since 7.1.0
 149   *
 150   * @param string $name The namespaced icon name (e.g. 'core/plus',
 151   *                     'core/arrow-down', 'my-plugin/custom-icon').
 152   * @param array  $args {
 153   *     Optional. Arguments for the icon. Default empty array.
 154   *
 155   *     @type int|null $size  Width and height in pixels. Pass null to leave the
 156   *                           SVG's intrinsic dimensions untouched. Default 24.
 157   *     @type string   $class Additional CSS class names. Multiple classes may be
 158   *                           provided as a space-separated string. Default empty string.
 159   *     @type string   $label Accessible label. If provided, the SVG gets
 160   *                           role="img" and aria-label. If omitted, the SVG
 161   *                           gets aria-hidden="true" and focusable="false".
 162   *                           Default empty string.
 163   * }
 164   * @return string SVG markup for the icon, or empty string if not found.
 165   */
 166  function wp_get_icon( $name, $args = array() ) {
 167      $icon = WP_Icons_Registry::get_instance()->get_registered_icon( $name );
 168      if ( is_null( $icon ) ) {
 169          return '';
 170      }
 171  
 172      $svg = $icon['content'];
 173      if ( empty( $svg ) ) {
 174          return '';
 175      }
 176  
 177      $args = wp_parse_args(
 178          $args,
 179          array(
 180              'size'  => 24,
 181              'class' => '',
 182              'label' => '',
 183          )
 184      );
 185  
 186      $processor = new WP_HTML_Tag_Processor( $svg );
 187      if ( ! $processor->next_tag( 'svg' ) ) {
 188          return '';
 189      }
 190  
 191      if ( is_numeric( $args['size'] ) ) {
 192          $size = absint( $args['size'] );
 193          $processor->set_attribute( 'width', (string) $size );
 194          $processor->set_attribute( 'height', (string) $size );
 195      }
 196  
 197      if ( ! empty( $args['class'] ) ) {
 198          foreach ( preg_split( '/\s+/', $args['class'], -1, PREG_SPLIT_NO_EMPTY ) as $class_name ) {
 199              $processor->add_class( $class_name );
 200          }
 201      }
 202  
 203      if ( ! empty( $args['label'] ) ) {
 204          $processor->set_attribute( 'role', 'img' );
 205          $processor->set_attribute( 'aria-label', $args['label'] );
 206          $processor->remove_attribute( 'aria-hidden' );
 207          $processor->remove_attribute( 'focusable' );
 208      } else {
 209          $processor->set_attribute( 'aria-hidden', 'true' );
 210          $processor->set_attribute( 'focusable', 'false' );
 211          $processor->remove_attribute( 'role' );
 212          $processor->remove_attribute( 'aria-label' );
 213      }
 214  
 215      return $processor->get_updated_html();
 216  }