create-nevela 0.1.5 → 0.2.1

package/template/laravel/src/Console/UpdateCommand.php

@@ -45,7 +45,48 @@ final class UpdateCommand extends Command
             $this->modernizeDevScript();
         }
 
-        return $this->updateDashboard($check);
+        $status = $this->updateDashboard($check);
+
+        // A new version may bring a table of its own (uploads did). Say so, don't run it:
+        // changing a database is the developer's call.
+        if (! $check && ($pending = $this->pendingMigrations()) > 0) {
+            $this->newLine();
+            $this->components->warn("{$pending} migration(s) have not been run. Run them before using the app: php nevela migrate");
+        }
+
+        return $status;
+    }
+
+    /** What the app's composer.json asks for, or an empty string when it can't be read. */
+    public static function rootConstraint(string $composerJson): string
+    {
+        $manifest = json_decode($composerJson, true);
+
+        return is_array($manifest) && is_string($manifest['require']['nevela/laravel'] ?? null) ? trim($manifest['require']['nevela/laravel']) : '';
+    }
+
+    /**
+     * Whether a constraint is the kind the installer writes ("^0.1", "^0.1.3") and nothing
+     * more: the only kind an update moves on its own.
+     */
+    public static function isPlainCaret(string $constraint): bool
+    {
+        return preg_match('/^\^\d+\.\d+(\.\d+)?$/', $constraint) === 1;
+    }
+
+    private function pendingMigrations(): int
+    {
+        try {
+            $migrator = app('migrator');
+            if (! $migrator->repositoryExists()) {
+                return 0;
+            }
+            $files = $migrator->getMigrationFiles([...$migrator->paths(), database_path('migrations')]);
+
+            return count(array_diff(array_keys($files), $migrator->getRepository()->getRan()));
+        } catch (\Throwable) {
+            return 0;
+        }
     }
 
     /**
@@ -115,9 +156,29 @@ final class UpdateCommand extends Command
         $source = (string) @file_get_contents(base_path('vendor/nevela/laravel/src/Nevela.php'));
         $now = preg_match("/const VERSION = '([^']+)'/", $source, $m) ? $m[1] : $installed;
         if ($now === $installed) {
-            $this->components->warn("Composer kept {$installed}: the constraint in composer.json doesn't allow {$latest}. Set \"nevela/laravel\" to \"^".implode('.', array_slice(explode('.', $latest), 0, 2)).'" there and run this again.');
+            // composer.json's range doesn't reach the new version: below 1.0, "^0.1" stops
+            // at 0.1.x. Updating is asking for the newest, so ask Composer for the range
+            // that has it. `require` rewrites composer.json and installs in one step.
+            $range = '^'.implode('.', array_slice(explode('.', $latest), 0, 2));
+            $current = self::rootConstraint((string) @file_get_contents(base_path('composer.json')));
+            if (! self::isPlainCaret($current)) {
+                // A pin, a branch or a hand-written range is somebody's decision. It is left
+                // as it is, and the update stops here.
+                $this->components->warn("Composer kept {$installed}: composer.json asks for \"{$current}\", which doesn't allow {$latest}. That looks deliberate, so it was left alone. To move, set \"nevela/laravel\" to \"{$range}\" there and run this again.");
+
+                return null;
+            }
+            $this->components->info("composer.json asks for \"{$current}\", which doesn't reach {$latest}. Moving \"nevela/laravel\" to \"{$range}\".");
+            $require = new Process(['composer', 'require', "nevela/laravel:{$range}", '--no-interaction', '--no-progress', '--update-with-dependencies'], base_path(), null, null, null);
+            $require->run(fn ($type, $buffer) => $this->output->write($buffer));
 
-            return null;
+            $source = (string) @file_get_contents(base_path('vendor/nevela/laravel/src/Nevela.php'));
+            $now = preg_match("/const VERSION = '([^']+)'/", $source, $m) ? $m[1] : $installed;
+            if (! $require->isSuccessful() || $now === $installed) {
+                $this->components->warn("Composer kept {$installed}. Set \"nevela/laravel\" to \"{$range}\" in composer.json, see what Composer says about it, and run this again.");
+
+                return null;
+            }
         }
 
         // The package's own files have just been replaced. Finish in a new process, so the

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -19,24 +19,77 @@ final class ResourceGenerator
 
     private const E = '// '.Writer::END;
 
-    /** @return list<GeneratedFile> */
-    public function forResource(Descriptor $d, ?string $timestamp = null): array
+    /**
+     * @param  list<Descriptor>  $all  Every resource in the app: a relation is written on both ends
+     * @return list<GeneratedFile>
+     */
+    public function forResource(Descriptor $d, ?string $timestamp = null, array $all = []): array
     {
         $timestamp ??= date('Y_m_d_His');
         $api = GeneratedFile::TARGET_API;
 
         return [
-            new GeneratedFile($api, "app/Models/{$d->name}.php", $this->model($d)),
-            new GeneratedFile($api, "database/migrations/{$timestamp}_create_{$d->table}_table.php", $this->migration($d), GeneratedFile::MODE_ONCE, "database/migrations/*_create_{$d->table}_table.php"),
-            new GeneratedFile($api, "app/Http/Requests/Nevela/{$d->name}Request.php", $this->request($d)),
+            new GeneratedFile($api, "app/Models/{$d->name}.php", $this->model($d, $all)),
+            new GeneratedFile($api, "database/migrations/{$timestamp}_create_{$d->table}_table.php", $this->migration($d, $all), GeneratedFile::MODE_ONCE, "database/migrations/*_create_{$d->table}_table.php"),
+            new GeneratedFile($api, "app/Http/Requests/Nevela/{$d->name}Request.php", $this->request($d, $all)),
             new GeneratedFile($api, "app/Http/Resources/Nevela/{$d->name}Resource.php", $this->resource($d)),
-            new GeneratedFile($api, "app/Http/Controllers/Api/{$d->name}Controller.php", $this->controller($d)),
+            new GeneratedFile($api, "app/Http/Controllers/Api/{$d->name}Controller.php", $this->controller($d, $all)),
             new GeneratedFile($api, "app/Policies/{$d->name}Policy.php", $this->policy($d), GeneratedFile::MODE_ONCE),
-            new GeneratedFile(GeneratedFile::TARGET_WEB, 'resources/'.Naming::kebab($d->name).'.resource.ts', $this->typescript($d)),
+            new GeneratedFile(GeneratedFile::TARGET_WEB, 'resources/'.Naming::kebab($d->name).'.resource.ts', $this->typescript($d, $all)),
             ...$this->pages($d),
         ];
     }
 
