Introduce a File primitive

src/Box.php

@@ -23,6 +23,7 @@
 use KevinGH\Box\Compactor\Compactors;
 use KevinGH\Box\Compactor\PhpScoper;
 use KevinGH\Box\Compactor\Placeholder;
+use KevinGH\Box\Filesystem\LocalPharFile;
 use KevinGH\Box\Parallelization\ParallelFileProcessor;
 use KevinGH\Box\Parallelization\ParallelizationDecider;
 use KevinGH\Box\Phar\CompressionAlgorithm;
@@ -47,6 +48,7 @@
 use function openssl_pkey_get_details;
 use function openssl_pkey_get_private;
 use function sprintf;
+use function strval;
 
 /**
  * Box is a utility class to generate a PHAR.
@@ -62,7 +64,7 @@ final class Box implements Countable
     private bool $buffering = false;
 
     /**
-     * @var array<string, string> Relative file path as key and file contents as value
+     * @var array<string, LocalPharFile>
      */
     private array $bufferedFiles = [];
 
@@ -127,13 +129,19 @@ public function endBuffering(?callable $dumpAutoload): void
 
         if ([] === $this->bufferedFiles) {
             $this->bufferedFiles = [
-                '.box_empty' => 'A PHAR cannot be empty so Box adds this file to ensure the PHAR is created still.',
+                new LocalPharFile(
+                    '.box_empty',
+                    'A PHAR cannot be empty so Box adds this file to ensure the PHAR is created still.',
+                ),
             ];
         }
 
         try {
-            foreach ($this->bufferedFiles as $file => $contents) {
-                FS::dumpFile($file, $contents);
+            foreach ($this->bufferedFiles as $file) {
+                FS::dumpFile(
+                    $file->getPath(),
+                    $file->getContents(),
+                );
             }
 
             if (null !== $dumpAutoload) {
@@ -294,7 +302,7 @@ public function addFiles(array $files, bool $binary): void
     {
         Assert::true($this->buffering, 'Cannot add files if the buffering has not started.');
 
-        $files = array_map('strval', $files);
+        $files = array_map(strval(...), $files);
 
         if ($binary) {
             foreach ($files as $file) {
@@ -304,8 +312,8 @@ public function addFiles(array $files, bool $binary): void
             return;
         }
 
-        foreach ($this->processContents($files) as [$file, $contents]) {
-            $this->bufferedFiles[$file] = $contents;
+        foreach ($this->processContents($files) as $file) {
+            $this->bufferedFiles[$file->getPath()] = $file;
         }
     }
 
@@ -328,7 +336,12 @@ public function addFile(string $file, ?string $contents = null, bool $binary = f
 
         $local = ($this->mapFile)($file);
 
-        $this->bufferedFiles[$local] = $binary ? $contents : $this->compactors->compact($local, $contents);
+        $this->bufferedFiles[$local] = new LocalPharFile(
+            $local,
+            $binary ?
+                $contents :
+                $this->compactors->compact($local, $contents),
+        );
 
         return $local;
     }
@@ -445,8 +458,7 @@ public function signUsingKey(string $key, ?string $password): void
     /**
      * @param string[] $files
      *
-     * @return array array of tuples where the first element is the local file path (path inside the PHAR) and the
-     *               second element is the processed contents
+     * @return LocalPharFile[]
      */
     private function processContents(array $files): array
     {
@@ -472,25 +484,25 @@ private function processContents(array $files): array
     /**
      * @param string[] $files
      *
-     * @return list<array{string, string}>
+     * @return LocalPharFile[]
      */
     private static function processFilesSynchronously(
         array $files,
         string $_cwd,
         MapFile $mapFile,
         Compactors $compactors,
     ): array {
-        $processFile = static function (string $file) use ($mapFile, $compactors): array {
+        $processFile = static function (string $file) use ($mapFile, $compactors): LocalPharFile {
             $contents = FS::getFileContents($file);
 
             $local = $mapFile($file);
 
             $processedContents = $compactors->compact($local, $contents);
 
-            return [
+            return new LocalPharFile(
                 $local,
                 $processedContents,
-            ];
+            );
         };
 
         return array_map($processFile, $files);

src/Console/Command/Compile.php

@@ -599,16 +599,18 @@ private static function registerStub(
             return;
         }
 
-        if (null !== ($stub = $config->getStubPath())) {
+        $stubPath = $config->getStubPath();
+
+        if (null !== $stubPath) {
             $logger->log(
                 CompilerLogger::QUESTION_MARK_PREFIX,
                 sprintf(
                     'Using stub file: %s',
-                    $stub,
+                    $stubPath,
                 ),
             );
 
-            $box->registerStub($stub);
+            $box->registerStub($stubPath);
 
             return;
         }

src/Filesystem/File.php

@@ -0,0 +1,22 @@
+<?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\Filesystem;
+
+interface File
+{
+    public function getPath(): string;
+
+    public function getContents(): string;
+}

src/Filesystem/LocalPharFile.php

@@ -0,0 +1,34 @@
+<?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\Filesystem;
+
+final readonly class LocalPharFile implements File
+{
+    public function __construct(
+        private string $path,
+        private string $contents,
+    ) {
+    }
+
+    public function getPath(): string
+    {
+        return $this->path;
+    }
+
+    public function getContents(): string
+    {
+        return $this->contents;
+    }
+}

src/Parallelization/ParallelFileProcessor.php

@@ -18,6 +18,7 @@
 use Amp\Parallel\Worker\TaskFailureThrowable;
 use Amp\Parallel\Worker\WorkerPool;
 use KevinGH\Box\Compactor\Compactors;
+use KevinGH\Box\Filesystem\LocalPharFile;
 use KevinGH\Box\MapFile;
 use function Amp\Future\await;
 use function Amp\Parallel\Worker\workerPool;
@@ -35,7 +36,7 @@ final class ParallelFileProcessor
      *
      * @throws TaskFailureThrowable
      *
-     * @return list<array{string, string}>
+     * @return LocalPharFile[]
      */
     public static function processFilesInParallel(
         array $filePaths,
@@ -55,7 +56,7 @@ public static function processFilesInParallel(
 
         $compactors->registerSymbolsRegistry($result->symbolsRegistry);
 
-        return $result->filesWithContents;
+        return $result->localPharFiles;
     }
 
     /**

src/Parallelization/ProcessFileTask.php

@@ -20,6 +20,7 @@
 use Fidry\FileSystem\FS;
 use Humbug\PhpScoper\Symbol\SymbolsRegistry;
 use KevinGH\Box\Compactor\Compactors;
+use KevinGH\Box\Filesystem\LocalPharFile;
 use KevinGH\Box\MapFile;
 use function array_map;
 
@@ -53,21 +54,21 @@ public function run(Channel $channel, Cancellation $cancellation): TaskResult
 
             $processedContents = $compactors->compact($local, $contents);
 
-            return [$local, $processedContents, $compactors->getScoperSymbolsRegistry()];
+            return [new LocalPharFile($local, $processedContents), $compactors->getScoperSymbolsRegistry()];
         };
 
         $tuples = array_map($processFile, $this->filePaths);
 
-        $filesWithContents = [];
+        $localPharFiles = [];
         $symbolRegistries = [];
 
-        foreach ($tuples as [$local, $processedContents, $symbolRegistry]) {
-            $filesWithContents[] = [$local, $processedContents];
+        foreach ($tuples as [$localPharFile, $symbolRegistry]) {
+            $localPharFiles[] = $localPharFile;
             $symbolRegistries[] = $symbolRegistry;
         }
 
         return new TaskResult(
-            $filesWithContents,
+            $localPharFiles,
             SymbolsRegistry::createFromRegistries(array_filter($symbolRegistries)),
         );
     }

src/Parallelization/TaskResult.php

@@ -15,6 +15,7 @@
 namespace KevinGH\Box\Parallelization;
 
 use Humbug\PhpScoper\Symbol\SymbolsRegistry;
+use KevinGH\Box\Filesystem\LocalPharFile;
 use function array_merge;
 
 /**
@@ -31,7 +32,7 @@ public static function aggregate(array $results): self
         $symbolsRegistries = [];
 
         foreach ($results as $result) {
-            $filesWithContents[] = $result->filesWithContents;
+            $filesWithContents[] = $result->localPharFiles;
             $symbolsRegistries[] = $result->symbolsRegistry;
         }
 
@@ -42,10 +43,10 @@ public static function aggregate(array $results): self
     }
 
     /**
-     * @param list<array{string, string}> $filesWithContents
+     * @param LocalPharFile[] $localPharFiles
      */
     public function __construct(
-        public array $filesWithContents,
+        public array $localPharFiles,
         public SymbolsRegistry $symbolsRegistry,
     ) {
     }

tests/Parallelization/TaskResultTest.php

@@ -15,6 +15,7 @@
 namespace KevinGH\Box\Parallelization;
 
 use Humbug\PhpScoper\Symbol\SymbolsRegistry;
+use KevinGH\Box\Filesystem\LocalPharFile;
 use PhpParser\Node\Name\FullyQualified;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\DataProvider;
@@ -64,25 +65,25 @@ public static function resultsProvider(): iterable
             [
                 new TaskResult(
                     [
-                        ['fileA', 'contentA'],
-                        ['fileB', 'contentB'],
+                        new LocalPharFile('fileA', 'contentA'),
+                        new LocalPharFile('fileB', 'contentB'),
                     ],
                     $symbolsRegistry1,
                 ),
                 new TaskResult(
                     [
-                        ['fileC', 'contentC'],
-                        ['fileD', 'contentD'],
+                        new LocalPharFile('fileC', 'contentC'),
+                        new LocalPharFile('fileD', 'contentD'),
                     ],
                     $symbolsRegistry2,
                 ),
             ],
             new TaskResult(
                 [
-                    ['fileA', 'contentA'],
-                    ['fileB', 'contentB'],
-                    ['fileC', 'contentC'],
-                    ['fileD', 'contentD'],
+                    new LocalPharFile('fileA', 'contentA'),
+                    new LocalPharFile('fileB', 'contentB'),
+                    new LocalPharFile('fileC', 'contentC'),
+                    new LocalPharFile('fileD', 'contentD'),
                 ],
                 $expectedSymbolsRegistry,
             ),