KevinGH\Box\Configuration

Complexity

Total Complexity

230

Size/Duplication

Total Lines	1836
Duplicated Lines	0 %

Importance

Changes

0

90 Methods

Rating	Name	Duplication	Size	Complexity
A	retrieveGitHash()	0	8	2
A	retrieveGitTag()	0	3	1
B	retrieveDatetimeFormat()	0	29	5
A	getStubBannerContents()	0	3	1
A	getFileMapper()	0	3	1
A	retrieveMainScriptContents()	0	11	2
A	getFile()	0	3	1
A	retrieveMetadata()	0	11	3
A	retrieveGitHashPlaceholder()	0	3	2
A	retrieveDatetimeNow()	0	5	1
B	retrieveCompactors()	0	38	6
B	retrieveMainScriptPath()	0	23	6
B	retrieveFiles()	0	50	6
A	getTmpOutputPath()	0	3	1
A	getShebang()	0	3	1
A	checkRequirements()	0	3	1
A	getBinaryFiles()	0	3	1
A	retrieveStubBannerContents()	0	17	4
A	createPhpCompactor()	0	12	3
A	getComposerJson()	0	3	1
A	normalizePath()	0	3	1
A	retrieveDumpAutoload()	0	8	2
A	excludeComposerFiles()	0	3	1
B	retrieveOutputPath()	0	22	5
A	retrieveIsInterceptFileFuncs()	0	7	2
A	retrieveFilesFromFinders()	0	12	2
A	getStubBannerPath()	0	3	1
A	dumpAutoload()	0	3	1
A	retrieveBlacklistFilter()	0	21	4
A	isInterceptFileFuncs()	0	3	1
A	retrieveGitTagPlaceholder()	0	3	2
A	getFileMode()	0	3	1
A	retrieveAlias()	0	11	2
A	retrieveReplacementSigil()	0	3	2
A	retrievePrivateKeyPassphrase()	0	10	3
A	retrieveBasePath()	0	18	3
A	getMainScriptPath()	0	8	1
B	retrieveMap()	0	25	5
A	getReplacements()	0	3	1
A	getAlias()	0	3	1
B	retrieveAllFiles()	0	109	3
A	getStubPath()	0	3	1
A	retrieveStubBannerPath()	0	11	2
F	retrieveReplacements()	0	44	10
A	retrievePhpScoperConfig()	0	21	3
A	getBasePath()	0	3	1
A	retrieveCheckRequirements()	0	9	3
A	retrieveBlacklist()	0	16	2
A	retrievePrettyGitTag()	0	9	2
A	retrieveIsStubGenerated()	0	3	3
A	retrieveSigningAlgorithm()	0	19	3
A	retrieveExcludeComposerFiles()	0	3	1
A	retrieveShebang()	0	22	3
A	getComposerLock()	0	3	1
A	isStubGenerated()	0	3	1
A	retrieveFilesAggregate()	0	11	3
A	getSigningAlgorithm()	0	3	1
A	runGitCommand()	0	15	2
A	getCompressionAlgorithm()	0	3	1
A	retrieveIsPrivateKeyPrompt()	0	3	2
A	getPrivateKeyPassphrase()	0	3	1
A	normalizeStubBannerContents()	0	10	2
A	shouldRetrieveAllFiles()	0	16	4
A	getFiles()	0	3	1
F	retrieveAllDirectoriesToInclude()	0	152	23
A	retrievePrettyGitPlaceholder()	0	3	2
A	retrieveGitVersionPlaceholder()	0	3	2
A	hasMainScript()	0	3	1
A	retrievePrivateKeyPath()	0	10	2
D	processFinder()	0	119	14
B	retrieveDirectories()	0	25	3
A	getMetadata()	0	3	1
A	getOutputPath()	0	3	1
A	processFinders()	0	11	1
A	retrieveGitVersion()	0	16	3
B	retrieveCompressionAlgorithm()	0	25	3
B	retrieveDirectoryPaths()	0	33	3
A	retrieveFileMode()	0	7	2
B	__construct()	0	77	2
A	getPrivateKeyPath()	0	3	1
A	isPrivateKeyPrompt()	0	3	1
A	getDecodedComposerJsonContents()	0	3	1
B	retrieveComposerFiles()	0	32	5
A	retrieveGitShortHashPlaceholder()	0	3	2
A	retrieveStubPath()	0	11	3
A	retrieveDatetimeNowPlaceHolder()	0	3	2
A	getDecodedComposerLockContents()	0	3	1
B	create()	0	134	3
A	getMainScriptContents()	0	8	1
A	getCompactors()	0	3	1

<?php

declare(strict_types=1);

/*
 * This file is part of the box project.
 *
 * (c) Kevin Herrera <kevin@herrera.io>
 *     Théo Fidry <theo.fidry@gmail.com>
 *
 * This source file is subject to the MIT license that is bundled
 * with this source code in the file LICENSE.
 */

namespace KevinGH\Box;

use Assert\Assertion;
use Closure;
use DateTimeImmutable;
use DateTimeZone;
use Herrera\Annotations\Tokenizer;
use Herrera\Box\Compactor\Php as LegacyPhp;
use Humbug\PhpScoper\Configuration as PhpScoperConfiguration;
use InvalidArgumentException;
use KevinGH\Box\Compactor\Php;
use KevinGH\Box\Compactor\PhpScoper as PhpScoperCompactor;
use KevinGH\Box\Composer\ComposerConfiguration;
use KevinGH\Box\Json\Json;
use KevinGH\Box\PhpScoper\SimpleScoper;
use Phar;
use RuntimeException;
use Seld\JsonLint\ParsingException;
use SplFileInfo;
use stdClass;
use Symfony\Component\Finder\Finder;
use Symfony\Component\Process\Process;
use const E_USER_DEPRECATED;
use function array_column;
use function array_diff;
use function array_filter;
use function array_key_exists;
use function array_map;
use function array_merge;
use function array_unique;
use function file_exists;
use function Humbug\PhpScoper\create_scoper;
use function is_array;
use function is_bool;
use function is_file;
use function is_link;
use function is_readable;
use function iter\fn\method;
use function iter\map;
use function iter\toArray;
use function iter\values;
use function KevinGH\Box\FileSystem\canonicalize;
use function KevinGH\Box\FileSystem\file_contents;
use function KevinGH\Box\FileSystem\is_absolute_path;
use function KevinGH\Box\FileSystem\longest_common_base_path;
use function KevinGH\Box\FileSystem\make_path_absolute;
use function KevinGH\Box\FileSystem\make_path_relative;
use function preg_match;
use function sprintf;
use function substr;
use function trigger_error;
use function uniqid;

/**
 * @private
 */
final class Configuration
{
    private const DEFAULT_ALIAS = 'test.phar';
    private const DEFAULT_MAIN_SCRIPT = 'index.php';
    private const DEFAULT_DATETIME_FORMAT = 'Y-m-d H:i:s';
    private const DEFAULT_REPLACEMENT_SIGIL = '@';
    private const DEFAULT_SHEBANG = '#!/usr/bin/env php';
    private const DEFAULT_BANNER = <<<'BANNER'
Generated by Humbug Box.

@link https://github.com/humbug/box
BANNER;
    private const FILES_SETTINGS = [
        'directories',
        'finder',
    ];
    private const PHP_SCOPER_CONFIG = 'scoper.inc.php';

