IconDefinitionInterface.php

<?php

declare (strict_types=1);
namespace Drupal\Core\Theme\Icon;

use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Interface for icon definition.
 *
 * @internal
 *   This API is experimental.
 */
interface IconDefinitionInterface {
    
    /**
     * Create an icon definition.
     *
     * @param string $pack_id
     *   The id of the icon pack.
     * @param string $icon_id
     *   The id of the icon.
     * @param string $template
     *   The icon template from definition.
     * @param string|null $source
     *   The source, url or path of the icon.
     * @param string|null $group
     *   The group of the icon.
     * @param array $data
     *   The additional data of the icon. Used by extractors to dynamically add
     *   any needed value.
     *
     * @return self
     *   The icon definition.
     */
    public static function create(string $pack_id, string $icon_id, string $template, ?string $source = NULL, ?string $group = NULL, array $data = []) : self;
    
    /**
     * Create an icon full id.
     *
     * @param string $pack_id
     *   The id of the icon pack.
     * @param string $icon_id
     *   The id of the icon.
     *
     * @return string
     *   The icon full id.
     */
    public static function createIconId(string $pack_id, string $icon_id) : string;
    
    /**
     * Get icon id and pack id from an icon full id.
     *
     * @param string $icon_full_id
     *   The id of the icon including the pack.
     *
     * @return array|null
     *   The icon data as keyed with `pack_id` and `icon_id`.
     */
    public static function getIconDataFromId(string $icon_full_id) : ?array;
    
    /**
     * Get the icon renderable element array.
     *
     * Shortcut to use icon element quickly without check if the icon id is valid,
     * then the element will simply be empty.
     *
     * @param string $icon_full_id
     *   The id of the icon including the pack.
     * @param array $settings
     *   Settings to pass to the renderable for context. Can be indexed by the
     *   icon pack id for lookup.
     *
     * @return array|null
     *   The icon renderable.
     */
    public static function getRenderable(string $icon_full_id, array $settings = []) : ?array;
    
    /**
     * Get the icon label as human friendly.
     *
     * @return string
     *   The icon label.
     */
    public function getLabel() : string;
    
    /**
     * Get the full icon id.
     *
     * @return string
     *   The icon id as pack_id:icon_id.
     */
    public function getId() : string;
    
    /**
     * Get the icon id.
     *
     * @return string
     *   The icon id as icon_id.
     */
    public function getIconId() : string;
    
    /**
     * Get the icon Pack id.
     *
     * @return string
     *   The icon Pack id.
     */
    public function getPackId() : string;
    
    /**
     * Get the icon source, path or url.
     *
     * @return string|null
     *   The icon source.
     */
    public function getSource() : ?string;
    
    /**
     * Get the icon Group.
     *
     * @return string|null
     *   The icon Group.
     */
    public function getGroup() : ?string;
    
    /**
     * Get the icon Twig template.
     *
     * @return string
     *   The icon template.
     */
    public function getTemplate() : string;
    
    /**
     * Get the icon pack label.
     *
     * @return \Drupal\Core\StringTranslation\TranslatableMarkup|null
     *   The icon pack label.
     */
    public function getPackLabel() : ?TranslatableMarkup;
    
    /**
     * Get the icon Twig library.
     *
     * @return string|null
     *   The icon library.
     */
    public function getLibrary() : ?string;
    
    /**
     * Get all icon data.
     *
     * Icon data is injected by extractors and can be used to set any values
     * needed for the extractor loadIcon() method.
     * The data is then injected in the Twig template of the icon.
     *
     * @return array
     *   All the icon data.
     */
    public function getAllData() : array;
    
    /**
     * Get a specific icon data.
     *
     * @param string $key
     *   The data key to retrieve.
     *
     * @return mixed
     *   The icon specific data if exist or null. The data being added as an array
     *   by extractors, there is no specific type enforced.
     */
    public function getData(string $key) : mixed;

}