Cecil\Renderer\Extension\Core

Complexity

Total Complexity

150

Size/Duplication

Total Lines	1030
Duplicated Lines	0 %

Importance

Changes	12
Bugs	2	Features	1

53 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	10	2
A	getName()	0	3	1
A	filterBySection()	0	3	1
A	sortByDate()	0	19	6
A	dataurl()	0	7	2
A	fingerprint()	0	7	2
B	filterBy()	0	15	8
A	minify()	0	7	2
A	maskable()	0	7	2
A	asset()	0	7	3
A	sortByWeight()	0	22	6
A	url()	0	7	1
A	sortByTitle()	0	8	1
A	toCss()	0	7	2
A	integrity()	0	7	2
A	resize()	0	7	2
A	getTests()	0	6	1
A	cover()	0	7	2
A	convert()	0	13	4
A	avif()	0	3	1
A	highlight()	0	3	1
A	inline()	0	3	1
A	excerpt()	0	12	2
A	isAsset()	0	3	1
A	imageSrcset()	0	3	1
A	getFunctions()	0	26	1
A	getEnv()	0	5	2
A	imageSizes()	0	3	1
A	varDump()	0	22	6
A	hexToRgb()	0	17	3
A	minifyCss()	0	17	3
A	readtime()	0	11	2
A	webp()	0	3	1
A	pregSplit()	0	14	3
A	lqip()	0	7	2
A	isImageSquare()	0	3	2
A	unique()	0	3	1
A	jsonDecode()	0	14	4
A	markdownToToc()	0	14	2
A	dominantColor()	0	7	2
A	scssToCss()	0	24	5
A	isImageLarge()	0	3	4
A	isHex()	0	9	4
A	markdownToHtml()	0	15	2
A	hash()	0	10	3
A	splitLine()	0	5	1
A	yamlParse()	0	14	3
A	minifyJs()	0	17	3
A	pregMatchAll()	0	14	3
D	html()	0	93	18
A	excerptHtml()	0	21	3
A	getFilters()	0	50	1
B	iterable()	0	21	8

<?php

/**
 * This file is part of Cecil.
 *
 * (c) Arnaud Ligny <arnaud@ligny.fr>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Cecil\Renderer\Extension;

use Cecil\Asset;
use Cecil\Asset\Image;
use Cecil\Builder;
use Cecil\Cache;
use Cecil\Collection\CollectionInterface;
use Cecil\Collection\Page\Collection as PagesCollection;
use Cecil\Collection\Page\Page;
use Cecil\Collection\Page\Type;
use Cecil\Config;
use Cecil\Converter\Parsedown;
use Cecil\Exception\ConfigException;
use Cecil\Exception\RuntimeException;
use Cecil\Url;
use Cocur\Slugify\Bridge\Twig\SlugifyExtension;
use Cocur\Slugify\Slugify;
use Highlight\Highlighter;
use MatthiasMullie\Minify;
use ScssPhp\ScssPhp\Compiler;
use ScssPhp\ScssPhp\OutputStyle;
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;
use Symfony\Component\Yaml\Exception\ParseException;
use Symfony\Component\Yaml\Yaml;
use Twig\DeprecatedCallableInfo;

/**
 * Core Twig extension.
 *
 * This extension provides various utility functions and filters for use in Twig templates,
 * including URL generation, asset management, content processing, and more.
 */
class Core extends SlugifyExtension
{
    /** @var Builder */
    protected $builder;

    /** @var Config */
    protected $config;

    /** @var Slugify */
    private static $slugifier;

    public function __construct(Builder $builder)
    {
        if (!self::$slugifier instanceof Slugify) {
            self::$slugifier = Slugify::create(['regexp' => Page::SLUGIFY_PATTERN]);
        }

        parent::__construct(self::$slugifier);

        $this->builder = $builder;
        $this->config = $builder->getConfig();
    }

    /**
     * {@inheritdoc}
     */
    public function getName(): string
    {
        return 'CoreExtension';
    }