    private $file;
    private $fileMode;
    private $alias;
    private $basePath;
    private $composerJson;
    private $composerLock;
    private $files;
    private $binaryFiles;
    private $dumpAutoload;
    private $excludeComposerFiles;
    private $compactors;
    private $compressionAlgorithm;
    private $mainScriptPath;
    private $mainScriptContents;
    private $map;
    private $fileMapper;
    private $metadata;
    private $tmpOutputPath;
    private $outputPath;
    private $privateKeyPassphrase;
    private $privateKeyPath;
    private $isPrivateKeyPrompt;
    private $processedReplacements;
    private $shebang;
    private $signingAlgorithm;
    private $stubBannerContents;
    private $stubBannerPath;
    private $stubPath;
    private $isInterceptFileFuncs;
    private $isStubGenerated;
    private $checkRequirements;

    /**
     * @param null|string   $file
     * @param null|string   $alias
     * @param string        $basePath             Utility to private the base path used and be able to retrieve a
     *                                            path relative to it (the base path)
     * @param array         $composerJson         The first element is the path to the `composer.json` file as a
     *                                            string and the second element its decoded contents as an
     *                                            associative array.
     * @param array         $composerLock         The first element is the path to the `composer.lock` file as a
     *                                            string and the second element its decoded contents as an
     *                                            associative array.
     * @param SplFileInfo[] $files                List of files
     * @param SplFileInfo[] $binaryFiles          List of binary files
     * @param bool          $dumpAutoload         Whether or not the Composer autoloader should be dumped
     * @param bool          $excludeComposerFiles Whether or not the Composer files composer.json, composer.lock and
     *                                            installed.json should be removed from the PHAR
     * @param Compactor[]   $compactors           List of file contents compactors
     * @param null|int      $compressionAlgorithm Compression algorithm constant value. See the \Phar class constants
     * @param null|int      $fileMode             File mode in octal form
     * @param string        $mainScriptPath       The main script file path
     * @param string        $mainScriptContents   The processed content of the main script file
     * @param MapFile       $fileMapper           Utility to map the files from outside and inside the PHAR
     * @param mixed         $metadata             The PHAR Metadata
     * @param bool          $isPrivateKeyPrompt   If the user should be prompted for the private key passphrase
     * @param scalar[]      $replacements         The processed list of replacement placeholders and their values
     * @param null|string   $shebang              The shebang line
     * @param int           $signingAlgorithm     The PHAR siging algorithm. See \Phar constants
     * @param null|string   $stubBannerContents   The stub banner comment
     * @param null|string   $stubBannerPath       The path to the stub banner comment file
     * @param null|string   $stubPath             The PHAR stub file path
     * @param bool          $isInterceptFileFuncs Whether or not Phar::interceptFileFuncs() should be used
     * @param bool          $isStubGenerated      Whether or not if the PHAR stub should be generated
     * @param bool          $checkRequirements    Whether the PHAR will check the application requirements before
     *                                            running
     */
    private function __construct(
        ?string $file,
        string $alias,
        string $basePath,
        array $composerJson,
        array $composerLock,
        array $files,
        array $binaryFiles,
        bool $dumpAutoload,
        bool $excludeComposerFiles,
        array $compactors,
        ?int $compressionAlgorithm,
        ?int $fileMode,
        ?string $mainScriptPath,
        ?string $mainScriptContents,
        MapFile $fileMapper,
        $metadata,
        string $tmpOutputPath,
        string $outputPath,
        ?string $privateKeyPassphrase,
        ?string $privateKeyPath,
        bool $isPrivateKeyPrompt,
        array $replacements,
        ?string $shebang,
        int $signingAlgorithm,
        ?string $stubBannerContents,
        ?string $stubBannerPath,
        ?string $stubPath,
        bool $isInterceptFileFuncs,
        bool $isStubGenerated,
        bool $checkRequirements
    ) {
        Assertion::nullOrInArray(
            $compressionAlgorithm,
            get_phar_compression_algorithms(),
            sprintf(
                'Invalid compression algorithm "%%s", use one of "%s" instead.',
                implode('", "', array_keys(get_phar_compression_algorithms()))
            )
        );

        if (null === $mainScriptPath) {
            Assertion::null($mainScriptContents);
        } else {
            Assertion::notNull($mainScriptContents);
        }

        $this->file = $file;
        $this->alias = $alias;
        $this->basePath = $basePath;
        $this->composerJson = $composerJson;
        $this->composerLock = $composerLock;
        $this->files = $files;
        $this->binaryFiles = $binaryFiles;
        $this->dumpAutoload = $dumpAutoload;
        $this->excludeComposerFiles = $excludeComposerFiles;
        $this->compactors = $compactors;
        $this->compressionAlgorithm = $compressionAlgorithm;
        $this->fileMode = $fileMode;
        $this->mainScriptPath = $mainScriptPath;
        $this->mainScriptContents = $mainScriptContents;
        $this->fileMapper = $fileMapper;
        $this->metadata = $metadata;
        $this->tmpOutputPath = $tmpOutputPath;
        $this->outputPath = $outputPath;
        $this->privateKeyPassphrase = $privateKeyPassphrase;
        $this->privateKeyPath = $privateKeyPath;
        $this->isPrivateKeyPrompt = $isPrivateKeyPrompt;
        $this->processedReplacements = $replacements;
        $this->shebang = $shebang;
        $this->signingAlgorithm = $signingAlgorithm;
        $this->stubBannerContents = $stubBannerContents;
        $this->stubBannerPath = $stubBannerPath;
        $this->stubPath = $stubPath;
        $this->isInterceptFileFuncs = $isInterceptFileFuncs;
        $this->isStubGenerated = $isStubGenerated;
        $this->checkRequirements = $checkRequirements;
    }

