create-nevela 0.7.1 → 0.8.0

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

@@ -22,6 +22,15 @@ use Throwable;
  */
 final class Uploads
 {
+    /** Who uploaded a file that came in through a public form and hasn't been used in a create yet. */
+    public const UNCLAIMED = 'public:unclaimed';
+
+    /** And one that has: it belongs to a record now, like any other. */
+    public const CLAIMED = 'public';
+
+    /** What every private file's key starts with. */
+    public const PRIVATE_PREFIX = 'private/';
+
     /** @var array<string, Upload|null> Rows already looked up in this request, by key. */
     private static array $loaded = [];
 
@@ -30,6 +39,27 @@ final class Uploads
         return (string) config('nevela.uploads.disk', 'public');
     }
 
+    /** Where private files are kept: a disk the web server doesn't serve. */
+    public static function privateDisk(): string
+    {
+        return (string) config('nevela.uploads.private_disk', 'local');
+    }
+
+    /**
+     * Whether a key is a private file's. It is said by the key itself, so that nothing
+     * which hands out files by key has to look anything up to know it must not.
+     */
+    public static function isPrivate(?string $key): bool
+    {
+        return is_string($key) && str_starts_with($key, self::PRIVATE_PREFIX);
+    }
+
+    /** Where a private file is on its disk, beside the originals Nevela keeps there. */
+    public static function privatePath(string $key): string
+    {
+        return 'nevela/'.$key;
+    }
+
     public static function maxBytes(): int
     {
         return (int) config('nevela.uploads.max_bytes', 10 * 1024 * 1024);
@@ -73,6 +103,23 @@ final class Uploads
         ];
         $profile = self::profile($field->profile);
 
+        // A private file is stored as it came, where the web server doesn't reach. Nothing
+        // is made from it: a thumbnail would be a copy of it on a disk anyone can read.
+        if ($field->private) {
+            $key = self::PRIVATE_PREFIX."{$base}.{$extension}";
+            self::write(Storage::disk(self::privateDisk()), self::privatePath($key), $bytes);
+            $size = str_starts_with($mime, 'image/') ? @getimagesizefromstring($bytes) : false;
+
+            return self::remember(Upload::create(['disk' => self::privateDisk()] + $row + [
+                'key' => $key,
+                'mime' => $mime,
+                'size' => strlen($bytes),
+                'width' => $size ? $size[0] : null,
+                'height' => $size ? $size[1] : null,
+                'optimised' => false,
+            ]));
+        }
+
         if ($field->isImage() && in_array($mime, ImageOptimizer::OPTIMISABLE, true)) {
             $written = [];
             $originals = Storage::disk((string) config('nevela.uploads.originals_disk', 'local'));
@@ -193,6 +240,11 @@ final class Uploads
             return null;
         }
         $upload = self::find($key);
+        // A private file has no address of its own. It is fetched through the record it
+        // belongs to (see privateRef), by someone who may view that record.
+        if (self::isPrivate($key)) {
+            return ['key' => $key, 'url' => null, 'private' => true, 'name' => $upload?->name, 'mime' => $upload?->mime, 'size' => $upload?->size];
+        }
         if ($upload === null) {
             return ['key' => $key, 'url' => self::url($key)];
         }
@@ -219,6 +271,65 @@ final class Uploads
         ];
     }
 
