feat(upload): add batch storeMany API with tests and docs

Co-authored-by: Claude <noreply@anthropic.com>

Author: dadajuice

docs/uploads.md

@@ -38,6 +38,21 @@ $relativePath = $uploader->store($upload, 'avatars');
 
 `store()` returns a path relative to the destination root (for example `avatars/a1b2c3...jpg`).
 
+### Batch upload
+
+`storeMany()` accepts a `list<FileUpload>` and returns paths in the same order.
+Processing stops on the first failure and throws the same `UploadException` as `store()`.
+
+```php
+/** @var list<string> $paths */
+$paths = $uploader->storeMany(
+    FileUpload::listFromPhpArray($_FILES['photos']),
+    'photos',
+);
+```
+
+An empty list returns an empty array immediately.
+
 ## Request normalization
 
 `Request::fromGlobals()` normalizes `$_FILES` entries into `FileUpload` objects:

src/Zephyrus/Upload/Uploader.php

@@ -46,6 +46,31 @@ public function __construct(
         }, $this->allowedMimeTypes), static fn (string $mimeType): bool => $mimeType !== ''));
     }
 
+    /**
+     * Persists multiple uploads in order and returns their relative paths.
+     *
+     * Each file is validated and stored via `store()`, sharing the same optional
+     * `$subDirectory`.  Processing stops immediately on the first failure and the
+     * same `UploadException` is re-thrown, leaving previously stored files in place.
+     *
+     * @param list<FileUpload> $files       Uploads to persist.
+     * @param string|null      $subDirectory Optional sub-path applied to every file.
+     *
+     * @return list<string> Relative paths in the same order as `$files`.
+     *
+     * @throws UploadException On the first validation or move failure.
+     */
+    public function storeMany(array $files, ?string $subDirectory = null): array
+    {
+        $paths = [];
+
+        foreach ($files as $file) {
+            $paths[] = $this->store($file, $subDirectory);
+        }
+
+        return $paths;
+    }
+
     /**
      * Persists the upload to disk and returns its path relative to `$destinationRoot`.
      *

tests/Unit/Upload/UploaderTest.php

@@ -385,4 +385,60 @@ public function test_store_rejects_double_dot_as_target_name(): void
             $this->removeDir($dest);
         }
     }
+
+    // ------------------------------------------------------------------
+    // storeMany
+    // ------------------------------------------------------------------
+
+    public function test_store_many_returns_empty_array_for_empty_input(): void
+    {
+        $dest = $this->makeTempDir();
+
+        $paths = (new Uploader($dest))->storeMany([]);
+
+        self::assertSame([], $paths);
+
+        $this->removeDir($dest);
+    }
+
+    public function test_store_many_returns_relative_paths_in_order(): void
+    {
+        $dest = $this->makeTempDir();
+        $files = [
+            $this->makeValidFile('a.txt'),
+            $this->makeValidFile('b.txt'),
+            $this->makeValidFile('c.txt'),
+        ];
+
+        $paths = (new Uploader($dest))->storeMany($files, 'batch');
+
+        self::assertCount(3, $paths);
+        foreach ($paths as $path) {
+            self::assertStringStartsWith('batch/', $path);
+            self::assertFileExists($dest . '/' . $path);
+        }
+        self::assertCount(3, array_unique($paths), 'Each file should receive a unique name.');
+
+        $this->removeDir($dest);
+    }
+
+    public function test_store_many_stops_on_first_invalid_file(): void
+    {
+        $dest = $this->makeTempDir();
+        $files = [
+            $this->makeValidFile('first.txt'),
+            new FileUpload('bad.txt', '', '/tmp/bad', 0, UPLOAD_ERR_NO_FILE),
+            $this->makeValidFile('third.txt'),
+        ];
+
+        try {
+            $this->expectException(UploadException::class);
+            (new Uploader($dest))->storeMany($files);
+        } finally {
+            // Only the first file should have been written.
+            $stored = glob($dest . '/*');
+            self::assertCount(1, $stored ?: []);
+            $this->removeDir($dest);
+        }
+    }
 }