    public static function create(?string $file, stdClass $raw): self
    {
        $alias = self::retrieveAlias($raw);

        $basePath = self::retrieveBasePath($file, $raw);

        $composerFiles = self::retrieveComposerFiles($basePath);

        $mainScriptPath = self::retrieveMainScriptPath($raw, $basePath, $composerFiles[0][1]);
        $mainScriptContents = self::retrieveMainScriptContents($mainScriptPath);

        [$tmpOutputPath, $outputPath] = self::retrieveOutputPath($raw, $basePath, $mainScriptPath);

        $composerJson = $composerFiles[0];
        $composerLock = $composerFiles[1];

        $devPackages = ComposerConfiguration::retrieveDevPackages($basePath, $composerJson[1], $composerLock[1]);

        [$excludedPaths, $blacklistFilter] = self::retrieveBlacklistFilter($raw, $basePath, $tmpOutputPath, $outputPath, $mainScriptPath);

        $files = self::retrieveFiles($raw, 'files', $basePath, $composerFiles, $mainScriptPath);

        if (self::shouldRetrieveAllFiles($file, $raw)) {
            [$files, $directories] = self::retrieveAllDirectoriesToInclude(
                $basePath,
                $composerJson[1],
                $devPackages,
                array_merge(
                    $files,
                    array_filter(
                        array_column($composerFiles, 0)
                    )
                ),
                $excludedPaths
            );

            $filesAggregate = self::retrieveAllFiles(
                $basePath,
                $files,
                $directories,
                $mainScriptPath,
                $blacklistFilter,
                $excludedPaths,
                $devPackages
            );
        } else {
            $directories = self::retrieveDirectories($raw, 'directories', $basePath, $blacklistFilter, $excludedPaths);
            $filesFromFinders = self::retrieveFilesFromFinders($raw, 'finder', $basePath, $blacklistFilter, $devPackages);

            $filesAggregate = self::retrieveFilesAggregate($files, $directories, ...$filesFromFinders);
        }

        $binaryFiles = self::retrieveFiles($raw, 'files-bin', $basePath, [], $mainScriptPath);
        $binaryDirectories = self::retrieveDirectories($raw, 'directories-bin', $basePath, $blacklistFilter, $excludedPaths);
        $binaryFilesFromFinders = self::retrieveFilesFromFinders($raw, 'finder-bin', $basePath, $blacklistFilter, $devPackages);

        $binaryFilesAggregate = self::retrieveFilesAggregate($binaryFiles, $binaryDirectories, ...$binaryFilesFromFinders);

        $dumpAutoload = self::retrieveDumpAutoload($raw, null !== $composerJson[0]);

        $excludeComposerFiles = self::retrieveExcludeComposerFiles($raw);

        $compactors = self::retrieveCompactors($raw, $basePath);
        $compressionAlgorithm = self::retrieveCompressionAlgorithm($raw);

        $fileMode = self::retrieveFileMode($raw);

        $map = self::retrieveMap($raw);
        $fileMapper = new MapFile($map);

        $metadata = self::retrieveMetadata($raw);

        $privateKeyPassphrase = self::retrievePrivateKeyPassphrase($raw);
        $privateKeyPath = self::retrievePrivateKeyPath($raw);
        $isPrivateKeyPrompt = self::retrieveIsPrivateKeyPrompt($raw);

        $replacements = self::retrieveReplacements($raw, $file);

        $shebang = self::retrieveShebang($raw);

        $signingAlgorithm = self::retrieveSigningAlgorithm($raw);

        $stubBannerContents = self::retrieveStubBannerContents($raw);
        $stubBannerPath = self::retrieveStubBannerPath($raw, $basePath);

        if (null !== $stubBannerPath) {
            $stubBannerContents = file_contents($stubBannerPath);
        }

        $stubBannerContents = self::normalizeStubBannerContents($stubBannerContents);

        $stubPath = self::retrieveStubPath($raw, $basePath);

        $isInterceptFileFuncs = self::retrieveIsInterceptFileFuncs($raw);
        $isStubGenerated = self::retrieveIsStubGenerated($raw, $stubPath);

        $checkRequirements = self::retrieveCheckRequirements(
            $raw,
            null !== $composerJson[0],
            null !== $composerLock[0],
            $isStubGenerated
        );

        return new self(
            $file,
            $alias,
            $basePath,
            $composerJson,
            $composerLock,
            $filesAggregate,
            $binaryFilesAggregate,
            $dumpAutoload,
            $excludeComposerFiles,
            $compactors,
            $compressionAlgorithm,
            $fileMode,
            $mainScriptPath,
            $mainScriptContents,
            $fileMapper,
            $metadata,
            $tmpOutputPath,
            $outputPath,
            $privateKeyPassphrase,
            $privateKeyPath,
            $isPrivateKeyPrompt,
            $replacements,
            $shebang,
            $signingAlgorithm,
            $stubBannerContents,
            $stubBannerPath,
            $stubPath,
            $isInterceptFileFuncs,
            $isStubGenerated,
            $checkRequirements
        );
    }

    public function getFile(): ?string
    {
        return $this->file;
    }

    public function getAlias(): string
    {
        return $this->alias;
    }

    public function getBasePath(): string
    {
        return $this->basePath;
    }

    public function getComposerJson(): ?string
    {
        return $this->composerJson[0];
    }

    public function getDecodedComposerJsonContents(): ?array
    {
        return $this->composerJson[1];
    }

    public function getComposerLock(): ?string
    {
        return $this->composerLock[0];
    }

    public function getDecodedComposerLockContents(): ?array
    {
        return $this->composerLock[1];
    }

    /**
     * @return string[]
     */
    public function getFiles(): array
    {
        return $this->files;
    }

    /**
     * @return string[]
     */
    public function getBinaryFiles(): array
    {
        return $this->binaryFiles;
    }

    public function dumpAutoload(): bool
    {
        return $this->dumpAutoload;
    }

    public function excludeComposerFiles(): bool
    {
        return $this->excludeComposerFiles;
    }

    /**
     * @return Compactor[] the list of compactors
     */
    public function getCompactors(): array
    {
        return $this->compactors;
    }

    public function getCompressionAlgorithm(): ?int
    {
        return $this->compressionAlgorithm;
    }

    public function getFileMode(): ?int
    {
        return $this->fileMode;
    }

    public function hasMainScript(): bool
    {
        return null !== $this->mainScriptPath;
    }

    public function getMainScriptPath(): string
    {
        Assertion::notNull(
            $this->mainScriptPath,
            'Cannot retrieve the main script path: no main script configured.'
        );

        return $this->mainScriptPath;
    }

    public function getMainScriptContents(): string
    {
        Assertion::notNull(
            $this->mainScriptPath,
            'Cannot retrieve the main script contents: no main script configured.'
        );

        return $this->mainScriptContents;
    }

    public function checkRequirements(): bool
    {
        return $this->checkRequirements;
    }

    public function getTmpOutputPath(): string
    {
        return $this->tmpOutputPath;
    }

    public function getOutputPath(): string
    {
        return $this->outputPath;
    }

    public function getFileMapper(): MapFile
    {
        return $this->fileMapper;
    }

    /**
     * @return mixed
     */
    public function getMetadata()
    {
        return $this->metadata;
    }

    public function getPrivateKeyPassphrase(): ?string
    {
        return $this->privateKeyPassphrase;
    }

    public function getPrivateKeyPath(): ?string
    {
        return $this->privateKeyPath;
    }

    public function isPrivateKeyPrompt(): bool
    {
        return $this->isPrivateKeyPrompt;
    }

    /**
     * @return scalar[]
     */
    public function getReplacements(): array
    {
        return $this->processedReplacements;
    }

    public function getShebang(): ?string
    {
        return $this->shebang;
    }

    public function getSigningAlgorithm(): int
    {
        return $this->signingAlgorithm;
    }

    public function getStubBannerContents(): ?string
    {
        return $this->stubBannerContents;
    }

    public function getStubBannerPath(): ?string
    {
        return $this->stubBannerPath;
    }

    public function getStubPath(): ?string
    {
        return $this->stubPath;
    }

    public function isInterceptFileFuncs(): bool
    {
        return $this->isInterceptFileFuncs;
    }

