class IconFinder

class IconFinder implements ContainerInjectionInterface, IconFinderInterface {
    use AutowireTrait;
    
    /**
     * Pattern to match a group placeholder in a source path.
     *
     * This constant is used to identify and extract group metadata from source
     * paths defined for icon pack.
     */
    private const GROUP_PATTERN = '{group}';
    
    /**
     * Pattern to match an icon ID placeholder in a filename.
     *
     * This constant is used to identify and extract icon IDs from filenames
     * within source paths defined for icon pack.
     */
    private const ICON_ID_PATTERN = '{icon_id}';
    
    /**
     * List of allowed file extensions for local icon files.
     *
     * This restriction is in place for security reasons, so a definition can not
     * be used to expose the content of a non image to the extractor.
     * Furthermore it make no sense to use other file format as Icons.
     */
    private const ALLOWED_EXTENSION = [
        'svg',
        'png',
        'gif',
    ];
    
    /**
     * Constructs a new IconFinder object.
     *
     * @param \Drupal\Core\File\FileUrlGeneratorInterface $fileUrlGenerator
     *   The file URL generator service.
     * @param \Psr\Log\LoggerInterface $logger
     *   A logger instance.
     * @param string $appRoot
     *   The application root.
     */
    public function __construct(FileUrlGeneratorInterface $fileUrlGenerator, LoggerInterface $logger, string $appRoot) {
    }
    
    /**
     * {@inheritdoc}
     */
    public function getFileContents(string $uri) : string|bool {
        $url = parse_url($uri);
        if (isset($url['scheme']) || isset($url['host'])) {
            return FALSE;
        }
        if (!file_exists($uri)) {
            return FALSE;
        }
        return file_get_contents($uri);
    }
    
    /**
     * {@inheritdoc}
     */
    public function getFilesFromSources(array $sources, string $relative_path) : array {
        $result = [];
        foreach ($sources as $source) {
            // Detect if source is path or remote, parse_url will have no scheme for
            // a path.
            $url = parse_url($source);
            if (isset($url['scheme']) && isset($url['path'])) {
                $result = array_merge($result, $this->getFileFromUrl($url['scheme'], $url['path'], $source));
                continue;
            }
            $result = array_merge($result, $this->getFilesFromPath($source, $relative_path));
        }
        return $result;
    }
    
    /**
     * Get filename from an URL source.
     *
     * Because url to an image can be of various form, there is no extension
     * validation, only scheme, the extractor must handle the constraints.
     *
     * @param string $scheme
     *   The url scheme from parse_url().
     * @param string $path
     *   The url path from parse_url().
     * @param string $source
     *   The source.
     *
     * @return array<string, array<string, string|null>>
     *   The file discovered.
     */
    private function getFileFromUrl(string $scheme, string $path, string $source) : array {
        if (!in_array($scheme, UrlHelper::getAllowedProtocols(), TRUE)) {
            $this->logger
                ->warning('Invalid icon source: @source', [
                '@source' => $source,
            ]);
            return [];
        }
        // Decode url to have cleaner filename.
        $icon_id = pathinfo(urldecode($path), PATHINFO_FILENAME);
        // Icon ID is used as index to avoid duplicates.
        return [
            $icon_id => [
                'icon_id' => $icon_id,
                'source' => $source,
                'absolute_path' => $source,
            ],
        ];
    }
    
    /**
     * Get files from a local path.
     *
     * This is a wrapper to use Symfony Finder with 2 extras features {group} and
     * {icon_id}.
     *
     * @param string $source
     *   The source path, which can be absolute (starting with '/') or relative
     *   to the definition folder.
     * @param string $relative_path
     *   The relative path to the definition folder.
     *
     * @return array<string, array<string, string|null>>
     *   The file discovered.
     */
    private function getFilesFromPath(string $source, string $relative_path) : array {
        $path_info = pathinfo($source);
        $dirname = $path_info['dirname'] ?? '';
        $extension = $path_info['extension'] ?? '';
        $filename = $path_info['filename'] ?? '';
        if (empty($dirname)) {
            return [];
        }
        // Set extension to wildcard if empty, and validate against allowed
        // extensions.
        $extension = empty($extension) ? '*' : $extension;
        if ('*' !== $extension && !in_array($extension, self::ALLOWED_EXTENSION, TRUE)) {
            $this->logger
                ->warning('Invalid icon path extension @filename.@extension in source: @source', [
                '@filename' => $filename,
                '@extension' => $extension,
                '@source' => $source,
            ]);
            return [];
        }
        // Use allowed extension bracket for Finder if wildcard.
        $extension = '*' === $extension ? '{' . implode(',', self::ALLOWED_EXTENSION) . '}' : $extension;
        // Prepare filename wildcard if empty or with {icon_id} pattern.
        $filename_wildcard = empty($filename) ? '*' : str_replace(self::ICON_ID_PATTERN, '*', $filename);
        // If icons are in the same folder dirname is 'dot'.
        if ('.' === $dirname) {
            $dirname = '';
        }
        // Prepare path to search for icons for Finder::in().
        $path = str_starts_with($source, '/') ? $this->appRoot . $dirname : sprintf('%s/%s/%s', $this->appRoot, $relative_path, $dirname);
        // Prepare file names for Finder::name().
        $names = sprintf('%s.%s', $filename_wildcard, $extension);
        if (!($finder = $this->findFiles($path, $names))) {
            return [];
        }
        // Wildcard around filename are ignored for extractIconIdFromFilename.
        $filename = str_replace('*', '', $filename);
        return $this->processFoundFiles($finder, $source, $filename, self::determineGroupPosition($path));
    }
    
