function icon_get_path

Locates an icon and returns its path.

Icons can be provided by themes, modules, and core. Normally, icons are provided by core (from the core/misc/icons directory), but modules can provide additional icons or override core ones. Modules must implement hook_icon_info() to provide icons. Themes can also provide icons or override existing ones by placing icons in their "icons" subdirectory.

@since 1.28.0 Function added.

Parameters

string $icon_name: The name of an icon without a file extension. Most icon names can be determined by looking in the core/misc/icons directory.

boolean $immutable: Immutable icons cannot be modified by themes or modules. Instead of allowing overrides, the first system that defines an icon name defines its path. This allows certain icons to lock to the icon provided by core or a module without allowing a theme to override it. Useful in situations where an icon is used across multiple themes (like in the admin bar).

Return value

string|NULL: The path to an icon, relative to the Backdrop installation root, with the file extension (usually .svg). Or NULL if an icon is not found.

See also

hook_icon_info()

hook_icon_info_alter()

File

core/includes/icon.inc, line 96

Provides the Backdrop API for placing icons.

Code

function icon_get_path($icon_name, $immutable = FALSE) {
  // Save into a static cache with both normal and immutable paths.
  $icon_paths = &backdrop_static(__FUNCTION__, array(
    'normal' => array(),
    'immutable' => array(),
  ));

  $immutable_type = $immutable ? 'immutable' : 'normal';
  if (isset($icon_paths[$immutable_type][$icon_name])) {
    return $icon_paths[$immutable_type][$icon_name];
  }

  // Normal search order searches themes, then modules, then core.
  $search_functions = array(
    '_icon_from_theme',
    '_icon_from_module',
    '_icon_from_core',
  );
  // Immutable searches core, then modules, then themes.
  if ($immutable) {
    $search_functions = array_reverse($search_functions);
  }

  $icon_path = NULL;
  foreach ($search_functions as $function) {
    if ($icon_path = $function($icon_name)) {
      break;
    }
  }

  // Save in the static cache and return.
  $icon_paths[$immutable_type][$icon_name] = $icon_path;
  return $icon_path;
}