    public function isStubGenerated(): bool
    {
        return $this->isStubGenerated;
    }

    private static function retrieveAlias(stdClass $raw): string
    {
        if (false === isset($raw->alias)) {
            return uniqid('box-auto-generated-alias-', false).'.phar';
        }

        $alias = trim($raw->alias);

        Assertion::notEmpty($alias, 'A PHAR alias cannot be empty when provided.');

        return $alias;
    }

    private static function retrieveBasePath(?string $file, stdClass $raw): string
    {
        if (null === $file) {
            return getcwd();
        }

        if (false === isset($raw->{'base-path'})) {
            return realpath(dirname($file));
        }

        $basePath = trim($raw->{'base-path'});

        Assertion::directory(
            $basePath,
            'The base path "%s" is not a directory or does not exist.'
        );

        return realpath($basePath);
    }

    private static function shouldRetrieveAllFiles(?string $file, stdClass $raw): bool
    {
        if (null === $file) {
            return true;
        }

        // TODO: config should be casted into an array: it is easier to do and we need an array in several places now
        $rawConfig = (array) $raw;

        foreach (self::FILES_SETTINGS as $key) {
            if (array_key_exists($key, $rawConfig)) {
                return false;
            }
        }

        return true;
    }

    private static function retrieveBlacklistFilter(stdClass $raw, string $basePath, ?string ...$excludedPaths): array
    {
        $blacklist = self::retrieveBlacklist($raw, $basePath, ...$excludedPaths);

        $blacklistFilter = function (SplFileInfo $file) use ($blacklist): ?bool {
            if ($file->isLink()) {
                return false;
            }

            if (false === $file->getRealPath()) {
                return false;
            }

            if (in_array($file->getRealPath(), $blacklist, true)) {
                return false;
            }

            return null;
        };

        return [$blacklist, $blacklistFilter];
    }

    /**
     * @param stdClass        $raw
     * @param string          $basePath
     * @param null[]|string[] $excludedPaths
     *
     * @return string[]
     */
    private static function retrieveBlacklist(stdClass $raw, string $basePath, ?string ...$excludedPaths): array
    {
        /** @var string[] $blacklist */
        $blacklist = array_merge(
            array_filter($excludedPaths),
            $raw->blacklist ?? []
        );

        $normalizedBlacklist = [];

        foreach ($blacklist as $file) {
            $normalizedBlacklist[] = self::normalizePath($file, $basePath);
            $normalizedBlacklist[] = canonicalize(make_path_relative(trim($file), $basePath));
        }

        return array_unique($normalizedBlacklist);
    }

    /**
     * @return SplFileInfo[]
     */
    private static function retrieveFiles(
        stdClass $raw,
        string $key,
        string $basePath,
        array $composerFiles,
        ?string $mainScriptPath
    ): array {
        $files = [];

        if (isset($composerFiles[0][0])) {
            $files[] = $composerFiles[0][0];
        }

        if (isset($composerFiles[1][1])) {
            $files[] = $composerFiles[1][0];
        }

        if (false === isset($raw->{$key})) {
            return $files;
        }

        $files = array_merge((array) $raw->{$key}, $files);

        Assertion::allString($files);

        $normalizePath = function (string $file) use ($basePath, $key, $mainScriptPath): ?SplFileInfo {
            $file = self::normalizePath($file, $basePath);

            if (is_link($file)) {
                // TODO: add this to baberlei/assert
                throw new InvalidArgumentException(
                    sprintf(
                        'Cannot add the link "%s": links are not supported.',
                        $file
                    )
                );
            }

            Assertion::file(
                $file,
                sprintf(
                    '"%s" must contain a list of existing files. Could not find "%%s".',
                    $key
                )
            );

            return $mainScriptPath === $file ? null : new SplFileInfo($file);
        };

        return array_filter(array_map($normalizePath, $files));
    }

    /**
     * @param stdClass $raw
     * @param string   $key             Config property name
     * @param string   $basePath
     * @param Closure  $blacklistFilter
     * @param string[] $excludedPaths
     *
     * @return iterable|SplFileInfo[]
     */
    private static function retrieveDirectories(
        stdClass $raw,
        string $key,
        string $basePath,
        Closure $blacklistFilter,
        array $excludedPaths
    ): iterable {
        $directories = self::retrieveDirectoryPaths($raw, $key, $basePath);

        if ([] !== $directories) {
            $finder = Finder::create()
                ->files()
                ->filter($blacklistFilter)
                ->ignoreVCS(true)
                ->in($directories)
            ;

            foreach ($excludedPaths as $excludedPath) {
                $finder->notPath($excludedPath);
            }

            return $finder;

The expression return $finder returns the type Symfony\Component\Finder\Finder which is incompatible with the documented return type iterable|SplFileInfo[].

        }

        return [];
    }

    /**
     * @param stdClass $raw
     * @param string   $key
     * @param string   $basePath
     * @param Closure  $blacklistFilter
     * @param string[] $devPackages
     *
     * @return iterable[]|SplFileInfo[][]
     */
    private static function retrieveFilesFromFinders(
        stdClass $raw,
        string $key,
        string $basePath,
        Closure $blacklistFilter,
        array $devPackages
    ): array {
        if (isset($raw->{$key})) {
            return self::processFinders($raw->{$key}, $basePath, $blacklistFilter, $devPackages);
        }

        return [];
    }

    /**
     * @param iterable[]|SplFileInfo[][] $fileIterators
     *
     * @return SplFileInfo[]
     */
    private static function retrieveFilesAggregate(iterable ...$fileIterators): array
    {
        $files = [];

        foreach ($fileIterators as $fileIterator) {
            foreach ($fileIterator as $file) {
                $files[(string) $file] = $file;
            }
        }

        return array_values($files);
    }

    /**
     * @param array    $findersConfig
     * @param string   $basePath
     * @param Closure  $blacklistFilter
     * @param string[] $devPackages
     *
     * @return Finder[]|SplFileInfo[][]
     */
    private static function processFinders(
        array $findersConfig,
        string $basePath,
        Closure $blacklistFilter,
        array $devPackages
    ): array {
        $processFinderConfig = function (stdClass $config) use ($basePath, $blacklistFilter, $devPackages) {
            return self::processFinder($config, $basePath, $blacklistFilter, $devPackages);
        };

        return array_map($processFinderConfig, $findersConfig);
    }

