* @link https://getkirby.com * @copyright Bastian Allgeier * @license https://opensource.org/licenses/MIT */ class Html extends Xml { /** * An internal store for an HTML entities translation table */ public static array|null $entities = null; /** * List of hosts that are allowed as source for embedded * Gists. Embedding Gists from any other host is blocked to * prevent loading untrusted scripts. Additional hosts (e.g. * for GitHub Enterprise) can be allowed via config: * * ```php * Html::$gistDomains[] = 'gist.example.com'; * ``` */ public static array $gistDomains = ['gist.github.com']; /** * List of HTML tags that can be used inline */ public static array $inlineList = [ 'b', 'i', 'small', 'abbr', 'cite', 'code', 'dfn', 'em', 'kbd', 'strong', 'samp', 'var', 'a', 'bdo', 'br', 'img', 'q', 'span', 'sub', 'sup' ]; /** * Closing string for void tags; * can be used to switch to trailing slashes if required * * ```php * Html::$void = ' />' * ``` */ public static string $void = '>'; /** * List of HTML tags that are considered to be self-closing */ public static array $voidList = [ 'area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'keygen', 'link', 'meta', 'param', 'source', 'track', 'wbr' ]; /** * Generic HTML tag generator * Can be called like `Html::p('A paragraph', ['class' => 'text'])` * * @param string $tag Tag name * @param array $arguments Further arguments for the Html::tag() method */ public static function __callStatic( string $tag, array $arguments = [] ): string { if (static::isVoid($tag) === true) { return static::tag($tag, null, ...$arguments); } return static::tag($tag, ...$arguments); } /** * Generates an `` tag; automatically supports mailto: and tel: links * * @param string $href The URL for the `` tag * @param string|array|null $text The optional text; if `null`, the URL will be used as text * @param array $attr Additional attributes for the tag * @return string The generated HTML */ public static function a( string $href, $text = null, array $attr = [] ): string { if (Str::startsWith($href, 'mailto:')) { return static::email(substr($href, 7), $text, $attr); } if (Str::startsWith($href, 'tel:')) { return static::tel(substr($href, 4), $text, $attr); } return static::link($href, $text, $attr); } /** * Generates a single attribute or a list of attributes * * @param string|array $name String: A single attribute with that name will be generated. * Key-value array: A list of attributes will be generated. Don't pass a second argument in that case. * @param mixed $value If used with a `$name` string, pass the value of the attribute here. * If used with a `$name` array, this can be set to `false` to disable attribute sorting. * @param string|null $before An optional string that will be prepended if the result is not empty * @param string|null $after An optional string that will be appended if the result is not empty * @return string|null The generated HTML attributes string */ public static function attr( string|array $name, $value = null, string|null $before = null, string|null $after = null ): string|null { // HTML supports boolean attributes without values if (is_array($name) === false && is_bool($value) === true) { return $value === true ? strtolower($name) : null; } // HTML attribute names are case-insensitive if (is_string($name) === true) { $name = strtolower($name); } // all other cases can share the XML variant $attr = parent::attr($name, $value); if ($attr === null) { return null; } // cache the keys/values arrays; // invalidates if $entities changes static $cached = null; static $html = []; static $xml = []; // HTML supports named entities $entities = parent::entities(); if ($cached !== $entities) { $html = array_keys($entities); $xml = array_values($entities); $cached = $entities; } $attr = str_replace($xml, $html, $attr); if ($attr) { return $before . $attr . $after; } return null; } /** * Converts lines in a string into HTML breaks */ public static function breaks(string $string): string { return nl2br($string); } /** * Generates an `` tag with `mailto:` * * @param string $email The email address * @param string|array|null $text The optional text; if `null`, the email address will be used as text * @param array $attr Additional attributes for the tag * @return string The generated HTML */ public static function email( string $email, string|array|null $text = null, array $attr = [] ): string { if (empty($email) === true) { return ''; } if (empty($text) === true) { // show only the email address without additional parameters $address = match (Str::contains($email, '?')) { true => Str::before($email, '?'), false => $email }; $text = [Str::encode($address)]; } $attr = [ 'href' => [ 'value' => 'mailto:' . Str::encode($email), 'escape' => false ], ...$attr ]; // add rel=noreferrer to target=_blank links to improve security // (avoids referrer leak and `window.opener` access) $attr['rel'] = static::rel( $attr['rel'] ?? null, $attr['target'] ?? null ); return static::tag('a', $text, $attr); } /** * Converts a string to an HTML-safe string * * @param bool $keepTags If true, existing tags won't be escaped * @return string The HTML string * * @psalm-suppress ParamNameMismatch */ public static function encode( string|null $string, bool $keepTags = false ): string { if ($string === null) { return ''; } if ($keepTags === true) { $list = static::entities(); unset( $list['"'], $list['<'], $list['>'], $list['&'] ); $search = array_keys($list); $values = array_values($list); return str_replace($search, $values, $string); } return htmlentities($string, ENT_QUOTES, 'utf-8'); } /** * Returns the entity translation table */ public static function entities(): array { return self::$entities ??= get_html_translation_table(HTML_ENTITIES); } /** * Creates a `

` tag with optional caption * * @param string|array $content Contents of the `

` tag * @param string|array $caption Optional `