    /**
     * {@inheritdoc}
     */
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('url', [$this, 'url'], ['needs_context' => true]),
            // assets
            new \Twig\TwigFunction('asset', [$this, 'asset']),
            new \Twig\TwigFunction('html', [$this, 'html'], ['needs_context' => true]),
            new \Twig\TwigFunction('integrity', [$this, 'integrity']),
            new \Twig\TwigFunction('image_srcset', [$this, 'imageSrcset']),
            new \Twig\TwigFunction('image_sizes', [$this, 'imageSizes']),
            // content
            new \Twig\TwigFunction('readtime', [$this, 'readtime']),
            new \Twig\TwigFunction('hash', [$this, 'hash']),
            // others
            new \Twig\TwigFunction('getenv', [$this, 'getEnv']),
            new \Twig\TwigFunction('d', [$this, 'varDump'], ['needs_context' => true, 'needs_environment' => true]),
            // deprecated
            new \Twig\TwigFunction(
                'minify',
                [$this, 'minify'],
                ['deprecation_info' => new DeprecatedCallableInfo('', '', 'minify filter')]
            ),
            new \Twig\TwigFunction(
                'toCSS',
                [$this, 'toCss'],
                ['deprecation_info' => new DeprecatedCallableInfo('', '', 'to_css filter')]
            ),
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function getFilters(): array
    {
        return [
            new \Twig\TwigFilter('url', [$this, 'url'], ['needs_context' => true]),
            // collections
            new \Twig\TwigFilter('sort_by_title', [$this, 'sortByTitle']),
            new \Twig\TwigFilter('sort_by_weight', [$this, 'sortByWeight']),
            new \Twig\TwigFilter('sort_by_date', [$this, 'sortByDate']),
            new \Twig\TwigFilter('filter_by', [$this, 'filterBy']),
            // assets
            new \Twig\TwigFilter('inline', [$this, 'inline']),
            new \Twig\TwigFilter('fingerprint', [$this, 'fingerprint']),
            new \Twig\TwigFilter('to_css', [$this, 'toCss']),
            new \Twig\TwigFilter('minify', [$this, 'minify']),
            new \Twig\TwigFilter('minify_css', [$this, 'minifyCss']),
            new \Twig\TwigFilter('minify_js', [$this, 'minifyJs']),
            new \Twig\TwigFilter('scss_to_css', [$this, 'scssToCss']),
            new \Twig\TwigFilter('sass_to_css', [$this, 'scssToCss']),
            new \Twig\TwigFilter('resize', [$this, 'resize']),
            new \Twig\TwigFilter('cover', [$this, 'cover']),
            new \Twig\TwigFilter('maskable', [$this, 'maskable']),
            new \Twig\TwigFilter('dataurl', [$this, 'dataurl']),
            new \Twig\TwigFilter('dominant_color', [$this, 'dominantColor']),
            new \Twig\TwigFilter('lqip', [$this, 'lqip']),
            new \Twig\TwigFilter('webp', [$this, 'webp']),
            new \Twig\TwigFilter('avif', [$this, 'avif']),
            // content
            new \Twig\TwigFilter('slugify', [$this, 'slugifyFilter']),
            new \Twig\TwigFilter('excerpt', [$this, 'excerpt']),
            new \Twig\TwigFilter('excerpt_html', [$this, 'excerptHtml']),
            new \Twig\TwigFilter('markdown_to_html', [$this, 'markdownToHtml']),
            new \Twig\TwigFilter('toc', [$this, 'markdownToToc']),
            new \Twig\TwigFilter('json_decode', [$this, 'jsonDecode']),
            new \Twig\TwigFilter('yaml_parse', [$this, 'yamlParse']),
            new \Twig\TwigFilter('preg_split', [$this, 'pregSplit']),
            new \Twig\TwigFilter('preg_match_all', [$this, 'pregMatchAll']),
            new \Twig\TwigFilter('hex_to_rgb', [$this, 'hexToRgb']),
            new \Twig\TwigFilter('splitline', [$this, 'splitLine']),
            new \Twig\TwigFilter('iterable', [$this, 'iterable']),
            new \Twig\TwigFilter('highlight', [$this, 'highlight']),
            new \Twig\TwigFilter('unique', [$this, 'unique']),
            // date
            new \Twig\TwigFilter('duration_to_iso8601', ['\Cecil\Util\Date', 'durationToIso8601']),
            // deprecated
            new \Twig\TwigFilter(
                'html',
                [$this, 'html'],
                [
                    'needs_context' => true,
                    'deprecation_info' => new DeprecatedCallableInfo('', '', 'html function')
                ]
            ),
        ];
    }