    /**
     * @param stdClass $config
     * @param string   $basePath
     * @param Closure  $blacklistFilter
     * @param string[] $devPackages
     *
     * @return Finder|SplFileInfo[]
     */
    private static function processFinder(
        stdClass $config,
        string $basePath,
        Closure $blacklistFilter,
        array $devPackages
    ): Finder {
        $finder = Finder::create()
            ->files()
            ->filter($blacklistFilter)
            ->filter(
                function (SplFileInfo $fileInfo) use ($devPackages): bool {
                    foreach ($devPackages as $devPackage) {
                        if ($devPackage === longest_common_base_path([$devPackage, $fileInfo->getRealPath()])) {
                            // File belongs to the dev package
                            return false;
                        }
                    }

                    return true;
                }
            )
            ->ignoreVCS(true)
        ;

        $normalizedConfig = (function (array $config, Finder $finder): array {
            $normalizedConfig = [];

            foreach ($config as $method => $arguments) {
                $method = trim($method);
                $arguments = (array) $arguments;

                Assertion::methodExists(
                    $method,
                    $finder,
                    'The method "Finder::%s" does not exist.'
                );

                $normalizedConfig[$method] = $arguments;
            }

            krsort($normalizedConfig);

            return $normalizedConfig;
        })((array) $config, $finder);

        $createNormalizedDirectories = function (string $directory) use ($basePath): ?string {
            $directory = self::normalizePath($directory, $basePath);

            if (is_link($directory)) {
                // TODO: add this to baberlei/assert
                throw new InvalidArgumentException(
                    sprintf(
                        'Cannot append the link "%s" to the Finder: links are not supported.',
                        $directory
                    )
                );
            }

            Assertion::directory($directory);

            return $directory;
        };

        $normalizeFileOrDirectory = function (string &$fileOrDirectory) use ($basePath, $blacklistFilter): void {
            $fileOrDirectory = self::normalizePath($fileOrDirectory, $basePath);

            if (is_link($fileOrDirectory)) {
                // TODO: add this to baberlei/assert
                throw new InvalidArgumentException(
                    sprintf(
                        'Cannot append the link "%s" to the Finder: links are not supported.',
                        $fileOrDirectory
                    )
                );
            }

            // TODO: add this to baberlei/assert
            if (false === file_exists($fileOrDirectory)) {
                throw new InvalidArgumentException(
                    sprintf(
                        'Path "%s" was expected to be a file or directory. It may be a symlink (which are unsupported).',
                        $fileOrDirectory
                    )
                );
            }

            // TODO: add fileExists (as file or directory) to Assert
            if (false === is_file($fileOrDirectory)) {
                Assertion::directory($fileOrDirectory);
            } else {
                Assertion::file($fileOrDirectory);
            }

            if (false === $blacklistFilter(new SplFileInfo($fileOrDirectory))) {
                $fileOrDirectory = null;
            }
        };

        foreach ($normalizedConfig as $method => $arguments) {
            if ('in' === $method) {
                $normalizedConfig[$method] = $arguments = array_map($createNormalizedDirectories, $arguments);
            }

            if ('exclude' === $method) {
                $arguments = array_unique(array_map('trim', $arguments));
            }

            if ('append' === $method) {
                array_walk($arguments, $normalizeFileOrDirectory);

                $arguments = [array_filter($arguments)];
            }

            foreach ($arguments as $argument) {
                $finder->$method($argument);
            }
        }

        return $finder;
    }

    /**
     * @param string[] $devPackages
     * @param string[] $filesToAppend
     *
     * @return string[][]
     */
    private static function retrieveAllDirectoriesToInclude(
        string $basePath,
        ?array $decodedJsonContents,
        array $devPackages,
        array $filesToAppend,
        array $excludedPaths
    ): array {
        $toString = function ($file): string {
            // @param string|SplFileInfo $file
            return (string) $file;
        };

        if (null !== $decodedJsonContents && array_key_exists('vendor-dir', $decodedJsonContents)) {
            $vendorDir = self::normalizePath($decodedJsonContents['vendor-dir'], $basePath);
        } else {
            $vendorDir = self::normalizePath('vendor', $basePath);
        }

        if (file_exists($vendorDir)) {
            // The installed.json file is necessary for dumping the autoload correctly. Note however that it will not exists if no
            // dependencies are included in the `composer.json`
            $installedJsonFiles = self::normalizePath($vendorDir.'/composer/installed.json', $basePath);

            if (file_exists($installedJsonFiles)) {
                $filesToAppend[] = $installedJsonFiles;
            }

            $vendorPackages = toArray(values(map(
                $toString,
                Finder::create()
                    ->in($vendorDir)
                    ->directories()
                    ->depth(1)
                    ->ignoreUnreadableDirs()
                    ->filter(
                        function (SplFileInfo $fileInfo): ?bool {
                            if ($fileInfo->isLink()) {
                                return false;
                            }

                            return null;
                        }
                    )
            )));

            $vendorPackages = array_diff($vendorPackages, $devPackages);

            if (null === $decodedJsonContents || false === array_key_exists('autoload', $decodedJsonContents)) {
                $files = toArray(values(map(
                    $toString,
                    Finder::create()
                        ->in($basePath)
                        ->files()
                        ->depth(0)
                )));

                $directories = toArray(values(map(
                    $toString,
                    Finder::create()
                        ->in($basePath)
                        ->notPath('vendor')
                        ->directories()
                        ->depth(0)
                )));

                return [
                    array_merge($files, $filesToAppend),
                    array_merge($directories, $vendorPackages),
                ];
            }

            $paths = $vendorPackages;
        } else {
            $paths = [];
        }

        $autoload = $decodedJsonContents['autoload'] ?? [];

        if (array_key_exists('psr-4', $autoload)) {
            foreach ($autoload['psr-4'] as $path) {
                /** @var string|string[] $path */
                $composerPaths = (array) $path;

                foreach ($composerPaths as $composerPath) {
                    $paths[] = '' !== trim($composerPath) ? $composerPath : $basePath;
                }
            }
        }

        if (array_key_exists('psr-0', $autoload)) {
            foreach ($autoload['psr-0'] as $path) {
                /** @var string|string[] $path */
                $composerPaths = (array) $path;

                foreach ($composerPaths as $composerPath) {
                    if ('' !== trim($composerPath)) {
                        $paths[] = $composerPath;
                    }
                }
            }
        }

        if (array_key_exists('classmap', $autoload)) {
            foreach ($autoload['classmap'] as $path) {
                // @var string $path
                $paths[] = $path;
            }
        }

        $normalizePath = function (string $path) use ($basePath): string {
            return is_absolute_path($path)
                ? canonicalize($path)
                : self::normalizePath(trim($path, '/ '), $basePath)
            ;
        };

        if (array_key_exists('files', $autoload)) {
            foreach ($autoload['files'] as $path) {
                // @var string $path
                $path = $normalizePath($path);

                Assertion::file($path);
                Assertion::false(is_link($path), 'Cannot add the link "'.$path.'": links are not supported.');

                $filesToAppend[] = $path;
            }
        }

        $files = $filesToAppend;
        $directories = [];

        foreach ($paths as $path) {
            $path = $normalizePath($path);

            Assertion::true(file_exists($path), 'File or directory "'.$path.'" was expected to exist.');
            Assertion::false(is_link($path), 'Cannot add the link "'.$path.'": links are not supported.');

            if (is_file($path)) {
                $files[] = $path;
            } else {
                $directories[] = $path;
            }
        }

        [$files, $directories] = [
            array_unique($files),
            array_unique($directories),
        ];

        return [
            array_diff($files, $excludedPaths),
            array_diff($directories, $excludedPaths),
        ];
    }