+    /**
+     * A private file as a record shows it: what it is, and the address it is fetched from,
+     * which names the record and the field and never the key.
+     *
+     * @return array<string, mixed>|null
+     */
+    public static function privateRef(?string $key, string $slug, mixed $id, string $field): ?array
+    {
+        $ref = self::ref($key);
+        if ($ref === null || ! self::isPrivate($key)) {
+            return $ref;
+        }
+
+        return ['url' => route('nevela.private.show', ['slug' => $slug, 'id' => $id, 'field' => $field])] + $ref;
+    }
+
+    /**
+     * Remove a private file for good: from its disk, and the record of it. For when the
+     * record it belonged to has been removed for good.
+     */
+    public static function discard(string $key): void
+    {
+        if (! self::isPrivate($key)) {
+            return;
+        }
+        $upload = Upload::query()->where('key', $key)->first();
+        Storage::disk($upload?->disk ?? self::privateDisk())->delete(self::privatePath($key));
+        $upload?->delete();
+        unset(self::$loaded[$key]);
+    }
+
+    /**
+     * Remove what visitors uploaded and never used: a form that was started and left.
+     * Each such file waits an hour for its create (PublicController::CLAIM_SECONDS), and
+     * goes after that, with anything that was made from it.
+     *
+     * @return int How many were removed
+     */
+    public static function purgeUnclaimed(int $olderThanSeconds = 3600): int
+    {
+        $removed = 0;
+        Upload::query()->where('uploaded_by', self::UNCLAIMED)->where('created_at', '<', now()->subSeconds($olderThanSeconds))->orderBy('id')
+            ->chunkById(200, function ($uploads) use (&$removed) {
+                foreach ($uploads as $upload) {
+                    $disk = Storage::disk($upload->disk);
+                    $disk->delete(self::isPrivate($upload->key) ? self::privatePath($upload->key) : $upload->key);
+                    $disk->delete(array_column($upload->renditions ?? [], 'key'));
+                    if ($upload->original_key !== null) {
+                        Storage::disk((string) config('nevela.uploads.originals_disk', 'local'))->delete($upload->original_key);
+                    }
+                    unset(self::$loaded[$upload->key]);
+                    $upload->delete();
+                    $removed++;
+                }
+            });
+
+        return $removed;
+    }
+
     public static function forget(): void
     {
         self::$loaded = [];

package/template/laravel/src/Nevela.php

@@ -7,6 +7,7 @@ use Illuminate\Database\UniqueConstraintViolationException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
 use InvalidArgumentException;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Support\Descriptor;
@@ -21,7 +22,7 @@ use Nevela\Laravel\Support\Naming;
 final class Nevela
 {
     /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.7.1';
+    public const VERSION = '0.8.0';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];
@@ -76,7 +77,18 @@ final class Nevela
      */
     public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
     {
-        $resource = self::resource($name);
+        return self::listFor($query, self::resource($name), $request, $resourceClass);
+    }
+
+    /**
+     * The same, for a descriptor that was handed over and not looked up: the public list
+     * is the resource with only the fields anyone may see, so nothing else can be sorted,
+     * filtered or searched by.
+     *
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function listFor(Builder $query, Descriptor $resource, Request $request, string $resourceClass): JsonResponse
+    {
         $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
         if (! $list->ok()) {
             return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
@@ -124,12 +136,32 @@ final class Nevela
         }
 
         foreach ($list->filters as $filter) {
+            $field = $resource->fields[$filter['field']] ?? null;
+            if ($filter['value'] !== null && $field?->kind === 'belongsTo' && ! self::couldBeId((string) $field->target, (string) $filter['value'])) {
+                // Nothing belongs to a record that can't exist. Asked anyway, some databases
+                // answer a number column given letters with an error instead of with no rows.
+                $query->whereRaw('1 = 0');
+
+                continue;
+            }
             $filter['value'] === null
                 ? $query->whereNull($filter['column'])
                 : $query->where($filter['column'], $filter['value']);
         }
     }
 
+    /** Whether a value has the shape of one of a resource's ids: digits, or a UUID. */
+    private static function couldBeId(string $name, string $value): bool
+    {
+        try {
+            $integers = self::resource($name)->idType === 'int';
+        } catch (InvalidArgumentException) {
+            return true; // not a resource this app describes: its ids are its own business
+        }
+
+        return $integers ? preg_match('/^[0-9]{1,18}$/', $value) === 1 : Str::isUuid($value);
+    }
+
     /**
      * GET /{slug}/_insights?unit=day|week|month&q&filter[field] → { total, unit, series, breakdown }.
      *
@@ -318,6 +350,26 @@ final class Nevela
         return Uploads::ref($key);
     }
 
+    /**
+     * The same for a private file: what it is, and the address it is fetched from by
+     * someone who may view the record, which names the record and never the file's key.
+     *
+     * @return array<string, mixed>|null
+     */
+    public static function privateFile(?string $key, string $slug, mixed $id, string $field): ?array
+    {
+        return Uploads::privateRef($key, $slug, $id, $field);
+    }
+
+    /**
+     * A rich text field's HTML, as it is safe to show: only the tags and attributes in
+     * config('nevela.rich_text'). Generated API resources send every rich text field through it.
+     */
+    public static function html(?string $html): ?string
+    {
+        return $html === null ? null : Support\Html::clean($html);
+    }
+
     /** Whether a request is one Nevela answers (so errors use Flare's shape). */
     public static function handles(Request $request): bool
     {

package/template/laravel/src/NevelaServiceProvider.php

@@ -13,6 +13,7 @@ use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
 use Nevela\Laravel\Access\Access;
 use Nevela\Laravel\Access\Permissions;
+use Nevela\Laravel\Console\AdoptCommand;
 use Nevela\Laravel\Console\DevCommand;
 use Nevela\Laravel\Console\GenerateCommand;
 use Nevela\Laravel\Console\MakeResourceCommand;
@@ -31,7 +32,9 @@ use Nevela\Laravel\Http\FlareErrors;
 use Nevela\Laravel\Http\Auth\AccountController;
 use Nevela\Laravel\Http\Auth\SecurityController;
 use Nevela\Laravel\Http\Auth\SignInController;
+use Nevela\Laravel\Http\PublicThrottle;
 use Nevela\Laravel\Http\TokenController;
+use Nevela\Laravel\Http\ActionController;
 use Nevela\Laravel\Http\TrashController;
 use Nevela\Laravel\Http\UploadController;
 use Nevela\Laravel\Media\Uploads;
@@ -58,7 +61,7 @@ final class NevelaServiceProvider extends ServiceProvider
 
             $this->publishes([__DIR__.'/../config/nevela.php' => config_path('nevela.php')], 'nevela-config');
             $this->commands([
-                MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
+                MakeResourceCommand::class, AdoptCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
                 UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class, SetupCommand::class,
                 TrashCommand::class,
             ]);
@@ -172,12 +175,21 @@ final class NevelaServiceProvider extends ServiceProvider
             'app' => Nevela::fingerprint(),
         ]))->name('nevela.ping');
 