+    /**
+     * The resources that point at this one, each with the field that does it and the name
+     * the relation gets here: a Category's Products are `products`. A second field from
+     * the same resource is named after itself (`productsAsFeaturedCategory`), and a name
+     * already taken by one of this resource's own fields is left out.
+     *
+     * @param  list<Descriptor>  $all
+     * @return list<array{resource: Descriptor, field: Field, name: string}>
+     */
+    public function children(Descriptor $d, array $all): array
+    {
+        $taken = [];
+        foreach ($d->fields as $field) {
+            $taken[$field->name] = true;
+            if ($field->kind === 'belongsTo') {
+                $taken[$field->relation()] = true;
+            }
+        }
+        $children = [];
+        usort($all, fn (Descriptor $a, Descriptor $b) => strcmp($a->name, $b->name));
+        foreach ($all as $other) {
+            $plural = Naming::camel(Naming::plural($other->name));
+            foreach ($other->fields as $field) {
+                if ($field->kind !== 'belongsTo' || $field->target !== $d->name) {
+                    continue;
+                }
+                $name = isset($taken[$plural]) ? $plural.'As'.ucfirst($field->relation()) : $plural;
+                if (isset($taken[$name])) {
+                    continue;
+                }
+                $taken[$name] = true;
+                $children[] = ['resource' => $other, 'field' => $field, 'name' => $name];
+            }
+        }
+
+        return $children;
+    }
+
+    /** @param list<Descriptor> $all */
+    private function tableOf(string $name, Descriptor $d, array $all): string
+    {
+        foreach ([$d, ...$all] as $candidate) {
+            if ($candidate->name === $name) {
+                return $candidate->table;
+            }
+        }
+
+        return Naming::snake(Naming::plural($name));
+    }
+
     /**
      * The dashboard pages for a resource, in Flare's layout: list, new, detail and edit,
      * each with its loading skeleton. They only name the descriptor — Flare's components
@@ -288,8 +341,31 @@ final class ResourceGenerator
         PHP);
     }
 
-    public function model(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function model(Descriptor $d, array $all = []): string
     {
+        $relations = [];
+        foreach ($d->fields as $f) {
+            if ($f->kind === 'belongsTo') {
+                $relations[] = <<<PHP
+
+            public function {$f->relation()}(): \Illuminate\Database\Eloquent\Relations\BelongsTo
+            {
+                return \$this->belongsTo({$f->target}::class, '{$f->column()}');
+            }
+        PHP;
+            }
+        }
+        foreach ($this->children($d, $all) as $child) {
+            $relations[] = <<<PHP
+
+            public function {$child['name']}(): \Illuminate\Database\Eloquent\Relations\HasMany
+            {
+                return \$this->hasMany({$child['resource']->name}::class, '{$child['field']->column()}');
+            }
+        PHP;
+        }
+        $relationBlock = $relations ? "\n".implode("\n", array_map(fn (string $r) => rtrim($r), $relations)) : '';
         $fillable = implode(', ', array_map(fn (Field $f) => "'{$f->column()}'", $d->fields));
         $casts = [];
         foreach ($d->fields as $f) {
@@ -331,21 +407,33 @@ final class ResourceGenerator
                 return [
         {$castBlock}
                 ];
-            }
+            }{$relationBlock}
             {$e}
 
-            // Relationships, scopes and accessors go here — outside the generated block.
+            // Your own relationships, scopes and accessors go here — outside the generated block.
         }
 
         PHP;
     }
 
-    public function migration(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function migration(Descriptor $d, array $all = []): string
     {
         $columns = [];
         foreach ($d->fields as $f) {
             $c = $f->column();
+            if ($f->kind === 'belongsTo') {
+                // A required parent can't be deleted while it has children; an optional one lets go of them.
+                $columns[] = "            \$table->foreignUuid('{$c}')"
+                    .($f->required ? '' : '->nullable()')
+                    .($f->unique ? '->unique()' : '->index()')
+                    ."->constrained('{$this->tableOf((string) $f->target, $d, $all)}')"
+                    .($f->required ? '' : '->nullOnDelete()').';';
+
+                continue;
+            }
             $line = match (true) {
+                $f->kind === 'file' => "\$table->string('{$c}', 512)",
                 $f->kind === 'text' => "\$table->text('{$c}')",
                 $f->kind === 'int' => "\$table->integer('{$c}')",
                 $f->kind === 'float' && $f->format === 'money' => "\$table->decimal('{$c}', 12, 2)",
@@ -396,14 +484,15 @@ final class ResourceGenerator
         PHP;
     }
 
-    public function request(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function request(Descriptor $d, array $all = []): string
     {
         $var = $d->variable();
         $param = $d->routeParameter();
         $rules = [];
         $columns = [];
         foreach ($d->fields as $f) {
-            $rules[] = "            '{$f->name}' => [".implode(', ', $this->rules($d, $f)).'],';
+            $rules[] = "            '{$f->name}' => [".implode(', ', $this->rules($d, $f, $all)).'],';
             $columns[] = "'{$f->name}' => '{$f->column()}'";
         }
         $ruleLines = implode("\n", $rules);
@@ -456,11 +545,16 @@ final class ResourceGenerator
         PHP;
     }
 
-    /** @return list<string> PHP expressions */
-    private function rules(Descriptor $d, Field $f): array
+    /**
+     * @param  list<Descriptor>  $all
+     * @return list<string> PHP expressions
+     */
+    private function rules(Descriptor $d, Field $f, array $all = []): array
     {
         $rules = [$f->required ? "'required'" : "'nullable'"];
         $type = match (true) {
+            $f->kind === 'belongsTo' => ["'uuid'", "Rule::exists('{$this->tableOf((string) $f->target, $d, $all)}', 'id')"],
+            $f->kind === 'file' => ["'string'", "'max:512'", "new \\Nevela\\Laravel\\Rules\\UploadKey('{$d->name}', '{$f->name}')"],
             $f->format === 'email' => ["'email'", "'max:255'"],
             $f->format === 'url' => ["'url'", "'max:2048'"],
             $f->format === 'tel' => ["'string'", "'max:32'"],
@@ -495,6 +589,10 @@ final class ResourceGenerator
                 default => "\$this->{$f->column()}",
             };
             $lines[] = "            '{$f->name}' => {$value},";
+            if ($f->kind === 'file') {
+                // The key is what a record stores; this is what a page needs to show it.
+                $lines[] = "            '{$f->name}File' => \\Nevela\\Laravel\\Nevela::file(\$this->{$f->column()}),";
+            }
         }
         $body = implode("\n", $lines);
         $m = self::M;