    /**
     * @param string[] $files
     * @param string[] $directories
     * @param string[] $excludedPaths
     * @param string[] $devPackages
     *
     * @return SplFileInfo[]
     */
    private static function retrieveAllFiles(
        string $basePath,
        array $files,
        array $directories,
        ?string $mainScriptPath,
        Closure $blacklistFilter,
        array $excludedPaths,
        array $devPackages
    ): array {
        $relativeDevPackages = array_map(
            function (string $packagePath) use ($basePath): string {
                return make_path_relative($packagePath, $basePath);
            },
            $devPackages
        );

        $finder = Finder::create()
            ->files()
            ->filter($blacklistFilter)
            ->exclude($relativeDevPackages)
            ->ignoreVCS(true)
            ->ignoreDotFiles(true)
            // Remove build files
            ->notName('composer.json')
            ->notName('composer.lock')
            ->notName('Makefile')
            ->notName('Vagrantfile')
            ->notName('phpstan*.neon*')
            ->notName('infection*.json*')
            ->notName('humbug*.json*')
            ->notName('easy-coding-standard.neon*')
            ->notName('phpbench.json*')
            ->notName('phpcs.xml*')
            ->notName('psalm.xml*')
            ->notName('scoper.inc*')
            ->notName('box*.json*')
            ->notName('phpdoc*.xml*')
            ->notName('codecov.yml*')
            ->notName('Dockerfile')
            ->exclude('build')
            ->exclude('dist')
            ->exclude('example')
            ->exclude('examples')
            // Remove documentation
            ->notName('*.md')
            ->notName('*.rst')
            ->notName('/^readme(\..*+)?$/i')
            ->notName('/^license(\..*+)?$/i')
            ->notName('/^upgrade(\..*+)?$/i')
            ->notName('/^contributing(\..*+)?$/i')
            ->notName('/^changelog(\..*+)?$/i')
            ->notName('/^authors?(\..*+)?$/i')
            ->notName('/^conduct(\..*+)?$/i')
            ->notName('/^todo(\..*+)?$/i')
            ->exclude('doc')
            ->exclude('docs')
            ->exclude('documentation')
            // Remove backup files
            ->notName('*~')
            ->notName('*.back')
            ->notName('*.swp')
            // Remove tests
            ->notName('*Test.php')
            ->exclude('test')
            ->exclude('Test')
            ->exclude('tests')
            ->exclude('Tests')
            ->notName('/phpunit.*\.xml(.dist)?/')
            ->notName('/behat.*\.yml(.dist)?/')
            ->exclude('spec')
            ->exclude('specs')
            ->exclude('features')
            // Remove CI config
            ->exclude('travis')
            ->notName('travis.yml')
            ->notName('appveyor.yml')
            ->notName('build.xml*')
        ;

        if (null !== $mainScriptPath) {
            $finder->notPath(make_path_relative($mainScriptPath, $basePath));
        }

        $finder->append($files);
        $finder->in($directories);

        $excludedPaths = array_unique(
            array_filter(
                array_map(
                    function (string $path) use ($basePath): string {
                        return make_path_relative($path, $basePath);
                    },
                    $excludedPaths
                ),
                function (string $path): bool {
                    return '..' !== substr($path, 0, 2);
                }
            )
        );

        foreach ($excludedPaths as $excludedPath) {
            $finder->notPath($excludedPath);
        }

        return array_unique(
            toArray(
                map(
                    method('getRealPath'),
                    $finder
                )
            )
        );
    }

    /**
     * @param stdClass $raw
     * @param string   $key      Config property name
     * @param string   $basePath
     *
     * @return string[]
     */
    private static function retrieveDirectoryPaths(stdClass $raw, string $key, string $basePath): array
    {
        if (false === isset($raw->{$key})) {
            return [];
        }

        $directories = $raw->{$key};

        $normalizeDirectory = function (string $directory) use ($basePath, $key): string {
            $directory = self::normalizePath($directory, $basePath);

            if (is_link($directory)) {
                // TODO: add this to baberlei/assert
                throw new InvalidArgumentException(
                    sprintf(
                        'Cannot add the link "%s": links are not supported.',
                        $directory
                    )
                );
            }

            Assertion::directory(
                $directory,
                sprintf(
                    '"%s" must contain a list of existing directories. Could not find "%%s".',
                    $key
                )
            );

            return $directory;
        };

        return array_map($normalizeDirectory, $directories);
    }

    private static function normalizePath(string $file, string $basePath): string
    {
        return make_path_absolute(trim($file), $basePath);
    }

    private static function retrieveDumpAutoload(stdClass $raw, bool $composerJson): bool
    {
        $dumpAutoload = $raw->{'dump-autoload'} ?? true;

        // TODO: add warning when the dump autoload parameter is explicitly set that it has been ignored because no `composer.json` file
        // could have been found.

        return $composerJson ? $dumpAutoload : false;
    }

    private static function retrieveExcludeComposerFiles(stdClass $raw): bool
    {
        return $raw->{'exclude-composer-files'} ?? true;
    }

    /**
     * @return Compactor[]
     */
    private static function retrieveCompactors(stdClass $raw, string $basePath): array
    {
        if (false === isset($raw->compactors)) {
            return [];
        }

        $compactorClasses = array_unique((array) $raw->compactors);

        return array_map(
            function (string $class) use ($raw, $basePath): Compactor {
                Assertion::classExists($class, 'The compactor class "%s" does not exist.');
                Assertion::implementsInterface($class, Compactor::class, 'The class "%s" is not a compactor class.');

                if (Php::class === $class || LegacyPhp::class === $class) {
                    return self::createPhpCompactor($raw);
                }

                if (PhpScoperCompactor::class === $class) {
                    $phpScoperConfig = self::retrievePhpScoperConfig($raw, $basePath);

                    $prefix = null === $phpScoperConfig->getPrefix()
                        ? uniqid('_HumbugBox', false)
                        : $phpScoperConfig->getPrefix()
                    ;

                    return new PhpScoperCompactor(
                        new SimpleScoper(
                            create_scoper(),
                            $prefix,
                            $phpScoperConfig->getWhitelist(),
                            $phpScoperConfig->getPatchers()
                        )
                    );
                }

                return new $class();
            },
            $compactorClasses
        );
    }

    private static function retrieveCompressionAlgorithm(stdClass $raw): ?int
    {
        if (false === isset($raw->compression)) {
            return null;
        }

        $knownAlgorithmNames = array_keys(get_phar_compression_algorithms());

        Assertion::inArray(
            $raw->compression,
            $knownAlgorithmNames,
            sprintf(
                'Invalid compression algorithm "%%s", use one of "%s" instead.',
                implode('", "', $knownAlgorithmNames)
            )
        );

        $value = get_phar_compression_algorithms()[$raw->compression];

        // Phar::NONE is not valid for compressFiles()
        if (Phar::NONE === $value) {
            return null;
        }

        return $value;
    }

    private static function retrieveFileMode(stdClass $raw): ?int
    {
        if (isset($raw->chmod)) {
            return intval($raw->chmod, 8);
        }

        return null;
    }