+        Route::aliasMiddleware('nevela.throttle', PublicThrottle::class);
+
+        // What a resource's "public" section opens: no sign-in, and each route its own throttle.
+        if (is_file($open = base_path('routes/nevela-public.php'))) {
+            Route::prefix(trim($prefix.'/public', '/'))->middleware('api')->name('nevela.public.')->group($open);
+        }
+
         // Stored files. Open, like any image on a website: the key is the secret.
         Route::prefix($prefix)->middleware('api')->get('_nevela/files/{path}', [UploadController::class, 'show'])
             ->where('path', '.*')->name('nevela.files.show');
 
         Route::prefix($prefix)->middleware(config('nevela.middleware', ['api', 'auth:sanctum']))->name('nevela.')->group(function () {
             Route::put('_nevela/uploads/{resource}/{field}', [UploadController::class, 'store'])->name('uploads.store');
+            // A private file: only for someone who may view the record it belongs to.
+            Route::get('_nevela/private/{slug}/{id}/{field}', [UploadController::class, 'download'])->name('private.show');
 
             // The image profiles, for a client that wants to know which renditions exist.
             Route::get('_nevela/profiles', fn () => response()->json([
@@ -221,6 +233,10 @@ final class NevelaServiceProvider extends ServiceProvider
                 'data' => array_map(fn ($d) => $d->toArray(), Nevela::all()),
             ]))->name('resources');
 
+            // A resource's own actions: on one record, and on the list or a selection from it.
+            Route::post('{slug}/_actions/{action}', [ActionController::class, 'collection'])->name('actions.collection');
+            Route::post('{slug}/{id}/_actions/{action}', [ActionController::class, 'record'])->name('actions.record');
+
             if (is_file($routes = base_path('routes/nevela.php'))) {
                 require $routes;
             }

package/template/laravel/src/Support/Action.php

@@ -0,0 +1,168 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Validation\Rule;
+use InvalidArgumentException;
+
+/**
+ * Something that can be done to a record, or to a resource as a whole, beyond creating,
+ * editing and deleting it: accept an application, send an announcement.
+ *
+ * The descriptor says what it is called, where its button goes and what it asks for.
+ * What it does is a class of the app's own, written once: App\Nevela\Actions\<Resource>\<Action>.
+ * Between the two, Nevela does the route, the permission, the checking and the button.
+ */
+final class Action
+{
+    /** Where its button is: on one record, or on the list as a whole. */
+    public const ON = ['record', 'collection'];
+
+    /** Names that already mean something for every resource. */
+    public const RESERVED = ['create', 'view', 'edit', 'delete', 'update', 'restore', 'list', 'read'];
+
+    /** What an action can ask for. A picture or a relation is a record's business, not a button's. */
+    public const KINDS = ['string', 'text', 'int', 'float', 'boolean', 'date', 'datetime', 'enum'];
+
+    /**
+     * @param  string  $name  camelCase, as in the descriptor and the address: accept, sendAnnouncement
+     * @param  string|null  $confirm  A question to ask before it runs
+     * @param  array<string, scalar|null>  $when  Field values a record must have for the action to apply to it
+     * @param  array<string, Field>  $fields  What it asks the person for, in a sheet
+     * @param  bool  $many  A record action that can also be run on a selection of rows
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $label,
+        public readonly string $on = 'record',
+        public readonly ?string $icon = null,
+        public readonly ?string $confirm = null,
+        public readonly array $when = [],
+        public readonly array $fields = [],
+        public readonly bool $many = false,
+    ) {
+        if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $name)) {
+            throw new InvalidArgumentException("Action \"{$name}\" must be camelCase, e.g. accept or sendAnnouncement.");
+        }
+        if (in_array(Naming::snake($name), self::RESERVED, true)) {
+            throw new InvalidArgumentException("\"{$name}\" is something every resource does already. Call the action something else.");
+        }
+        if (! in_array($on, self::ON, true)) {
+            throw new InvalidArgumentException("Action \"{$name}\" is on \"{$on}\". Use record or collection.");
+        }
+        if ($on === 'collection' && ($when !== [] || $many)) {
+            throw new InvalidArgumentException("Action \"{$name}\" is on the collection, so it has no one record to check \"when\" against or to select.");
+        }
+        foreach ($when as $field => $value) {
+            if (! is_scalar($value) && $value !== null) {
+                throw new InvalidArgumentException("Action \"{$name}\": \"when\" compares \"{$field}\" with one value, or with null.");
+            }
+        }
+        foreach ($fields as $field) {
+            if (! in_array($field->kind, self::KINDS, true)) {
+                throw new InvalidArgumentException("Action \"{$name}\" can't ask for \"{$field->name}\": a {$field->kind} isn't something a button asks for. Use: ".implode(', ', self::KINDS).'.');
+            }
+        }
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function fromArray(string $name, array $data): self
+    {
+        $fields = [];
+        foreach ((array) ($data['fields'] ?? []) as $key => $field) {
+            $fields[(string) $key] = Field::fromArray((string) $key, (array) $field);
+        }
+
+        return new self(
+            $name,
+            (string) ($data['label'] ?? Naming::humanize($name)),
+            (string) ($data['on'] ?? 'record'),
+            $data['icon'] ?? null,
+            $data['confirm'] ?? null,
+            (array) ($data['when'] ?? []),
+            $fields,
+            (bool) ($data['many'] ?? false),
+        );
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return array_filter([
+            'label' => $this->label,
+            'icon' => $this->icon,
+            'on' => $this->on,
+            'confirm' => $this->confirm,
+            'when' => $this->when ?: null,
+            'fields' => $this->fields ? array_map(fn (Field $f) => $f->toArray(), $this->fields) : null,
+            'many' => $this->many ?: null,
+        ], fn ($v) => $v !== null);
+    }
+
+    /** The second half of its permission: "send_announcement" in "newsletter_subscriptions.send_announcement". */
+    public function key(): string
+    {
+        return Naming::snake($this->name);
+    }
+
+    /** The class that does it, without its namespace: SendAnnouncement. */
+    public function className(): string
+    {
+        return Naming::pascal($this->name);
+    }
+
+    /**
+     * Whether it applies to a record with these values, by field name.
+     *
+     * @param  array<string, mixed>  $values
+     */
+    public function applies(array $values): bool
+    {
+        foreach ($this->when as $field => $wanted) {
+            $value = $values[$field] ?? null;
+            $same = match (true) {
+                $wanted === null => $value === null,
+                $value === null => false,
+                // A yes/no column comes back from some databases as 1 and 0.
+                is_bool($wanted) => (bool) $value === $wanted,
+                default => (string) $value === (string) $wanted,
+            };
+            if (! $same) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The rules its fields are checked by: the ones a resource's field of the same kind has.
+     *
+     * @return array<string, list<mixed>>
+     */
+    public function rules(): array
+    {
+        $rules = [];
+        foreach ($this->fields as $field) {
+            $rules[$field->name] = [$field->required ? 'required' : 'nullable', ...match (true) {
+                $field->format === 'email' => ['email', 'max:'.($field->maxLength ?? 255)],
+                $field->format === 'url' => ['url', 'max:'.($field->maxLength ?? 2048)],
+                $field->format === 'tel' => ['string', 'max:'.($field->maxLength ?? 32)],
+                $field->format === 'slug' => ['string', 'alpha_dash', 'max:'.($field->maxLength ?? 255)],
+                $field->format === 'color' => ['string', 'regex:/^#[0-9a-fA-F]{6}$/'],
+                $field->kind === 'string' => ['string', 'max:'.($field->maxLength ?? 255)],
+                $field->kind === 'text' => ['string', 'max:'.($field->maxLength ?? 65535)],
+                $field->kind === 'int' && $field->format === 'percent' => ['integer', 'between:0,100'],
+                $field->kind === 'int' => ['integer'],
+                $field->kind === 'float' && $field->format === 'percent' => ['numeric', 'between:0,100'],
+                $field->kind === 'float' => ['numeric'],
+                $field->kind === 'boolean' => ['boolean'],
+                $field->kind === 'date' => ['date_format:Y-m-d'],
+                $field->kind === 'datetime' => ['date'],
+                $field->kind === 'enum' => [Rule::in($field->options)],
+            }];
+        }
+
+        return $rules;
+    }
+}