    /**
     * Creates a Finder instance with configured patterns and return result.
     *
     * @param string $path
     *   The path to search for icons.
     * @param string $names
     *   The file names for Finder::names().
     *
     * @return \Symfony\Component\Finder\Finder|null
     *   The configured Finder instance.
     */
    private function findFiles(string $path, string $names) : ?Finder {
        $path = str_replace(self::GROUP_PATTERN, '*', $path);
        $finder = new Finder();
        try {
            $finder->depth(0)
                ->in($path)
                ->files()
                ->name($names)
                ->sortByExtension();
        } catch (\Throwable) {
            $this->logger
                ->warning('Invalid icon path in source: @source', [
                '@source' => $path,
            ]);
            return NULL;
        }
        if (!$finder->hasResults()) {
            $this->logger
                ->warning('No icon found in source: @source', [
                '@source' => $path,
            ]);
            return NULL;
        }
        return $finder;
    }
    
    /**
     * Process files and format icon information.
     *
     * @param \Symfony\Component\Finder\Finder $finder
     *   The Finder instance with found files.
     * @param string $source
     *   The source.
     * @param string $path_info_filename
     *   The filename from path_info().
     * @param int|null $group_position
     *   The position of the group in the path, or null if not applicable.
     *
     * @return array<string, array<string, string|null>>
     *   List of files with metadata.
     */
    private function processFoundFiles(Finder $finder, string $source, string $path_info_filename, ?int $group_position) : array {
        $result = [];
        $has_icon_pattern = \str_contains($path_info_filename, self::ICON_ID_PATTERN);
        foreach ($finder as $file) {
            $file_absolute_path = $file->getPathName();
            $icon_id = $file->getFilenameWithoutExtension();
            // If an {icon_id} pattern is used, extract it to be used.
            if ($has_icon_pattern) {
                $icon_id = self::extractIconIdFromFilename($icon_id, $path_info_filename);
            }
            // Icon ID is used as index to avoid duplicates.
            $result[$icon_id] = [
                'icon_id' => $icon_id,
                'source' => $this->fileUrlGenerator
                    ->generateString(str_replace($this->appRoot, '', $file_absolute_path)),
                'absolute_path' => $file_absolute_path,
                'group' => self::extractGroupFromPath($file->getPath(), $group_position),
            ];
        }
        return $result;
    }
    
    /**
     * Check if {icon_id} is a part of the name and need to be extracted.
     *
     * @param string $filename
     *   The filename found to match against.
     * @param string $filename_pattern
     *   The path with {icon_id}.
     *
     * @return string
     *   The extracted icon ID or the original filename.
     */
    private static function extractIconIdFromFilename(string $filename, string $filename_pattern) : string {
        $pattern = str_replace(self::ICON_ID_PATTERN, '(?<icon_id>.+)?', $filename_pattern);
        if (preg_match('@' . $pattern . '@', $filename, $matches)) {
            return $matches['icon_id'] ?? $filename;
        }
        return $filename;
    }
    
    /**
     * Extracts the group from a file path based on the group position.
     *
     * @param string $path
     *   The file path.
     * @param int|null $group_position
     *   The position of the group in the path, or null if not applicable.
     *
     * @return string|null
     *   The extracted group, or null if not found.
     */
    private static function extractGroupFromPath(string $path, ?int $group_position) : ?string {
        $parts = explode('/', trim($path, '/'));
        return $parts[$group_position] ?? NULL;
    }
    
    /**
     * Determines the group position based on the URI.
     *
     * The group position is needed to use it as a mask to find the folder name
     * matching this position.
     *
     * @param string $source
     *   The source with optional group pattern.
     *
     * @return int|null
     *   The determined group position.
     */
    private static function determineGroupPosition(string $source) : ?int {
        $parts = explode('/', trim($source, '/'));
        if ($result = array_search(self::GROUP_PATTERN, $parts, TRUE)) {
            return (int) $result;
        }
        return NULL;
    }

}