    private static function retrieveMainScriptPath(stdClass $raw, string $basePath, ?array $decodedJsonContents): ?string
    {
        if (isset($raw->main)) {
            $main = $raw->main;
        } else {
            if (null === $decodedJsonContents
                || false === array_key_exists('bin', $decodedJsonContents)
                || false === $main = current((array) $decodedJsonContents['bin'])
            ) {
                $main = self::DEFAULT_MAIN_SCRIPT;
            }
        }

        if (is_bool($main)) {
            Assertion::false(
                $main,
                'Cannot "enable" a main script: either disable it with `false` or give the main script file path.'
            );

            return null;
        }

        return self::normalizePath($main, $basePath);
    }

    private static function retrieveMainScriptContents(?string $mainScriptPath): ?string
    {
        if (null === $mainScriptPath) {
            return null;
        }

        $contents = file_contents($mainScriptPath);

        // Remove the shebang line: the shebang line in a PHAR should be located in the stub file which is the real
        // PHAR entry point file.
        return preg_replace('/^#!.*\s*/', '', $contents);
    }

    private static function retrieveComposerFiles(string $basePath): array
    {
        $retrieveFileAndContents = function (string $file): array {
            $json = new Json();

            if (false === file_exists($file) || false === is_file($file) || false === is_readable($file)) {
                return [null, null];
            }

            try {
                $contents = $json->decodeFile($file, true);
            } catch (ParsingException $exception) {
                throw new InvalidArgumentException(
                    sprintf(
                        'Expected the file "%s" to be a valid composer.json file but an error has been found: %s',
                        $file,
                        $exception->getMessage()
                    ),
                    0,
                    $exception
                );
            }

            return [$file, $contents];
        };

        [$composerJson, $composerJsonContents] = $retrieveFileAndContents(canonicalize($basePath.'/composer.json'));
        [$composerLock, $composerLockContents] = $retrieveFileAndContents(canonicalize($basePath.'/composer.lock'));

        return [
            [$composerJson, $composerJsonContents],
            [$composerLock, $composerLockContents],
        ];
    }

    /**
     * @return string[][]
     */
    private static function retrieveMap(stdClass $raw): array
    {
        if (false === isset($raw->map)) {
            return [];
        }

        $map = [];

        foreach ((array) $raw->map as $item) {
            $processed = [];

            foreach ($item as $match => $replace) {
                $processed[canonicalize(trim($match))] = canonicalize(trim($replace));
            }

            if (isset($processed['_empty_'])) {
                $processed[''] = $processed['_empty_'];

                unset($processed['_empty_']);
            }

            $map[] = $processed;
        }

        return $map;
    }

    /**
     * @return mixed
     */
    private static function retrieveMetadata(stdClass $raw)
    {
        if (isset($raw->metadata)) {
            if (is_object($raw->metadata)) {
                return (array) $raw->metadata;
            }

            return $raw->metadata;
        }

        return null;
    }

    /**
     * @return string[] The first element is the temporary output path and the second the real one
     */
    private static function retrieveOutputPath(stdClass $raw, string $basePath, ?string $mainScriptPath): array
    {
        if (isset($raw->output)) {
            $path = $raw->output;
        } else {
            if (null !== $mainScriptPath
                && 1 === preg_match('/^(?<main>.*?)(?:\.[\p{L}\d]+)?$/', $mainScriptPath, $matches)
            ) {
                $path = $matches['main'].'.phar';
            } else {
                // Last resort, should not happen
                $path = self::DEFAULT_ALIAS;
            }
        }

        $tmp = $real = self::normalizePath($path, $basePath);

        if ('.phar' !== substr($real, -5)) {
            $tmp .= '.phar';
        }

        return [$tmp, $real];
    }

    private static function retrievePrivateKeyPassphrase(stdClass $raw): ?string
    {
        // TODO: add check to not allow this setting without the private key path
        if (isset($raw->{'key-pass'})
            && is_string($raw->{'key-pass'})
        ) {
            return $raw->{'key-pass'};
        }

        return null;
    }

    private static function retrievePrivateKeyPath(stdClass $raw): ?string
    {
        // TODO: If passed need to check its existence
        // Also need

        if (isset($raw->key)) {
            return $raw->key;
        }

        return null;
    }

    /**
     * @return scalar[]
     */
    private static function retrieveReplacements(stdClass $raw, ?string $file): array
    {
        if (null === $file) {
            return [];
        }

        $replacements = isset($raw->replacements) ? (array) $raw->replacements : [];

        if (null !== ($git = self::retrievePrettyGitPlaceholder($raw))) {
            $replacements[$git] = self::retrievePrettyGitTag($file);
        }

        if (null !== ($git = self::retrieveGitHashPlaceholder($raw))) {
            $replacements[$git] = self::retrieveGitHash($file);
        }

        if (null !== ($git = self::retrieveGitShortHashPlaceholder($raw))) {
            $replacements[$git] = self::retrieveGitHash($file, true);
        }

        if (null !== ($git = self::retrieveGitTagPlaceholder($raw))) {
            $replacements[$git] = self::retrieveGitTag($file);
        }

        if (null !== ($git = self::retrieveGitVersionPlaceholder($raw))) {
            $replacements[$git] = self::retrieveGitVersion($file);
        }

        $datetimeFormat = self::retrieveDatetimeFormat($raw);

        if (null !== ($date = self::retrieveDatetimeNowPlaceHolder($raw))) {
            $replacements[$date] = self::retrieveDatetimeNow(
                $datetimeFormat
            );
        }

        $sigil = self::retrieveReplacementSigil($raw);

        foreach ($replacements as $key => $value) {
            unset($replacements[$key]);
            $replacements[$sigil.$key.$sigil] = $value;
        }

        return $replacements;
    }

    private static function retrievePrettyGitPlaceholder(stdClass $raw): ?string
    {
        return isset($raw->{'git'}) ? $raw->{'git'} : null;
    }

    private static function retrieveGitHashPlaceholder(stdClass $raw): ?string
    {
        return isset($raw->{'git-commit'}) ? $raw->{'git-commit'} : null;
    }

    /**
     * @param string $file
     * @param bool   $short Use the short version
     *
     * @return string the commit hash
     */
    private static function retrieveGitHash(string $file, bool $short = false): string
    {
        return self::runGitCommand(
            sprintf(
                'git log --pretty="%s" -n1 HEAD',
                $short ? '%h' : '%H'
            ),
            $file
        );
    }

    private static function retrieveGitShortHashPlaceholder(stdClass $raw): ?string
    {
        return isset($raw->{'git-commit-short'}) ? $raw->{'git-commit-short'} : null;
    }

    private static function retrieveGitTagPlaceholder(stdClass $raw): ?string
    {
        return isset($raw->{'git-tag'}) ? $raw->{'git-tag'} : null;
    }

    private static function retrieveGitTag(string $file): string
    {
        return self::runGitCommand('git describe --tags HEAD', $file);
    }

    private static function retrievePrettyGitTag(string $file): string
    {
        $version = self::retrieveGitTag($file);

        if (preg_match('/^(?<tag>.+)-\d+-g(?<hash>[a-f0-9]{7})$/', $version, $matches)) {
            return sprintf('%s@%s', $matches['tag'], $matches['hash']);
        }

        return $version;
    }