    /**
     * {@inheritdoc}
     */
    public function getTests()
    {
        return [
            new \Twig\TwigTest('asset', [$this, 'isAsset']),
            new \Twig\TwigTest('image_large', [$this, 'isImageLarge']),
            new \Twig\TwigTest('image_square', [$this, 'isImageSquare']),
        ];
    }

    /**
     * Filters by Section.
     */
    public function filterBySection(PagesCollection $pages, string $section): CollectionInterface
    {
        return $this->filterBy($pages, 'section', $section);
    }

    /**
     * Filters a pages collection by variable's name/value.
     */
    public function filterBy(PagesCollection $pages, string $variable, string $value): CollectionInterface
    {
        $filteredPages = $pages->filter(function (Page $page) use ($variable, $value) {
            // is a dedicated getter exists?
            $method = 'get' . ucfirst($variable);
            if (method_exists($page, $method) && $page->$method() == $value) {
                return $page->getType() == Type::PAGE->value && !$page->isVirtual() && true;
            }
            // or a classic variable
            if ($page->getVariable($variable) == $value) {
                return $page->getType() == Type::PAGE->value && !$page->isVirtual() && true;
            }
        });

        return $filteredPages;
    }

    /**
     * Sorts a collection by title.
     */
    public function sortByTitle(\Traversable $collection): array
    {
        $sort = \SORT_ASC;

        $collection = iterator_to_array($collection);
        array_multisort(array_keys(/** @scrutinizer ignore-type */ $collection), $sort, \SORT_NATURAL | \SORT_FLAG_CASE, $collection);

array_keys($collection) cannot be passed to array_multisort() as the parameter $array expects a reference.

SORT_NATURAL | SORT_FLAG_CASE cannot be passed to array_multisort() as the parameter $rest expects a reference.

        return $collection;
    }

    /**
     * Sorts a collection by weight.
     *
     * @param \Traversable|array $collection
     */
    public function sortByWeight($collection): array
    {
        $callback = function ($a, $b) {
            if (!isset($a['weight'])) {
                $a['weight'] = 0;
            }
            if (!isset($b['weight'])) {
                $a['weight'] = 0;
            }
            if ($a['weight'] == $b['weight']) {
                return 0;
            }

            return $a['weight'] < $b['weight'] ? -1 : 1;
        };

        if (!\is_array($collection)) {
            $collection = iterator_to_array($collection);
        }
        usort(/** @scrutinizer ignore-type */ $collection, $callback);

        return $collection;
    }

    /**
     * Sorts by creation date (or 'updated' date): the most recent first.
     */
    public function sortByDate(\Traversable $collection, string $variable = 'date', bool $descTitle = false): array
    {
        $callback = function ($a, $b) use ($variable, $descTitle) {
            if ($a[$variable] == $b[$variable]) {
                // if dates are equal and "descTitle" is true
                if ($descTitle && (isset($a['title']) && isset($b['title']))) {
                    return strnatcmp($b['title'], $a['title']);
                }

                return 0;
            }

            return $a[$variable] > $b[$variable] ? -1 : 1;
        };

        $collection = iterator_to_array($collection);
        usort(/** @scrutinizer ignore-type */ $collection, $callback);

        return $collection;
    }