@@ -529,9 +627,28 @@ final class ResourceGenerator
         PHP;
     }
 
-    public function controller(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function controller(Descriptor $d, array $all = []): string
     {
         $var = $d->variable();
+        $guards = [];
+        foreach ($this->children($d, $all) as $child) {
+            if (! $child['field']->required) {
+                continue; // the database clears an optional link itself
+            }
+            $one = strtolower($child['resource']->label);
+            $many = strtolower($child['resource']->pluralLabel);
+            $parent = $this->lower($d->label);
+            $guards[] = <<<PHP
+                if ((\$count = \\App\\Models\\{$child['resource']->name}::query()->where('{$child['field']->column()}', \${$var}->getKey())->count()) > 0) {
+                    return response()->json(['error' => \$count === 1
+                        ? '1 {$one} belongs to this {$parent}. Move or delete it first.'
+                        : "{\$count} {$many} belong to this {$parent}. Move or delete them first."], 409);
+                }
+        PHP;
+        }
+        $guardBlock = $guards ? "\n".implode("\n", array_map(fn (string $g) => rtrim($g), $guards)) : '';
+        $destroyReturn = $guards ? 'Response|JsonResponse' : 'Response';
         $m = self::M;
         $e = self::E;
 
@@ -595,9 +712,9 @@ final class ResourceGenerator
                 return new {$d->name}Resource(\${$var}->refresh());
             }
 
-            public function destroy({$d->name} \${$var}): Response
+            public function destroy({$d->name} \${$var}): {$destroyReturn}
             {
-                Gate::authorize('delete', \${$var});
+                Gate::authorize('delete', \${$var});{$guardBlock}
                 \${$var}->delete();
 
                 return response()->noContent();
@@ -608,6 +725,11 @@ final class ResourceGenerator
         PHP;
     }
 
+    private function lower(string $label): string
+    {
+        return strtolower($label);
+    }
+
     public function policy(Descriptor $d): string
     {
         $var = $d->variable();
@@ -657,7 +779,8 @@ final class ResourceGenerator
         PHP;
     }
 
-    public function typescript(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function typescript(Descriptor $d, array $all = []): string
     {
         $j = fn (mixed $v) => json_encode($v, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
         $config = [
@@ -683,15 +806,24 @@ final class ResourceGenerator
                 'unique' => $f->unique ? 'true' : null,
                 'label' => $f->label ? $j($f->label) : null,
                 'format' => in_array($f->format, ['money', 'percent', 'rating'], true) ? $j($f->format) : null,
+                // What the migration does when the parent goes: an optional link is cleared.
+                'onDelete' => $f->kind === 'belongsTo' && ! $f->required ? '"set null"' : null,
+                // A picture is worth a column in the table; other files are not.
+                'list' => $f->isImage() ? 'true' : null,
             ]);
             $opts = $options ? '{ '.implode(', ', array_map(fn ($k, $v) => "{$k}: {$v}", array_keys($options), $options)).' }' : '';
             $call = match (true) {
+                $f->kind === 'belongsTo' => "field.belongsTo({$j($f->target)}".($opts ? ", {$opts}" : '').')',
+                $f->kind === 'file' => "field.file({$j($f->accept)}".($opts ? ", {$opts}" : '').')',
                 $f->kind === 'enum' => "field.enum({$j($f->options)}".($opts ? ", {$opts}" : '').')',
                 $f->kind === 'string' && $f->format !== null => "field.{$f->format}({$opts})",
                 default => "field.{$f->kind}({$opts})",
             };
             $fields[] = "    {$f->name}: {$call},";
         }
+        foreach ($this->children($d, $all) as $child) {
+            $fields[] = "    {$child['name']}: field.hasMany({$j($child['resource']->name)}, { foreignKey: {$j($child['field']->name)} }),";
+        }
         $configLines = implode("\n", $config);
         $fieldLines = implode("\n", $fields);
         $file = Naming::kebab($d->name);

package/template/laravel/src/Http/ResourceRequest.php

@@ -41,8 +41,11 @@ abstract class ResourceRequest extends FormRequest
     {
         $validator->after(function (Validator $validator) {
             $known = array_keys($this->columns());
+            // A file field is sent back with its details beside it (imageFile for image);
+            // a client that echoes a record shouldn't be refused for it.
+            $computed = array_map(fn (string $field) => $field.'File', $known);
             foreach (array_keys($this->json()->all() ?: $this->request->all()) as $key) {
-                if (! in_array($key, $known, true) && ! in_array($key, self::READ_ONLY, true)) {
+                if (! in_array($key, $known, true) && ! in_array($key, self::READ_ONLY, true) && ! in_array($key, $computed, true)) {
                     $validator->errors()->add((string) $key, 'Unknown field.');
                 }
             }

package/template/laravel/src/Http/UploadController.php

@@ -0,0 +1,147 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Gate;
+use Illuminate\Support\Facades\Storage;
+use InvalidArgumentException;
+use Nevela\Laravel\Media\FileTypes;
+use Nevela\Laravel\Media\UploadRejected;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Models\Upload;
+use Nevela\Laravel\Nevela;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Receiving files and handing them back.
+ *
+ *   PUT {prefix}/_nevela/uploads/{Resource}/{field}?name=kettle.jpg   the file is the request body
+ *   GET {prefix}/_nevela/files/{key}                                  the stored file
+ *
+ * The body is the file itself, not a form: that is what a browser's upload progress
+ * works with, and it isn't held to PHP's 2 MB default for form uploads.
+ */
+final class UploadController
+{
+    public function store(Request $request, string $resource, string $field): JsonResponse
+    {
+        try {
+            $descriptor = Nevela::resource($resource);
+        } catch (InvalidArgumentException) {
+            return $this->refuse(404, "There is no resource called {$resource}.");
+        }
+        $definition = $descriptor->fields[$field] ?? null;
+        if ($definition === null || $definition->kind !== 'file') {
+            return $this->refuse(404, "{$resource} has no file field called {$field}.");
+        }
+        $model = 'App\\Models\\'.$descriptor->name;
+        // Storing a file is a write, so it takes the permission to create a record. Being
+        // allowed to look at the resource is not enough.
+        if (class_exists($model) && Gate::getPolicyFor($model) !== null && ! Gate::allows('create', $model)) {
+            return $this->refuse(403, "You can't upload files to {$descriptor->pluralLabel}.");
+        }
+
+        $name = basename(str_replace('\\', '/', (string) $request->query('name', 'file')));
+        $limit = Uploads::maxBytes();
+        $megabytes = round($limit / 1024 / 1024, 1);
+        if ((int) $request->header('Content-Length', '0') > $limit) {
+            return $this->refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
+        }
+
+        // Copied to a temporary file with the limit enforced while it arrives: the length
+        // a client declares is not something to rely on.
+        $path = Uploads::scratchFile();
+
+        try {
+            $out = fopen($path, 'wb');
+            try {
+                $written = stream_copy_to_stream($request->getContent(true), $out, $limit + 1);
+            } finally {
+                fclose($out);
+            }
+            if ($written === false || $written === 0) {
+                return $this->refuse(422, 'The upload arrived empty. Try again.');
+            }
+            if ($written > $limit) {
+                return $this->refuse(413, "{$name} is larger than the {$megabytes} MB this field takes.");
+            }
+
+            $mime = FileTypes::sniff($path);
+            $declared = (string) $request->header('Content-Type', 'application/octet-stream');
+            // The contents decide. What was declared only has to agree with them.
+            $effective = FileTypes::accepts($definition->accept, $mime) ? $mime : $declared;
+            if (FileTypes::forbidden($mime) || ! FileTypes::accepts($definition->accept, $effective) || ! FileTypes::consistent($declared, $mime)) {
+                $wanted = in_array('any', $definition->accept, true) ? 'a file this field can store' : implode(' or ', $definition->accept).' data';
+
+                return $this->refuse(422, "{$name} doesn't contain {$wanted}. It may have been renamed; choose the original file.");
+            }
+
+            try {
+                $upload = Uploads::store($descriptor, $definition, $name, $path, strtolower(trim(explode(';', $effective)[0])), (string) ($request->user()?->getAuthIdentifier() ?? '') ?: null);
+            } catch (UploadRejected $e) {
+                return $this->refuse(422, $e->getMessage());
+            }
+
+            return response()->json(Uploads::ref($upload->key), 201);
+        } finally {
+            @unlink($path);
+        }
+    }
+
+    /**
+     * A stored file. Keys are unguessable and never reused, so the response can be cached
+     * for good. Asking for a rendition that was never made (the image wasn't one that could
+     * be optimised) gets the file itself, so a client can always ask for a thumbnail.
+     */
+    public function show(string $path): Response
+    {
+        // A key is letters, digits, dashes, dots and slashes. Anything else was never one.
+        if ($path === '' || str_contains($path, '..') || ! preg_match('#^[A-Za-z0-9][A-Za-z0-9._/-]*$#', $path)) {
+            abort(404);
+        }
+        $cache ='public, max-age=31536000, immutable';
+
+        // Only what was uploaded through Nevela is served, found by its record. The disk may
+        // hold other things, and being on the disk is not a reason to hand a file out.
+        $upload = Upload::query()->where('key', $path)->first();
+        if ($upload === null) {
+            // Not a stored image: a rendition, then. "kettle.thumb.webp" belongs to the upload
+            // whose key is "kettle" and one extension.
+            $base = preg_replace('/\.[a-z][a-z0-9-]*\.[A-Za-z0-9]+$/', '', $path);
+            if ($base === null || $base === $path) {
+                abort(404);
+            }
+            // LIKE narrows it down; the exact comparison after it is what decides. ("_" in a
+            // key is a wildcard to LIKE, and how to escape it differs between databases.)
+            $upload = Upload::query()->where('key', 'like', $base.'.%')->limit(20)->get()
+                ->first(fn (Upload $candidate) => str_starts_with($candidate->key, $base.'.')
+                    && preg_match('/^\.[A-Za-z0-9]+$/', substr($candidate->key, strlen($base))) === 1);
+            if ($upload === null) {
+                abort(404);
+            }
+            if (! in_array($path, array_column($upload->renditions ?? [], 'key'), true)) {
+                // A rendition that was never made: the image itself, so a client can always
+                // ask for a thumbnail. Cached briefly, in case one is made later.
+                $path = $upload->key;
+                $cache = 'public, max-age=300';
+            }
+        }
+
+        $disk = Storage::disk($upload->disk);
+        if (! $disk->exists($path)) {
+            abort(404);
+        }
+
+        return $disk->response($path, null, [
+            'Cache-Control' => $cache,
+            'X-Content-Type-Options' => 'nosniff',
+        ]);
+    }
+
+    private function refuse(int $status, string $message): JsonResponse
+    {
+        return response()->json(['error' => $message], $status);
+    }
+}

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

@@ -0,0 +1,97 @@
+<?php
+
+namespace Nevela\Laravel\Media;
+
+/**
+ * What each of Flare's file categories lets through. The same lists the dashboard's
+ * upload widget checks in the browser; this is the check that counts.
+ */
+final class FileTypes
+{
+    public const CATEGORIES = [
+        'any' => ['*/*'],
+        'image' => ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/avif'],
+        'pdf' => ['application/pdf'],
+        'video' => ['video/*'],
+        'audio' => ['audio/*'],
+        'text' => ['text/plain'],
+        'csv' => ['text/csv'],
+        'document' => ['application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.oasis.opendocument.text'],
+        'spreadsheet' => ['application/vnd.ms-excel', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.oasis.opendocument.spreadsheet'],
+        'archive' => ['application/zip', 'application/x-zip-compressed', 'application/x-zip', 'application/gzip', 'application/x-gzip', 'application/x-7z-compressed', 'application/vnd.rar', 'application/x-rar-compressed'],
+    ];
+
+    /** Types a browser would run or render as a page. Never stored, whatever a field accepts. */
+    private const NEVER = ['text/html', 'application/xhtml+xml', 'image/svg+xml', 'application/javascript', 'text/javascript', 'application/x-httpd-php', 'text/x-php', 'application/x-msdownload', 'application/x-dosexec'];
+
+    /** Extensions a web server might run or a browser might render as a page. */
+    private const NEVER_EXTENSIONS = ['html', 'htm', 'xhtml', 'shtml', 'svg', 'svgz', 'js', 'mjs', 'php', 'phtml', 'phar', 'exe', 'dll', 'bat', 'cmd', 'com', 'msi', 'sh', 'cgi', 'pl', 'py', 'jsp', 'asp', 'aspx', 'htaccess'];
+
+    public static function forbidden(string $mime): bool
+    {
+        return in_array(strtolower(trim(explode(';', $mime)[0])), self::NEVER, true);
+    }
+
+    /** The extension a file is stored with: its own, unless that one could be run or rendered. */
+    public static function safeExtension(string $name): string
+    {
+        $extension = strtolower(pathinfo($name, PATHINFO_EXTENSION));
+
+        return $extension !== '' && preg_match('/^[a-z0-9]{1,10}$/', $extension) && ! in_array($extension, self::NEVER_EXTENSIONS, true) ? $extension : 'bin';
+    }
+
+    /**
+     * @param  list<string>  $accept  Categories, e.g. ["image", "pdf"]
+     */
+    public static function accepts(array $accept, string $mime): bool
+    {
+        $mime = strtolower(trim(explode(';', $mime)[0]));
+        if ($mime === '' || self::forbidden($mime)) {
+            return false;
+        }
+        foreach ($accept as $category) {
+            foreach (self::CATEGORIES[$category] ?? [] as $pattern) {
+                if ($pattern === '*/*' || $pattern === $mime || (str_ends_with($pattern, '/*') && str_starts_with($mime, substr($pattern, 0, -1)))) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * What a file is, from its contents. The type a browser sends is only a label, and a
+     * renamed file carries the wrong one.
+     */
+    public static function sniff(string $path): string
+    {
+        $mime = function_exists('finfo_open') ? (string) @finfo_file(finfo_open(FILEINFO_MIME_TYPE), $path) : '';
+
+        return $mime !== '' ? strtolower($mime) : 'application/octet-stream';
+    }
+
+    /**
+     * Whether what a file contains fits what it was sent as. Office documents and CSVs are
+     * containers and plain text underneath, so those are compared by family, not exactly.
+     */
+    public static function consistent(string $declared, string $sniffed): bool
+    {
+        $declared = strtolower(trim(explode(';', $declared)[0]));
+        if ($declared === $sniffed) {
+            return true;
+        }
+        $family = fn (string $mime) => explode('/', $mime)[0];
+        if (in_array($family($declared), ['image', 'video', 'audio'], true)) {
+            return $family($declared) === $family($sniffed);
+        }
+        if ($declared === 'application/pdf') {
+            return false;
+        }
+
+        // Zip-based documents, text formats and anything finfo has no opinion on.
+        return in_array($sniffed, ['application/zip', 'application/octet-stream', 'text/plain', 'application/csv', 'text/csv', 'application/x-ole-storage', 'application/cdfv2'], true)
+            || str_starts_with($sniffed, 'application/vnd.')
+            || str_starts_with($sniffed, 'application/x-');
+    }
+}