create-nevela 0.1.5 → 0.2.1

package/template/laravel/src/Media/ImageOptimizer.php

@@ -0,0 +1,252 @@
+<?php
+
+namespace Nevela\Laravel\Media;
+
+use GdImage;
+use RuntimeException;
+
+/**
+ * Turns an uploaded image into the files worth storing: one that fits the profile's box,
+ * and the profile's named renditions. Pure PHP and GD: no Laravel, no filesystem writes.
+ *
+ * What it does to every image, following Grit's pipeline:
+ *
+ * - Turns it the right way up. A phone stores a portrait photo sideways with a note saying
+ *   so (EXIF orientation); the note is applied to the pixels, then dropped with the rest of
+ *   the metadata, which also removes the location the photo was taken at.
+ * - Scales it down to fit, never up.
+ * - Picks the format from the pixels when the profile says "auto": transparency is kept
+ *   (lossless WebP), and everything else becomes lossy WebP, a quarter smaller than a JPEG
+ *   that looks the same. Encoding a transparent logo as JPEG, and giving it a black box,
+ *   can't happen.
+ * - Refuses an image that would decode to more pixels than the profile allows, from its
+ *   header, before any memory is spent on it.
+ */
+final class ImageOptimizer
+{
+    /** The types worth optimising. GIF is left alone: decoding one keeps only its first frame. */
+    public const OPTIMISABLE = ['image/jpeg', 'image/png', 'image/webp', 'image/avif'];
+
+    public static function available(): bool
+    {
+        return function_exists('imagecreatefromstring') && function_exists('imagecopyresampled');
+    }
+
+    /** Whether this build of PHP can write a format. */
+    public static function writes(string $format): bool
+    {
+        return match ($format) {
+            'webp' => function_exists('imagewebp'),
+            'avif' => function_exists('imageavif'),
+            'jpeg' => function_exists('imagejpeg'),
+            'png' => function_exists('imagepng'),
+            default => false,
+        };
+    }
+
+    /**
+     * @return array{
+     *     primary: array{bytes: string, width: int, height: int, mime: string, ext: string},
+     *     renditions: array<string, array{bytes: string, width: int, height: int, mime: string, ext: string}>,
+     *     originalWidth: int,
+     *     originalHeight: int,
+     * }
+     *
+     * @throws RuntimeException when the image can't be read, or is too large to decode safely
+     */
+    public static function transform(string $bytes, Profile $profile): array
+    {
+        if (! self::available()) {
+            throw new RuntimeException('PHP\'s GD extension is not installed, so images are stored as they are uploaded.');
+        }
+        $info = @getimagesizefromstring($bytes);
+        if ($info === false) {
+            throw new RuntimeException('The file is not an image PHP can read.');
+        }
+        [$width, $height] = $info;
+        if ($width < 1 || $height < 1 || $width * $height > $profile->maxPixels) {
+            throw new RuntimeException("The image is {$width}×{$height}, which is more than the ".number_format($profile->maxPixels).' pixels this field allows.');
+        }
+
+        $source = @imagecreatefromstring($bytes);
+        if (! $source instanceof GdImage) {
+            // An animated WebP lands here: GD reads still images only.
+            throw new RuntimeException('The image could not be decoded.');
+        }
+        if (! imageistruecolor($source)) {
+            imagepalettetotruecolor($source);
+        }
+        $source = self::upright($source, $bytes, $info['mime'] ?? '');
+        $width = imagesx($source);
+        $height = imagesy($source);
+
+        $transparent = ($info['mime'] ?? '') !== 'image/jpeg' && self::hasTransparency($source);
+        $format = self::format($profile->format, $transparent);
+
+        $primary = self::render($source, $profile->max, $format, $profile->quality, $transparent);
+
+        // A flat graphic (a diagram, a screenshot) is what PNG is good at: as a PNG it can be
+        // smaller than any lossy version of itself. So a PNG is also written as one, and the
+        // smaller result is kept, with its renditions in the same format so they sit beside
+        // it. It is written again, never copied: a PNG can carry text and location data in
+        // its metadata, and writing it from the pixels is what leaves that behind.
+        if (($info['mime'] ?? '') === 'image/png' && $profile->format === 'auto' && $format !== 'png' && self::writes('png')) {
+            $png = self::render($source, $profile->max, 'png', $profile->quality, $transparent);
+            if (strlen($png['bytes']) < strlen($primary['bytes'])) {
+                $format = 'png';
+                $primary = $png;
+            }
+        }
+
+        $result = [
+            'primary' => $primary,
+            'renditions' => [],
+            'originalWidth' => $width,
+            'originalHeight' => $height,
+        ];
+        foreach ($profile->renditions as $name => $size) {
+            $result['renditions'][$name] = self::render($source, $size, $format, $profile->quality, $transparent);
+        }
+
+        return $result;
+    }
+
+    /**
+     * What "auto" means for this image, and what to fall back to when PHP can't write the
+     * format that was asked for.
+     */
+    public static function format(string $wanted, bool $transparent): string
+    {
+        if ($wanted !== 'auto' && self::writes($wanted)) {
+            return $wanted;
+        }
+        if (self::writes('webp')) {
+            return 'webp';
+        }
+
+        return $transparent ? 'png' : 'jpeg';
+    }
+
+    /** Apply the EXIF orientation of a JPEG to its pixels. */
+    private static function upright(GdImage $image, string $bytes, string $mime): GdImage
+    {
+        if ($mime !== 'image/jpeg' || ! function_exists('exif_read_data')) {
+            return $image;
+        }
+        $exif = @exif_read_data('data://image/jpeg;base64,'.base64_encode($bytes));
+        $orientation = is_array($exif) ? (int) ($exif['Orientation'] ?? 1) : 1;
+
+        // imagerotate turns anticlockwise, so 90° clockwise is -90.
+        $turn = match ($orientation) {
+            3, 4 => 180,
+            5, 6 => -90,
+            7, 8 => 90,
+            default => 0,
+        };
+        if ($turn !== 0) {
+            $rotated = imagerotate($image, $turn, 0);
+            if ($rotated instanceof GdImage) {
+                $image = $rotated;
+            }
+        }
+        if (in_array($orientation, [2, 4, 5, 7], true)) {
+            imageflip($image, IMG_FLIP_HORIZONTAL);
+        }
+
+        return $image;
+    }
+
+    /**
+     * Whether any part of the image is see-through enough to matter. Checked on a small
+     * copy: reading twelve million pixels one by one in PHP takes seconds, and averaging
+     * them down first finds every transparent area a person could see.
+     */
+    private static function hasTransparency(GdImage $image): bool
+    {
+        $side = 48;
+        $small = imagecreatetruecolor($side, $side);
+        imagealphablending($small, false);
+        imagesavealpha($small, true);
+        imagecopyresampled($small, $image, 0, 0, 0, 0, $side, $side, imagesx($image), imagesy($image));
+        for ($y = 0; $y < $side; $y++) {
+            for ($x = 0; $x < $side; $x++) {
+                // The top 7 bits are alpha: 0 is solid, 127 is fully transparent.
+                if (((imagecolorat($small, $x, $y) >> 24) & 0x7F) > 2) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @param  array{0: int, 1: int, 2: bool}  $size
+     * @return array{bytes: string, width: int, height: int, mime: string, ext: string}
+     */
+    private static function render(GdImage $source, array $size, string $format, int $quality, bool $transparent): array
+    {
+        [$boxWidth, $boxHeight, $crop] = $size;
+        $width = imagesx($source);
+        $height = imagesy($source);
+        $fromX = $fromY = 0;
+        $fromWidth = $width;
+        $fromHeight = $height;
+
+        if ($crop) {
+            // Take the largest centred area with the box's shape, then scale that down.
+            $ratio = $boxWidth / $boxHeight;
+            if ($width / $height > $ratio) {
+                $fromWidth = max(1, (int) round($height * $ratio));
+                $fromX = intdiv($width - $fromWidth, 2);
+            } else {
+                $fromHeight = max(1, (int) round($width / $ratio));
+                $fromY = intdiv($height - $fromHeight, 2);
+            }
+        }
+        $scale = min(1, $boxWidth / $fromWidth, $boxHeight / $fromHeight);
+        $toWidth = max(1, (int) round($fromWidth * $scale));
+        $toHeight = max(1, (int) round($fromHeight * $scale));
+
+        $keepAlpha = $transparent && $format !== 'jpeg';
+        $target = imagecreatetruecolor($toWidth, $toHeight);
+        if ($keepAlpha) {
+            imagealphablending($target, false);
+            imagesavealpha($target, true);
+            imagefill($target, 0, 0, imagecolorallocatealpha($target, 0, 0, 0, 127));
+        } else {
+            // Anything see-through is put on white, not on the black a JPEG would give it.
+            imagefill($target, 0, 0, imagecolorallocate($target, 255, 255, 255));
+        }
+        imagecopyresampled($target, $source, 0, 0, $fromX, $fromY, $toWidth, $toHeight, $fromWidth, $fromHeight);
+
+        ob_start();
+        $written = match ($format) {
+            // Lossless when there is transparency to keep: a logo's edges don't survive lossy.
+            'webp' => imagewebp($target, null, $keepAlpha && defined('IMG_WEBP_LOSSLESS') ? IMG_WEBP_LOSSLESS : $quality),
+            'avif' => imageavif($target, null, $quality),
+            'png' => imagepng($target, null, 9),
+            default => self::jpeg($target, $quality),
+        };
+        $bytes = (string) ob_get_clean();
+        if (! $written || $bytes === '') {
+            throw new RuntimeException("The image could not be written as {$format}.");
+        }
+
+        return [
+            'bytes' => $bytes,
+            'width' => $toWidth,
+            'height' => $toHeight,
+            'mime' => 'image/'.$format,
+            'ext' => $format === 'jpeg' ? 'jpg' : $format,
+        ];
+    }
+
+    private static function jpeg(GdImage $image, int $quality): bool
+    {
+        // Progressive: the picture appears whole and sharpens, instead of arriving top to bottom.
+        imageinterlace($image, true);
+
+        return imagejpeg($image, null, $quality);
+    }
+}

package/template/laravel/src/Media/Profile.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace Nevela\Laravel\Media;
+
+/**
+ * How one image field's uploads are optimised. The idea and the numbers are Grit's.
+ *
+ * Every default is one somebody would otherwise have to research:
+ *
+ *   1600  covers a 2x display at a typical content width. Storing more keeps pixels no
+ *         browser will draw.
+ *   82    the quality at which a lossy image is indistinguishable from its source. Below
+ *         about 75, gradients and skin start to show artefacts.
+ *   400   the thumbnail a table row or a grid of cards needs at 2x.
+ *
+ * Profiles are plain arrays in config/nevela.php, under uploads.profiles. A named profile
+ * only says what differs from the default.
+ */
+final class Profile
+{
+    public const FORMATS = ['auto', 'webp', 'jpeg', 'png', 'avif'];
+
+    public const DEFAULTS = [
+        'max' => [1600, 1600],
+        'quality' => 82,
+        'format' => 'auto',
+        'renditions' => ['thumb' => [400, 400, 'crop']],
+        'keep_original' => true,
+        'on_error' => 'store_original',
+        'max_pixels' => 50_000_000,
+    ];
+
+    /**
+     * @param  array{0: int, 1: int, 2: bool}  $max  The box the stored image fits inside: width, height, crop to fill
+     * @param  int  $quality  1 to 100, for lossy formats
+     * @param  string  $format  One of FORMATS. "auto" keeps transparency and otherwise picks the smallest
+     * @param  array<string, array{0: int, 1: int, 2: bool}>  $renditions  Extra sizes made alongside, by name
+     * @param  bool  $keepOriginal  Whether the untouched upload is kept, privately, for reprocessing
+     * @param  bool  $reject  Whether an image that can't be optimised is refused, rather than stored as it came
+     * @param  int  $maxPixels  Refuse anything that would decode to more than this (a decompression bomb is small on disk)
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly array $max,
+        public readonly int $quality,
+        public readonly string $format,
+        public readonly array $renditions,
+        public readonly bool $keepOriginal,
+        public readonly bool $reject,
+        public readonly int $maxPixels,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $options  What this profile sets
+     * @param  array<string, mixed>  $defaults  What it falls back to: the app's "default" profile
+     */
+    public static function fromArray(string $name, array $options, array $defaults = []): self
+    {
+        $o = $options + $defaults + self::DEFAULTS;
+        $renditions = [];
+        foreach ((array) $o['renditions'] as $key => $size) {
+            if (preg_match('/^[a-z][a-z0-9-]*$/', (string) $key)) {
+                $renditions[(string) $key] = self::size((array) $size);
+            }
+        }
+        $quality = (int) $o['quality'];
+
+        return new self(
+            $name,
+            self::size((array) $o['max']),
+            $quality >= 1 && $quality <= 100 ? $quality : self::DEFAULTS['quality'],
+            in_array($o['format'], self::FORMATS, true) ? $o['format'] : 'auto',
+            $renditions,
+            (bool) $o['keep_original'],
+            $o['on_error'] === 'reject',
+            max(1, (int) $o['max_pixels']),
+        );
+    }
+
+    /**
+     * [width, height] fits inside the box; a third value of "crop" (or true) fills it exactly.
+     *
+     * @param  array<int, mixed>  $size
+     * @return array{0: int, 1: int, 2: bool}
+     */
+    private static function size(array $size): array
+    {
+        $size = array_values($size);
+        $width = max(1, (int) ($size[0] ?? self::DEFAULTS['max'][0]));
+        $height = max(1, (int) ($size[1] ?? $width));
+
+        return [$width, $height, in_array($size[2] ?? false, ['crop', 'fill', true], true)];
+    }
+}

package/template/laravel/src/Media/UploadRejected.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Nevela\Laravel\Media;
+
+use RuntimeException;
+
+/** An upload the field's profile refuses, with a message fit to show the person who sent it. */
+final class UploadRejected extends RuntimeException {}

package/template/laravel/src/Media/Uploads.php

@@ -0,0 +1,325 @@
+<?php
+
+namespace Nevela\Laravel\Media;
+
+use Illuminate\Contracts\Filesystem\Filesystem;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+use Nevela\Laravel\Models\Upload;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Field;
+use RuntimeException;
+use Throwable;
+
+/**
+ * Stores uploaded files and answers questions about them.
+ *
+ * A record's file field holds a key such as
+ * `products/image/2026/10/<uuid>-kettle.webp`. An image's renditions sit beside it with
+ * their name before the extension (`…-kettle.thumb.webp`), so a client that knows the key
+ * can ask for a size without looking anything up. The untouched original is kept on a
+ * private disk, so the image can be optimised again later with different settings.
+ */
+final class Uploads
+{
+    /** @var array<string, Upload|null> Rows already looked up in this request, by key. */
+    private static array $loaded = [];
+
+    public static function disk(): string
+    {
+        return (string) config('nevela.uploads.disk', 'public');
+    }
+
+    public static function maxBytes(): int
+    {
+        return (int) config('nevela.uploads.max_bytes', 10 * 1024 * 1024);
+    }
+
+    /** The profile a field names, or the default when it names none or one that isn't defined. */
+    public static function profile(?string $name): Profile
+    {
+        $profiles = (array) config('nevela.uploads.profiles', []);
+        $default = (array) ($profiles['default'] ?? []);
+        if ($name === null || $name === 'default' || ! isset($profiles[$name])) {
+            return Profile::fromArray('default', $default);
+        }
+
+        return Profile::fromArray($name, (array) $profiles[$name], $default);
+    }
+
+    /**
+     * Store one upload, optimising it first when it is an image for an image field.
+     *
+     * @param  string  $name  The file's name as the person had it
+     * @param  string  $path  Where the uploaded bytes are on this machine
+     * @param  string  $mime  What the file is, from its contents
+     *
+     * @throws UploadRejected when the field's profile refuses images it can't optimise
+     */
+    public static function store(Descriptor $resource, Field $field, string $name, string $path, string $mime, ?string $uploadedBy = null): Upload
+    {
+        $disk = Storage::disk(self::disk());
+        $extension = FileTypes::safeExtension($name);
+        $slug = Str::limit(Str::slug(pathinfo($name, PATHINFO_FILENAME)) ?: 'file', 60, '');
+        $base = sprintf('%s/%s/%s/%s-%s', $resource->table, $field->name, date('Y/m'), (string) Str::uuid(), $slug);
+        $bytes = (string) file_get_contents($path);
+
+        $row = [
+            'disk' => self::disk(),
+            'resource' => $resource->name,
+            'field' => $field->name,
+            'name' => Str::limit($name, 200, ''),
+            'uploaded_by' => $uploadedBy,
+        ];
+        $profile = self::profile($field->profile);
+
+        if ($field->isImage() && in_array($mime, ImageOptimizer::OPTIMISABLE, true)) {
+            $written = [];
+            $originals = Storage::disk((string) config('nevela.uploads.originals_disk', 'local'));
+            $originalKey = null;
+            try {
+                self::makeRoom();
+                $result = ImageOptimizer::transform($bytes, $profile);
+                $primary = $result['primary'];
+                $key = "{$base}.{$primary['ext']}";
+                self::write($disk, $written[] = $key, $primary['bytes'], 'public');
+
+                $renditions = [];
+                foreach ($result['renditions'] as $rendition => $image) {
+                    $renditionKey = "{$base}.{$rendition}.{$image['ext']}";
+                    self::write($disk, $written[] = $renditionKey, $image['bytes'], 'public');
+                    $renditions[$rendition] = ['key' => $renditionKey, 'width' => $image['width'], 'height' => $image['height'], 'size' => strlen($image['bytes'])];
+                }
+
+                if ($profile->keepOriginal) {
+                    $originalKey = "nevela/originals/{$base}.{$extension}";
+                    self::write($originals, $originalKey, $bytes);
+                }
+
+                return self::remember(Upload::create($row + [
+                    'key' => $key,
+                    'mime' => $primary['mime'],
+                    'size' => strlen($primary['bytes']),
+                    'width' => $primary['width'],
+                    'height' => $primary['height'],
+                    'renditions' => $renditions,
+                    'profile' => $profile->name,
+                    'optimised' => true,
+                    'original_key' => $originalKey,
+                    'original_size' => strlen($bytes),
+                ]));
+            } catch (Throwable $e) {
+                // Whatever was written before it failed is taken away again: no half-made sets.
+                $disk->delete($written);
+                if ($originalKey !== null) {
+                    $originals->delete($originalKey);
+                }
+                if ($profile->reject) {
+                    throw new UploadRejected($e->getMessage(), previous: $e);
+                }
+                // Losing somebody's file because an encoder choked is worse than storing a
+                // large one. It is kept as it came and marked, so it can be found later.
+                report($e);
+            }
+        }
+
+        $key = "{$base}.{$extension}";
+        self::write($disk, $key, $bytes, 'public');
+        $size = str_starts_with($mime, 'image/') ? @getimagesizefromstring($bytes) : false;
+
+        return self::remember(Upload::create($row + [
+            'key' => $key,
+            'mime' => $mime,
+            'size' => strlen($bytes),
+            'width' => $size ? $size[0] : null,
+            'height' => $size ? $size[1] : null,
+            'profile' => $field->isImage() ? $profile->name : null,
+            'optimised' => false,
+        ]));
+    }
+
+    /** The address a browser can fetch a stored file from. */
+    public static function url(string $key): string
+    {
+        $base = config('nevela.uploads.url');
+        if (is_string($base) && $base !== '') {
+            return rtrim($base, '/').'/'.ltrim($key, '/');
+        }
+
+        return route('nevela.files.show', ['path' => $key]);
+    }
+
+    /**
+     * Look up many keys in one query, so a page of records with images costs one extra
+     * query and not one per record.
+     *
+     * @param  iterable<string|null>  $keys
+     */
+    public static function preload(iterable $keys): void
+    {
+        $missing = [];
+        foreach ($keys as $key) {
+            if (is_string($key) && $key !== '' && ! array_key_exists($key, self::$loaded)) {
+                $missing[$key] = true;
+            }
+        }
+        if ($missing === []) {
+            return;
+        }
+        foreach (array_keys($missing) as $key) {
+            self::$loaded[$key] = null;
+        }
+        foreach (Upload::query()->whereIn('key', array_keys($missing))->get() as $upload) {
+            self::$loaded[$upload->key] = $upload;
+        }
+    }
+
+    public static function find(string $key): ?Upload
+    {
+        self::preload([$key]);
+
+        return self::$loaded[$key];
+    }
+
+    /**
+     * Everything a client needs to show a file well: its address, its dimensions (so the
+     * page doesn't jump when the image arrives) and each rendition's.
+     *
+     * @return array<string, mixed>|null
+     */
+    public static function ref(?string $key): ?array
+    {
+        if ($key === null || $key === '') {
+            return null;
+        }
+        $upload = self::find($key);
+        if ($upload === null) {
+            return ['key' => $key, 'url' => self::url($key)];
+        }
+        $renditions = [];
+        foreach ($upload->renditions ?? [] as $name => $rendition) {
+            $renditions[$name] = [
+                'url' => self::url($rendition['key']),
+                'width' => $rendition['width'],
+                'height' => $rendition['height'],
+                'size' => $rendition['size'],
+            ];
+        }
+
+        return [
+            'key' => $upload->key,
+            'url' => self::url($upload->key),
+            'name' => $upload->name,
+            'mime' => $upload->mime,
+            'size' => $upload->size,
+            'width' => $upload->width,
+            'height' => $upload->height,
+            'optimised' => $upload->optimised,
+            'renditions' => (object) $renditions,
+        ];
+    }
+
+    public static function forget(): void
+    {
+        self::$loaded = [];
+    }
+
+    /**
+     * A few pictures to seed an image field with, made here so a seeded shop has something
+     * to look at without downloading anything. They go through the same optimiser as a
+     * real upload, so their renditions exist too.
+     *
+     * @return list<string> keys
+     */
+    public static function placeholders(Descriptor $resource, Field $field, int $count = 6): array
+    {
+        if (! ImageOptimizer::available() || ! function_exists('imagepng')) {
+            return [];
+        }
+        $palette = [[111, 0, 255], [0, 168, 150], [240, 113, 103], [38, 70, 83], [233, 196, 106], [72, 149, 239], [155, 93, 229], [42, 157, 143]];
+        $keys = [];
+        for ($i = 0; $i < $count; $i++) {
+            [$r, $g, $b] = $palette[$i % count($palette)];
+            $image = imagecreatetruecolor(800, 800);
+            // A soft top-to-bottom gradient with a lighter disc: enough to tell cards apart.
+            for ($y = 0; $y < 800; $y++) {
+                $shade = 1 - $y / 1600;
+                imageline($image, 0, $y, 799, $y, imagecolorallocate($image, (int) ($r * $shade), (int) ($g * $shade), (int) ($b * $shade)));
+            }
+            $light = imagecolorallocate($image, min(255, $r + 90), min(255, $g + 90), min(255, $b + 90));
+            imagefilledellipse($image, 400, 400, 360, 360, $light);
+            imagefilledellipse($image, 400, 400, 200, 200, imagecolorallocate($image, 255, 255, 255));
+
+            $path = self::scratchFile();
+            imagepng($image, $path);
+            try {
+                $keys[] = self::store($resource, $field, strtolower("{$resource->name}-".($i + 1).'.png'), $path, 'image/png')->key;
+            } finally {
+                @unlink($path);
+            }
+        }
+
+        return $keys;
+    }
+
+    /**
+     * A path for a file that lives for one request. In the app's own storage, not the system's
+     * temporary folder: a web server's PHP often can't write there, and tempnam() then picks
+     * somewhere else and says so with a notice Laravel treats as an error.
+     */
+    public static function scratchFile(): string
+    {
+        $dir = storage_path('framework/cache/nevela');
+        if (! is_dir($dir)) {
+            @mkdir($dir, 0775, true);
+        }
+
+        return $dir.DIRECTORY_SEPARATOR.Str::uuid().'.tmp';
+    }
+
+    /**
+     * Write a file, and fail loudly if it wasn't written. Laravel's disks answer false by
+     * default instead of throwing, and a record must never point at a file that isn't there.
+     *
+     * @throws RuntimeException
+     */
+    private static function write(Filesystem $disk, string $key, string $bytes, ?string $visibility = null): void
+    {
+        $stored = $visibility === null ? $disk->put($key, $bytes) : $disk->put($key, $bytes, $visibility);
+        if ($stored === false) {
+            throw new RuntimeException("The file could not be written to storage ({$key}). Check the disk in config/nevela.php and that it is writable.");
+        }
+    }
+
+    private static function remember(Upload $upload): Upload
+    {
+        return self::$loaded[$upload->key] = $upload;
+    }
+
+    /**
+     * Decoding a photo needs about five bytes per pixel, which a 12-megapixel phone picture
+     * takes past PHP's usual 128 MB. Raised for this request only.
+     */
+    private static function makeRoom(): void
+    {
+        $wanted = (string) config('nevela.uploads.memory', '512M');
+        $bytes = fn (string $value): int => (int) $value * match (strtoupper(substr(trim($value), -1))) {
+            'G' => 1024 ** 3,
+            'M' => 1024 ** 2,
+            'K' => 1024,
+            default => 1,
+        };
+        $current = (string) ini_get('memory_limit');
+        if ($current !== '-1' && $bytes($current) < $bytes($wanted)) {
+            @ini_set('memory_limit', $wanted);
+        }
+    }
+
+    /** @throws RuntimeException */
+    public static function assertStorable(): void
+    {
+        if (! array_key_exists(self::disk(), (array) config('filesystems.disks', []))) {
+            throw new RuntimeException('The disk "'.self::disk().'" in config/nevela.php (uploads.disk) is not defined in config/filesystems.php.');
+        }
+    }
+}