    /**
     * Creates an URL.
     *
     * $options[
     *     'canonical' => false,
     *     'format'    => 'html',
     *     'language'  => null,
     * ];
     *
     * @param array                  $context
     * @param Page|Asset|string|null $value
     * @param array|null             $options
     */
    public function url(array $context, $value = null, ?array $options = null): string
    {
        $optionsLang = [];
        $optionsLang['language'] = (string) $context['site']['language'];
        $options = array_merge($optionsLang, $options ?? []);

        return (new Url($this->builder, $value, $options))->getUrl();
    }

    /**
     * Creates an Asset (CSS, JS, images, etc.) from a path or an array of paths.
     *
     * @param string|array $path    File path or array of files path (relative from `assets/` or `static/` dir).
     * @param array|null   $options
     *
     * @return Asset
     */
    public function asset($path, array|null $options = null): Asset
    {
        if (!\is_string($path) && !\is_array($path)) {
            throw new RuntimeException(\sprintf('Argument of "%s()" must a string or an array.', \Cecil\Util::formatMethodName(__METHOD__)));
        }

        return new Asset($this->builder, $path, $options);
    }

    /**
     * Compiles a SCSS asset.
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function toCss($asset): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->compile();
    }

    /**
     * Minifying an asset (CSS or JS).
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function minify($asset): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->minify();
    }

    /**
     * Fingerprinting an asset.
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function fingerprint($asset): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->fingerprint();
    }

    /**
     * Resizes an image.
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function resize($asset, int $size): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->resize($size);
    }

    /**
     * Crops an image Asset to the given width and height, keeping the aspect ratio.
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function cover($asset, int $width, int $height): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->cover($width, $height);
    }

    /**
     * Creates a maskable icon from an image asset.
     * The maskable icon is used for Progressive Web Apps (PWAs).
     *
     * @param string|Asset $asset
     *
     * @return Asset
     */
    public function maskable($asset, ?int $padding = null): Asset
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->maskable($padding);
    }

    /**
     * Returns the data URL of an image.
     *
     * @param string|Asset $asset
     *
     * @return string
     */
    public function dataurl($asset): string
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->dataurl();
    }

    /**
     * Hashing an asset with algo (sha384 by default).
     *
     * @param string|Asset $asset
     * @param string       $algo
     *
     * @return string
     */
    public function integrity($asset, string $algo = 'sha384'): string
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return $asset->getIntegrity($algo);
    }

    /**
     * Minifying a CSS string.
     */
    public function minifyCss(?string $value): string
    {
        $value = $value ?? '';

        if ($this->builder->isDebug()) {
            return $value;
        }

        $cache = new Cache($this->builder, 'assets');
        $cacheKey = $cache->createKeyFromValue(null, $value);
        if (!$cache->has($cacheKey)) {
            $minifier = new Minify\CSS($value);
            $value = $minifier->minify();
            $cache->set($cacheKey, $value, $this->config->get('cache.assets.ttl'));
        }

        return $cache->get($cacheKey, $value);
    }

    /**
     * Minifying a JavaScript string.
     */
    public function minifyJs(?string $value): string
    {
        $value = $value ?? '';

        if ($this->builder->isDebug()) {
            return $value;
        }

        $cache = new Cache($this->builder, 'assets');
        $cacheKey = $cache->createKeyFromValue(null, $value);
        if (!$cache->has($cacheKey)) {
            $minifier = new Minify\JS($value);
            $value = $minifier->minify();
            $cache->set($cacheKey, $value, $this->config->get('cache.assets.ttl'));
        }

        return $cache->get($cacheKey, $value);
    }

    /**
     * Compiles a SCSS string.
     *
     * @throws RuntimeException
     */
    public function scssToCss(?string $value): string
    {
        $value = $value ?? '';

        $cache = new Cache($this->builder, 'assets');
        $cacheKey = $cache->createKeyFromValue(null, $value);
        if (!$cache->has($cacheKey)) {
            $scssPhp = new Compiler();
            $outputStyles = ['expanded', 'compressed'];
            $outputStyle = strtolower((string) $this->config->get('assets.compile.style'));
            if (!\in_array($outputStyle, $outputStyles)) {
                throw new ConfigException(\sprintf('"%s" value must be "%s".', 'assets.compile.style', implode('" or "', $outputStyles)));
            }
            $scssPhp->setOutputStyle($outputStyle == 'compressed' ? OutputStyle::COMPRESSED : OutputStyle::EXPANDED);
            $variables = $this->config->get('assets.compile.variables');
            if (!empty($variables)) {
                $variables = array_map('ScssPhp\ScssPhp\ValueConverter::parseValue', $variables);
                $scssPhp->replaceVariables($variables);
            }
            $value = $scssPhp->compileString($value)->getCss();
            $cache->set($cacheKey, $value, $this->config->get('cache.assets.ttl'));
        }

        return $cache->get($cacheKey, $value);
    }

    /**
     * Creates the HTML element of an asset.
     *
     * $options[
     *     'preload'    => false,
     *     'responsive' => false,
     *     'formats'    => [],
     * ];
     *
     * @throws RuntimeException
     */
    public function html(array $context, Asset $asset, array $attributes = [], array $options = []): string
    {
        $htmlAttributes = '';
        $preload = false;
        $responsive = $this->config->isEnabled('layouts.images.responsive');
        $formats = (array) $this->config->get('layouts.images.formats');
        extract($options, EXTR_IF_EXISTS);

        // builds HTML attributes
        foreach ($attributes as $name => $value) {
            $attribute = \sprintf(' %s="%s"', $name, $value);
            if (!isset($value)) {
                $attribute = \sprintf(' %s', $name);
            }
            $htmlAttributes .= $attribute;
        }

        // be sure Asset file is saved
        $asset->save();

        // CSS or JavaScript
        switch ($asset['ext']) {
            case 'css':
                if ($preload) {
                    return \sprintf(
                        '<link href="%s" rel="preload" as="style" onload="this.onload=null;this.rel=\'stylesheet\'"%s><noscript><link rel="stylesheet" href="%1$s"%2$s></noscript>',
                        $this->url($context, $asset, $options),
                        $htmlAttributes
                    );
                }

                return \sprintf('<link rel="stylesheet" href="%s"%s>', $this->url($context, $asset, $options), $htmlAttributes);
            case 'js':
                return \sprintf('<script src="%s"%s></script>', $this->url($context, $asset, $options), $htmlAttributes);
        }
        // image
        if ($asset['type'] == 'image') {
            // if responsive is enabled
            $sizes = '';
            if (
                $responsive && $srcset = Image::buildHtmlSrcset(
                    $asset,
                    $this->config->getAssetsImagesWidths()
                )
            ) {
                $htmlAttributes .= \sprintf(' srcset="%s"', $srcset);
                $sizes = Image::getHtmlSizes($attributes['class'] ?? '', $this->config->getAssetsImagesSizes());
                $htmlAttributes .= \sprintf(' sizes="%s"', $sizes);
                if ($asset['width'] > max($this->config->getAssetsImagesWidths())) {
                    $asset = $asset->resize(max($this->config->getAssetsImagesWidths()));
                }
            }

            // `<img>` element
            $img = \sprintf(
                '<img src="%s" width="' . ($asset['width'] ?: '') . '" height="' . ($asset['height'] ?: '') . '"%s>',
                $this->url($context, $asset, $options),
                $htmlAttributes
            );

            // multiple formats (`<source>`)?
            if (\count($formats) > 0) {
                $source = '';
                foreach ($formats as $format) {
                    try {
                        $assetConverted = $asset->convert($format);
                        // if responsive is enabled
                        if ($responsive && $srcset = Image::buildHtmlSrcset($assetConverted, $this->config->getAssetsImagesWidths())) {
                            // `<source>` element
                            $source .= \sprintf(
                                "\n  <source type=\"image/$format\" srcset=\"%s\" sizes=\"%s\">",
                                $srcset,
                                $sizes
                            );
                            continue;
                        }
                        // `<source>` element
                        $source .= \sprintf("\n  <source type=\"image/$format\" srcset=\"%s\">", $assetConverted);
                    } catch (\Exception $e) {
                        $this->builder->getLogger()->error($e->getMessage());
                        continue;
                    }
                }
                // put `<source>` in `<picture>`
                if (!empty($source)) {
                    return \sprintf("<picture>%s\n  %s\n</picture>", $source, $img);
                }
            }

            return $img;
        }

        throw new RuntimeException(\sprintf('%s is available for CSS, JavaScript and images files only.', '"html" filter'));
    }

    /**
     * Builds the HTML img `srcset` (responsive) attribute of an image Asset.
     *
     * @throws RuntimeException
     */
    public function imageSrcset(Asset $asset): string
    {
        return Image::buildHtmlSrcset($asset, $this->config->getAssetsImagesWidths(), true);
    }

    /**
     * Returns the HTML img `sizes` attribute based on a CSS class name.
     */
    public function imageSizes(string $class): string
    {
        return Image::getHtmlSizes($class, $this->config->getAssetsImagesSizes());
    }

    /**
     * Converts an image Asset to WebP format.
     */
    public function webp(Asset $asset, ?int $quality = null): Asset
    {
        return $this->convert($asset, 'webp', $quality);
    }

    /**
     * Converts an image Asset to AVIF format.
     */
    public function avif(Asset $asset, ?int $quality = null): Asset
    {
        return $this->convert($asset, 'avif', $quality);
    }

    /**
     * Converts an image Asset to the given format.
     *
     * @throws RuntimeException
     */
    private function convert(Asset $asset, string $format, ?int $quality = null): Asset
    {
        if ($asset['subtype'] == "image/$format") {
            return $asset;
        }
        if (Image::isAnimatedGif($asset)) {
            throw new RuntimeException(\sprintf('Unable to convert the animated GIF "%s" to %s.', $asset['path'], $format));
        }

        try {
            return $asset->$format($quality);
        } catch (\Exception $e) {
            throw new RuntimeException(\sprintf('Unable to convert "%s" to %s (%s).', $asset['path'], $format, $e->getMessage()));
        }
    }

    /**
     * Returns the content of an asset.
     */
    public function inline(Asset $asset): string
    {
        return $asset['content'];
    }

    /**
     * Reads $length first characters of a string and adds a suffix.
     */
    public function excerpt(?string $string, int $length = 450, string $suffix = ' …'): string
    {
        $string = $string ?? '';

        $string = str_replace('</p>', '<br><br>', $string);
        $string = trim(strip_tags($string, '<br>'));
        if (mb_strlen($string) > $length) {
            $string = mb_substr($string, 0, $length);
            $string .= $suffix;
        }

        return $string;
    }

    /**
     * Reads characters before or after '<!-- separator -->'.
     * Options:
     *  - separator: string to use as separator (`excerpt|break` by default)
     *  - capture: part to capture, `before` or `after` the separator (`before` by default).
     */
    public function excerptHtml(?string $string, array $options = []): string
    {
        $string = $string ?? '';

        $separator = (string) $this->config->get('pages.body.excerpt.separator');
        $capture = (string) $this->config->get('pages.body.excerpt.capture');
        extract($options, EXTR_IF_EXISTS);

        // https://regex101.com/r/n9TWHF/1
        $pattern = '(.*)<!--[[:blank:]]?(' . $separator . ')[[:blank:]]?-->(.*)';
        preg_match('/' . $pattern . '/is', $string, $matches);

        if (empty($matches)) {
            return $string;
        }
        $result = trim($matches[1]);
        if ($capture == 'after') {
            $result = trim($matches[3]);
        }
        // removes footnotes and returns result
        return preg_replace('/<sup[^>]*>[^u]*<\/sup>/', '', $result);
    }

    /**
     * Converts a Markdown string to HTML.
     *
     * @throws RuntimeException
     */
    public function markdownToHtml(?string $markdown): ?string
    {
        $markdown = $markdown ?? '';

        try {
            $parsedown = new Parsedown($this->builder);
            $html = $parsedown->text($markdown);
        } catch (\Exception $e) {
            throw new RuntimeException(
                '"markdown_to_html" filter can not convert supplied Markdown.',
                previous: $e
            );
        }

        return $html;
    }

    /**
     * Extract table of content of a Markdown string,
     * in the given format ("html" or "json", "html" by default).
     *
     * @throws RuntimeException
     */
    public function markdownToToc(?string $markdown, $format = 'html', ?array $selectors = null, string $url = ''): ?string
    {
        $markdown = $markdown ?? '';
        $selectors = $selectors ?? (array) $this->config->get('pages.body.toc');

        try {
            $parsedown = new Parsedown($this->builder, ['selectors' => $selectors, 'url' => $url]);
            $parsedown->body($markdown);
            $return = $parsedown->contentsList($format);
        } catch (\Exception) {
            throw new RuntimeException('"toc" filter can not convert supplied Markdown.');
        }

        return $return;
    }

    /**
     * Converts a JSON string to an array.
     *
     * @throws RuntimeException
     */
    public function jsonDecode(?string $json): ?array
    {
        $json = $json ?? '';

        try {
            $array = json_decode($json, true);
            if ($array === null && json_last_error() !== JSON_ERROR_NONE) {
                throw new \Exception('JSON error.');
            }
        } catch (\Exception) {
            throw new RuntimeException('"json_decode" filter can not parse supplied JSON.');
        }

        return $array;
    }

    /**
     * Converts a YAML string to an array.
     *
     * @throws RuntimeException
     */
    public function yamlParse(?string $yaml): ?array
    {
        $yaml = $yaml ?? '';

        try {
            $array = Yaml::parse($yaml, Yaml::PARSE_DATETIME);
            if (!\is_array($array)) {
                throw new ParseException('YAML error.');
            }
        } catch (ParseException $e) {
            throw new RuntimeException(\sprintf('"yaml_parse" filter can not parse supplied YAML: %s', $e->getMessage()));
        }

        return $array;
    }

    /**
     * Split a string into an array using a regular expression.
     *
     * @throws RuntimeException
     */
    public function pregSplit(?string $value, string $pattern, int $limit = 0): ?array
    {
        $value = $value ?? '';

        try {
            $array = preg_split($pattern, $value, $limit);
            if ($array === false) {
                throw new RuntimeException('PREG split error.');
            }
        } catch (\Exception) {
            throw new RuntimeException('"preg_split" filter can not split supplied string.');
        }

        return $array;
    }

    /**
     * Perform a regular expression match and return the group for all matches.
     *
     * @throws RuntimeException
     */
    public function pregMatchAll(?string $value, string $pattern, int $group = 0): ?array
    {
        $value = $value ?? '';

        try {
            $array = preg_match_all($pattern, $value, $matches, PREG_PATTERN_ORDER);
            if ($array === false) {
                throw new RuntimeException('PREG match all error.');
            }
        } catch (\Exception) {
            throw new RuntimeException('"preg_match_all" filter can not match in supplied string.');
        }

        return $matches[$group];
    }

    /**
     * Calculates estimated time to read a text.
     */
    public function readtime(?string $text): string
    {
        $text = $text ?? '';

        $words = str_word_count(strip_tags($text));
        $min = floor($words / 200);
        if ($min === 0) {
            return '1';
        }

        return (string) $min;
    }

    /**
     * Gets the value of an environment variable.
     */
    public function getEnv(?string $var): ?string
    {
        $var = $var ?? '';

        return getenv($var) ?: null;
    }

    /**
     * Dump variable (or Twig context).
     */
    public function varDump(\Twig\Environment $env, array $context, $var = null, ?array $options = null): void
    {
        if (!$env->isDebug()) {
            return;
        }

        if ($var === null) {
            $var = array();
            foreach ($context as $key => $value) {
                if (!$value instanceof \Twig\Template && !$value instanceof \Twig\TemplateWrapper) {
                    $var[$key] = $value;
                }
            }
        }

        $cloner = new VarCloner();
        $cloner->setMinDepth(3);
        $dumper = new HtmlDumper();
        $dumper->setTheme($options['theme'] ?? 'light');

        $data = $cloner->cloneVar($var)->withMaxDepth(3);
        $dumper->dump($data, null, ['maxDepth' => 3]);
    }

    /**
     * Tests if a variable is an Asset.
     */
    public function isAsset($variable): bool
    {
        return $variable instanceof Asset;
    }

    /**
     * Tests if an image Asset is large enough to be used as a cover image.
     * A large image is defined as having a width >= 600px and height >= 315px.
     */
    public function isImageLarge(Asset $asset): bool
    {
        return $asset['type'] == 'image' && $asset['width'] > $asset['height'] && $asset['width'] >= 600 && $asset['height'] >= 315;
    }

    /**
     * Tests if an image Asset is square.
     * A square image is defined as having the same width and height.
     */
    public function isImageSquare(Asset $asset): bool
    {
        return $asset['type'] == 'image' && $asset['width'] == $asset['height'];
    }

    /**
     * Returns the dominant hex color of an image asset.
     *
     * @param string|Asset $asset
     *
     * @return string
     */
    public function dominantColor($asset): string
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return Image::getDominantColor($asset);
    }

    /**
     * Returns a Low Quality Image Placeholder (LQIP) as data URL.
     *
     * @param string|Asset $asset
     *
     * @return string
     */
    public function lqip($asset): string
    {
        if (!$asset instanceof Asset) {
            $asset = new Asset($this->builder, $asset);
        }

        return Image::getLqip($asset);
    }

    /**
     * Converts an hexadecimal color to RGB.
     *
     * @throws RuntimeException
     */
    public function hexToRgb(?string $variable): array
    {
        $variable = $variable ?? '';

        if (!self::isHex($variable)) {
            throw new RuntimeException(\sprintf('"%s" is not a valid hexadecimal value.', $variable));
        }
        $hex = ltrim($variable, '#');
        if (\strlen($hex) == 3) {
            $hex = $hex[0] . $hex[0] . $hex[1] . $hex[1] . $hex[2] . $hex[2];
        }
        $c = hexdec($hex);

        return [
            'red'   => $c >> 16 & 0xFF,
            'green' => $c >> 8 & 0xFF,
            'blue'  => $c & 0xFF,
        ];
    }

    /**
     * Split a string in multiple lines.
     */
    public function splitLine(?string $variable, int $max = 18): array
    {
        $variable = $variable ?? '';

        return preg_split("/.{0,{$max}}\K(\s+|$)/", $variable, 0, PREG_SPLIT_NO_EMPTY);
    }

    /**
     * Hashing an object, an array or a string (with algo, md5 by default).
     */
    public function hash(object|array|string $data, $algo = 'md5'): string
    {
        switch (\gettype($data)) {
            case 'object':
                return spl_object_hash($data);
            case 'array':
                return hash($algo, serialize($data));
        }

        return hash($algo, $data);
    }

    /**
     * Converts a variable to an iterable (array).
     */
    public function iterable($value): array
    {
        if (\is_array($value)) {
            return $value;
        }
        if (\is_string($value)) {
            return [$value];
        }
        if ($value instanceof \Traversable) {
            return iterator_to_array($value);
        }
        if ($value instanceof \stdClass) {
            return (array) $value;
        }
        if (\is_object($value)) {
            return [$value];
        }
        if (\is_int($value) || \is_float($value)) {
            return [$value];
        }
        return [$value];
    }

    /**
     * Highlights a code snippet.
     */
    public function highlight(string $code, string $language): string
    {
        return (new Highlighter())->highlight($language, $code)->value;
    }

    /**
     * Returns an array with unique values.
     */
    public function unique(array $array): array
    {
        return array_intersect_key($array, array_unique(array_map('strtolower', $array), SORT_STRING));
    }

    /**
     * Is a hexadecimal color is valid?
     */
    private static function isHex(string $hex): bool
    {
        $valid = \is_string($hex);
        $hex = ltrim($hex, '#');
        $length = \strlen($hex);
        $valid = $valid && ($length === 3 || $length === 6);
        $valid = $valid && ctype_xdigit($hex);

        return $valid;
    }
}