    private static function retrieveGitVersionPlaceholder(stdClass $raw): ?string
    {
        return isset($raw->{'git-version'}) ? $raw->{'git-version'} : null;
    }

    private static function retrieveGitVersion(string $file): ?string
    {
        try {
            return self::retrieveGitTag($file);
        } catch (RuntimeException $exception) {
            try {
                return self::retrieveGitHash($file, true);
            } catch (RuntimeException $exception) {
                throw new RuntimeException(
                    sprintf(
                        'The tag or commit hash could not be retrieved from "%s": %s',
                        dirname($file),
                        $exception->getMessage()
                    ),
                    0,
                    $exception
                );
            }
        }
    }

    private static function retrieveDatetimeNowPlaceHolder(stdClass $raw): ?string
    {
        return isset($raw->{'datetime'}) ? $raw->{'datetime'} : null;
    }

    private static function retrieveDatetimeNow(string $format): string
    {
        $now = new DateTimeImmutable('now', new DateTimeZone('UTC'));

        return $now->format($format);
    }

    private static function retrieveDatetimeFormat(stdClass $raw): string
    {
        if (isset($raw->{'datetime-format'})) {
            $format = $raw->{'datetime-format'};
        } elseif (isset($raw->{'datetime_format'})) {
            // TODO: make sure this deprecation message correctly appear to the user
            @trigger_error(
                'The setting "datetime_format" is deprecated, use "datetime-format" instead.',
                E_USER_DEPRECATED
            );

            $format = $raw->{'datetime_format'};
        }

        if (isset($format)) {
            $formattedDate = (new DateTimeImmutable())->format($format);

            Assertion::false(
                false === $formattedDate || $formattedDate === $format,
                sprintf(
                    'Expected the datetime format to be a valid format: "%s" is not',
                    $format
                )
            );

            return $format;
        }

        return self::DEFAULT_DATETIME_FORMAT;
    }

    private static function retrieveReplacementSigil(stdClass $raw): string
    {
        return isset($raw->{'replacement-sigil'}) ? $raw->{'replacement-sigil'} : self::DEFAULT_REPLACEMENT_SIGIL;
    }

    private static function retrieveShebang(stdClass $raw): ?string
    {
        if (false === array_key_exists('shebang', (array) $raw)) {
            return self::DEFAULT_SHEBANG;
        }

        if (null === $raw->shebang) {
            return null;
        }

        $shebang = trim($raw->shebang);

        Assertion::notEmpty($shebang, 'The shebang should not be empty.');
        Assertion::true(
            '#!' === substr($shebang, 0, 2),
            sprintf(
                'The shebang line must start with "#!". Got "%s" instead',
                $shebang
            )
        );

        return $shebang;
    }

    private static function retrieveSigningAlgorithm(stdClass $raw): int
    {
        // TODO: trigger warning: if no signing algorithm is given provided we are not in dev mode
        // TODO: trigger a warning if the signing algorithm used is weak
        // TODO: no longer accept strings & document BC break
        if (false === isset($raw->algorithm)) {
            return Phar::SHA1;
        }

        if (false === defined('Phar::'.$raw->algorithm)) {
            throw new InvalidArgumentException(
                sprintf(
                    'The signing algorithm "%s" is not supported.',
                    $raw->algorithm
                )
            );
        }

        return constant('Phar::'.$raw->algorithm);
    }

    private static function retrieveStubBannerContents(stdClass $raw): ?string
    {
        if (false === array_key_exists('banner', (array) $raw)) {
            return self::DEFAULT_BANNER;
        }

        if (null === $raw->banner) {
            return null;
        }

        $banner = $raw->banner;

        if (is_array($banner)) {
            $banner = implode("\n", $banner);
        }

        return $banner;
    }

    private static function retrieveStubBannerPath(stdClass $raw, string $basePath): ?string
    {
        if (false === isset($raw->{'banner-file'})) {
            return null;
        }

        $bannerFile = make_path_absolute($raw->{'banner-file'}, $basePath);

        Assertion::file($bannerFile);

        return $bannerFile;
    }

    private static function normalizeStubBannerContents(?string $contents): ?string
    {
        if (null === $contents) {
            return null;
        }

        $banner = explode("\n", $contents);
        $banner = array_map('trim', $banner);

        return implode("\n", $banner);
    }

    private static function retrieveStubPath(stdClass $raw, string $basePath): ?string
    {
        if (isset($raw->stub) && is_string($raw->stub)) {
            $stubPath = make_path_absolute($raw->stub, $basePath);

            Assertion::file($stubPath);

            return $stubPath;
        }

        return null;
    }

    private static function retrieveIsInterceptFileFuncs(stdClass $raw): bool
    {
        if (isset($raw->intercept)) {
            return $raw->intercept;
        }

        return false;
    }

    private static function retrieveIsPrivateKeyPrompt(stdClass $raw): bool
    {
        return isset($raw->{'key-pass'}) && (true === $raw->{'key-pass'});
    }

    private static function retrieveIsStubGenerated(stdClass $raw, ?string $stubPath): bool
    {
        return null === $stubPath && (false === isset($raw->stub) || false !== $raw->stub);
    }

    private static function retrieveCheckRequirements(stdClass $raw, bool $hasComposerJson, bool $hasComposerLock, bool $generateStub): bool
    {
        // TODO: emit warning when stub is not generated and check requirements is explicitly set to true
        // TODO: emit warning when no composer lock is found but check requirements is explicitely set to true
        if (false === $hasComposerJson && false === $hasComposerLock) {
            return false;
        }

        return $raw->{'check-requirements'} ?? true;
    }

    private static function retrievePhpScoperConfig(stdClass $raw, string $basePath): PhpScoperConfiguration
    {
        if (!isset($raw->{'php-scoper'})) {
            $configFilePath = make_path_absolute(self::PHP_SCOPER_CONFIG, $basePath);

            return file_exists($configFilePath)
                ? PhpScoperConfiguration::load($configFilePath)
                : PhpScoperConfiguration::load()
             ;
        }

        $configFile = $raw->phpScoper;

        Assertion::string($configFile);

        $configFilePath = make_path_absolute($configFile, $basePath);

        Assertion::file($configFilePath);
        Assertion::readable($configFilePath);

        return PhpScoperConfiguration::load($configFilePath);
    }

    /**
     * Runs a Git command on the repository.
     *
     * @param string $command the command
     *
     * @return string the trimmed output from the command
     */
    private static function runGitCommand(string $command, string $file): string
    {
        $path = dirname($file);

        $process = new Process($command, $path);

        if (0 === $process->run()) {
            return trim($process->getOutput());
        }

        throw new RuntimeException(
            sprintf(
                'The tag or commit hash could not be retrieved from "%s": %s',
                $path,
                $process->getErrorOutput()
            )
        );
    }

    private static function createPhpCompactor(stdClass $raw): Compactor
    {
        // TODO: false === not set; check & add test/doc
        $tokenizer = new Tokenizer();

        if (false === empty($raw->annotations) && isset($raw->annotations->ignore)) {
            $tokenizer->ignore(
                (array) $raw->annotations->ignore
            );
        }

        return new Php($tokenizer);
    }
}