create-nevela 0.5.1 → 0.5.3

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

@@ -0,0 +1,190 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Trash\Trash;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/**
+ * The trash: deleted records, by resource, to restore or to remove for good.
+ *
+ * One controller for every resource, where everything else about a resource is generated.
+ * The trash asks the same three questions of all of them (what was deleted, bring it back,
+ * get rid of it), and a generated copy per resource would be the same file many times.
+ *
+ * Who may use it is the resource's own policy: `restore` and `forceDelete` where it has
+ * them, and what it says to `delete` where it was written before there was a trash.
+ */
+final class TrashController
+{
+    /**
+     * GET _nevela/trash/_status: which resources have a trash this person may use, and how
+     * long it keeps things. Nothing is counted and nothing is removed: this is asked on
+     * the way to drawing a delete button, to say truthfully what pressing it will do.
+     */
+    public function status(): JsonResponse
+    {
+        $slugs = [];
+        foreach (Trash::resources() as ['descriptor' => $descriptor, 'model' => $model]) {
+            if (Trash::maySee($model)) {
+                $slugs[] = $descriptor->slug;
+            }
+        }
+
+        return response()->json(['days' => Trash::days(), 'resources' => $slugs]);
+    }
+
+    /**
+     * GET _nevela/trash: how long things are kept, and how much of each resource is in it.
+     * Only the resources this person may deal with. Anything past its time goes first.
+     */
+    public function index(): JsonResponse
+    {
+        Trash::purgeExpired();
+
+        $resources = [];
+        foreach (Trash::resources() as ['descriptor' => $descriptor, 'model' => $model]) {
+            if (! Trash::maySee($model)) {
+                continue;
+            }
+            $resources[] = [
+                'name' => $descriptor->name,
+                'label' => $descriptor->label,
+                'pluralLabel' => $descriptor->pluralLabel,
+                'slug' => $descriptor->slug,
+                'icon' => $descriptor->icon,
+                'count' => $model::onlyTrashed()->count(),
+            ];
+        }
+
+        return response()->json(['days' => Trash::days(), 'resources' => $resources]);
+    }
+
+    /** GET _nevela/trash/{slug}?page=&perPage=: one resource's deleted records, the latest deletion first. */
+    public function show(Request $request, string $slug): JsonResponse
+    {
+        ['descriptor' => $descriptor, 'model' => $model] = $this->resource($slug);
+        $input = $request->validate(['page' => ['nullable', 'integer', 'min:1'], 'perPage' => ['nullable', 'integer', 'min:1', 'max:100']]);
+        Trash::purgeExpired($model);
+
+        $instance = new $model;
+        $page = $model::onlyTrashed()
+            ->orderByDesc($instance->getQualifiedDeletedAtColumn())->orderBy($instance->getQualifiedKeyName())
+            ->paginate((int) ($input['perPage'] ?? 25), ['*'], 'page', (int) ($input['page'] ?? 1));
+
+        return response()->json([
+            'data' => $page->getCollection()->map(fn ($record) => [
+                'id' => (string) $record->getKey(),
+                'label' => self::label($descriptor, $record),
+                'deletedAt' => $record->{$record->getDeletedAtColumn()}?->toJSON(),
+                'expiresAt' => Trash::expires($record->{$record->getDeletedAtColumn()})?->toJSON(),
+            ])->all(),
+            'meta' => ['page' => $page->currentPage(), 'perPage' => $page->perPage(), 'total' => $page->total(), 'totalPages' => max(1, $page->lastPage())],
+        ]);
+    }
+
+    /** POST _nevela/trash/{slug}/{id}/restore: back into the list, as it was. */
+    public function restore(string $slug, string $id): JsonResponse
+    {
+        ['descriptor' => $descriptor, 'model' => $model] = $this->resource($slug);
+        $record = $model::onlyTrashed()->find($id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
+        if (! Trash::may('restore', $record)) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+
+        // A record that must belong to another can't come back while that other is itself deleted.
+        foreach ($descriptor->fields as $field) {
+            if ($field->kind !== 'belongsTo' || ! $field->required) {
+                continue;
+            }
+            $parent = "App\\Models\\{$field->target}";
+            $key = $record->{$field->column()};
+            if ($key !== null && class_exists($parent) && method_exists($parent, 'trashes') && $parent::trashes() && $parent::onlyTrashed()->whereKey($key)->exists()) {
+                $what = strtolower($field->target);
+
+                return response()->json(['error' => "Its {$what} is in the trash too. Restore the {$what} first.", 'code' => 'PARENT_IN_TRASH'], 409);
+            }
+        }
+        $record->restore();
+
+        return response()->json(['id' => (string) $record->getKey(), 'restored' => true]);
+    }
+
+    /** DELETE _nevela/trash/{slug}/{id}: gone for good. */
+    public function destroy(string $slug, string $id): JsonResponse|Response
+    {
+        ['descriptor' => $descriptor, 'model' => $model] = $this->resource($slug);
+        $record = $model::onlyTrashed()->find($id) ?? throw new NotFoundHttpException("No deleted {$this->noun($descriptor)} with that id.");
+        if (! Trash::may('forceDelete', $record)) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+        if (! Trash::purge($record)) {
+            return response()->json(['error' => 'Other records in the trash still belong to this one. Delete those for good first.', 'code' => 'STILL_REFERENCED'], 409);
+        }
+
+        return response()->noContent();
+    }
+
+    /**
+     * DELETE _nevela/trash/{slug}?confirm={slug}: everything of one resource, for good.
+     * The slug has to be said again, so that this can't be the result of a mistyped address.
+     */
+    public function empty(Request $request, string $slug): JsonResponse
+    {
+        ['model' => $model] = $this->resource($slug);
+        if ($request->query('confirm') !== $slug) {
+            return response()->json(['error' => "To empty this trash, send confirm={$slug}.", 'code' => 'CONFIRM'], 422);
+        }
+        $removed = 0;
+        $kept = 0;
+        $instance = new $model;
+        $model::onlyTrashed()->orderBy($instance->getQualifiedKeyName())->chunkById(200, function ($records) use (&$removed, &$kept) {
+            foreach ($records as $record) {
+                if (Trash::may('forceDelete', $record) && Trash::purge($record)) {
+                    $removed++;
+                } else {
+                    $kept++;
+                }
+            }
+        });
+
+        return response()->json(['removed' => $removed, 'kept' => $kept]);
+    }
+
+    /** @return array{descriptor: Descriptor, model: class-string<\Illuminate\Database\Eloquent\Model>} */
+    private function resource(string $slug): array
+    {
+        $resource = Trash::resource($slug) ?? throw new NotFoundHttpException('This resource has no trash.');
+        if (! Trash::maySee($resource['model'])) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+
+        return $resource;
+    }
+
+    private function noun(Descriptor $descriptor): string
+    {
+        return strtolower($descriptor->label);
+    }
+
+    /** What to call a deleted record: its title, the way a list would, and its id when it has none. */
+    private static function label(Descriptor $descriptor, mixed $record): string
+    {
+        // The field the descriptor names, or the first piece of text it has, as the dashboard does.
+        $field = $descriptor->titleField !== null ? ($descriptor->fields[$descriptor->titleField] ?? null) : null;
+        foreach ($field === null ? $descriptor->fields : [] as $candidate) {
+            if ($candidate->kind === 'string') {
+                $field = $candidate;
+                break;
+            }
+        }
+        $value = $field ? $record->getAttribute($field->column()) : null;
+
+        return is_scalar($value) && (string) $value !== '' ? (string) $value : (string) $record->getKey();
+    }
+}

package/template/laravel/src/Nevela.php

@@ -3,11 +3,14 @@
 namespace Nevela\Laravel;
 
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\UniqueConstraintViolationException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 use InvalidArgumentException;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Insights;
 use Nevela\Laravel\Support\ListQuery;
 use Nevela\Laravel\Support\Naming;
 
@@ -18,7 +21,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.5.1';
+    public const VERSION = '0.5.3';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];
@@ -79,6 +82,35 @@ final class Nevela
             return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
         }
 
+        self::narrow($query, $resource, $list);
+
+        $query->reorder()
+            ->orderBy($list->sort['column'], $list->sort['direction'])
+            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+
+        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+
+        // One query for every file on the page, instead of one per record.
+        foreach ($resource->fields as $field) {
+            if ($field->kind === 'file') {
+                Uploads::preload($page->getCollection()->pluck($field->column()));
+            }
+        }
+
+        return response()->json([
+            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
+            'meta' => [
+                'page' => $page->currentPage(),
+                'perPage' => $page->perPage(),
+                'total' => $page->total(),
+                'totalPages' => max(1, $page->lastPage()),
+            ],
+        ]);
+    }
+
+    /** The search and the filters of a list request, applied. Its insights are narrowed the same way. */
+    private static function narrow(Builder $query, Descriptor $resource, ListQuery $list): void
+    {
         if ($list->q !== null) {
             $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
             if ($columns !== []) {
@@ -96,31 +128,146 @@ final class Nevela
                 ? $query->whereNull($filter['column'])
                 : $query->where($filter['column'], $filter['value']);
         }
+    }
 
-        $query->reorder()
-            ->orderBy($list->sort['column'], $list->sort['direction'])
-            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+    /**
+     * GET /{slug}/_insights?unit=day|week|month&q&filter[field] → { total, unit, series, breakdown }.
+     *
+     * What the dashboard's insights panel draws: how many records were created in each
+     * period, and how they split across each field that is a choice (an enum or a yes/no).
+     *
+     * It takes the list's own search and filters, so the charts describe the rows the
+     * table is showing. A whole-table chart above a filtered table would be wrong in a
+     * prominent place.
+     */
+    public static function insights(Builder $query, string $name, Request $request): JsonResponse
+    {
+        $resource = self::resource($name);
+        $unit = $request->query('unit', 'day');
+        if (! is_string($unit) || ! isset(Insights::PERIODS[$unit])) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'unit', 'message' => 'Must be day, week or month.']]], 400);
+        }
+        // The same parameters as the list. Where in the list someone is makes no difference to a count.
+        $params = array_diff_key($request->query(), array_flip(['unit', 'page', 'perPage', 'sort', 'columns']));
+        $list = ListQuery::parse($resource, $params, (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);
+        }
+        self::narrow($query, $resource, $list);
+        $base = fn () => (clone $query)->reorder();
 
-        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+        // Counted per day by the database, one grouped query over the created_at index,
+        // and added up into weeks or months here: see Support\Insights.
+        $now = now();
+        $table = $query->getModel()->getTable();
+        $day = $query->getConnection()->getDriverName() === 'sqlsrv' ? "CAST({$table}.created_at AS date)" : "DATE({$table}.created_at)";
+        $perDay = $base()->toBase()
+            ->where("{$table}.created_at", '>=', Insights::since($unit, $now))
+            ->selectRaw("{$day} as day, count(*) as aggregate")
+            ->groupByRaw($day)
+            ->get()
+            ->map(fn ($row) => [(string) $row->day, (int) $row->aggregate]);
 
-        // One query for every file on the page, instead of one per record.
+        $breakdown = [];
         foreach ($resource->fields as $field) {
-            if ($field->kind === 'file') {
-                Uploads::preload($page->getCollection()->pluck($field->column()));
+            if (! in_array($field->kind, ['enum', 'boolean'], true)) {
+                continue;
+            }
+            if (count($breakdown) === 4) {
+                break; // one grouped query each, and four charts is already a lot to read
             }
+            $column = $field->column();
+            $counts = [];
+            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
+                $value = $row->value === null ? '' : ($field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value);
+                $counts[$value] = ($counts[$value] ?? 0) + (int) $row->aggregate;
+            }
+            // Every choice the field has, in its own order, so one nobody has picked shows as zero.
+            $values = $field->kind === 'boolean' ? ['true', 'false'] : $field->options;
+            $slices = array_map(fn (string $value) => ['value' => $value, 'count' => $counts[$value] ?? 0], $values);
+            if (($counts[''] ?? 0) > 0) {
+                $slices[] = ['value' => '', 'count' => $counts['']];
+            }
+            $breakdown[] = ['field' => $field->name, 'kind' => $field->kind, 'slices' => $slices];
         }
 
         return response()->json([
-            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
-            'meta' => [
-                'page' => $page->currentPage(),
-                'perPage' => $page->perPage(),
-                'total' => $page->total(),
-                'totalPages' => max(1, $page->lastPage()),
-            ],
+            'total' => $base()->count(),
+            'unit' => $unit,
+            'series' => Insights::series($unit, $now, $perDay),
+            'breakdown' => $breakdown,
         ]);
     }
 
+    /**
+     * POST /{slug}/_bulk { items: [ … ] } → 201 { created, data }, or 422 { error, rows }.
+     *
+     * Several records in one go, for the dashboard's grid. Every row is checked before
+     * anything is written, and they are saved in one transaction: a mistake on row 7
+     * is reported against row 7 and nothing is created, where saving six and stopping
+     * would leave someone working out which six.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelClass
+     * @param  class-string<Http\ResourceRequest>  $requestClass
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function createMany(string $modelClass, string $requestClass, string $resourceClass, Request $request): JsonResponse
+    {
+        $most = max(1, (int) config('nevela.bulk_max', 500));
+        $items = $request->input('items');
+        if (! is_array($items) || ! array_is_list($items) || $items === []) {
+            return response()->json(['error' => 'Send the rows to create as "items", a list with at least one row.'], 422);
+        }
+        if (count($items) > $most) {
+            return response()->json(['error' => 'That is '.number_format(count($items))." rows. At most {$most} can be created at once; for more, import a file."], 422);
+        }
+
+        $checked = (new $requestClass)->many($items);
+        if ($checked['problems'] !== []) {
+            return self::rowsRefused($checked['problems'], count($items));
+        }
+
+        try {
+            $created = DB::transaction(function () use ($modelClass, $checked) {
+                $created = [];
+                foreach ($checked['values'] as $index => $values) {
+                    try {
+                        $created[] = $modelClass::create($values);
+                    } catch (UniqueConstraintViolationException $e) {
+                        // Someone else created the same value between the check and the write.
+                        throw new \RuntimeException((string) ($index + 1), 0, $e);
+                    }
+                }
+
+                return $created;
+            });
+        } catch (\RuntimeException $e) {
+            if (! $e->getPrevious() instanceof UniqueConstraintViolationException) {
+                throw $e;
+            }
+
+            return self::rowsRefused([['row' => (int) $e->getMessage(), 'issues' => [['path' => '', 'message' => 'A record with one of these values was created a moment ago.']]]], count($items));
+        }
+
+        return response()->json([
+            'created' => count($created),
+            'data' => array_map(fn ($model) => (new $resourceClass($model->refresh()))->resolve($request), $created),
+        ], 201);
+    }
+
+    /** @param list<array{row: int, issues: list<array{path: string, message: string}>}> $problems */
+    private static function rowsRefused(array $problems, int $sent): JsonResponse
+    {
+        $wrong = count($problems);
+
+        return response()->json([
+            'error' => $wrong === 1
+                ? "Nothing was created: row {$problems[0]['row']} needs fixing."
+                : "Nothing was created: {$wrong} of the {$sent} rows need fixing.",
+            'rows' => $problems,
+        ], 422);
+    }
+
     /**
      * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
      * What Flare's ResourceStats card shows above a table.

package/template/laravel/src/NevelaServiceProvider.php

@@ -4,6 +4,7 @@ namespace Nevela\Laravel;
 
 use Illuminate\Contracts\Debug\ExceptionHandler;
 use Illuminate\Cache\RateLimiting\Limit;
+use Illuminate\Console\Scheduling\Schedule;
 use Illuminate\Foundation\Console\ServeCommand;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Gate;
@@ -18,6 +19,7 @@ use Nevela\Laravel\Console\MakeResourceCommand;
 use Nevela\Laravel\Console\SeedCommand;
 use Nevela\Laravel\Console\SetupCommand;
 use Nevela\Laravel\Console\StatusCommand;
+use Nevela\Laravel\Console\TrashCommand;
 use Nevela\Laravel\Console\UpdateCommand;
 use Nevela\Laravel\Console\UserCommand;
 use Nevela\Laravel\Console\VersionCommand;
@@ -29,6 +31,7 @@ use Nevela\Laravel\Http\Auth\AccountController;
 use Nevela\Laravel\Http\Auth\SecurityController;
 use Nevela\Laravel\Http\Auth\SignInController;
 use Nevela\Laravel\Http\TokenController;
+use Nevela\Laravel\Http\TrashController;
 use Nevela\Laravel\Http\UploadController;
 use Nevela\Laravel\Media\Uploads;
 
@@ -56,7 +59,15 @@ final class NevelaServiceProvider extends ServiceProvider
             $this->commands([
                 MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
                 UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class, SetupCommand::class,
+                TrashCommand::class,
             ]);
+
+            // What has been in the trash too long is removed each night, wherever the app's
+            // scheduler is running (Laravel's one cron line). Where it isn't, the same thing
+            // happens whenever someone opens the trash.
+            $this->callAfterResolving(Schedule::class, function (Schedule $schedule) {
+                $schedule->command(TrashCommand::class)->dailyAt('03:40')->withoutOverlapping();
+            });
         }
 
         $this->callAfterResolving(ExceptionHandler::class, function ($handler) {
@@ -171,6 +182,14 @@ final class NevelaServiceProvider extends ServiceProvider
                 'data' => array_map(fn ($name) => (array) Uploads::profile($name), array_keys((array) config('nevela.uploads.profiles', ['default' => []]))),
             ]))->name('profiles');
 
+            // The trash: deleted records, to restore or to remove for good.
+            Route::get('_nevela/trash', [TrashController::class, 'index'])->name('trash.index');
+            Route::get('_nevela/trash/_status', [TrashController::class, 'status'])->name('trash.status');
+            Route::get('_nevela/trash/{slug}', [TrashController::class, 'show'])->name('trash.show');
+            Route::post('_nevela/trash/{slug}/{id}/restore', [TrashController::class, 'restore'])->name('trash.restore');
+            Route::delete('_nevela/trash/{slug}/{id}', [TrashController::class, 'destroy'])->name('trash.destroy');
+            Route::delete('_nevela/trash/{slug}', [TrashController::class, 'empty'])->name('trash.empty');
+
             // Users and roles, for whoever holds the permissions to manage them.
             Route::middleware(RolesAreSetUp::class)->group(function () {
                 Route::get('_nevela/users', [UsersController::class, 'index'])->name('users.index');

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

@@ -0,0 +1,78 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Carbon\CarbonImmutable;
+use Carbon\CarbonInterface;
+
+/**
+ * The periods a "created per day, week or month" chart is drawn in.
+ *
+ * The database is only ever asked for counts per day, which every database can give
+ * with the same expression. Weeks and months are added up here, so a week starts on
+ * Monday and a month is a calendar month whichever database is underneath.
+ */
+final class Insights
+{
+    /** How many periods of each kind a chart shows: a month of days, half a year of weeks, a year of months. */
+    public const PERIODS = ['day' => 30, 'week' => 26, 'month' => 12];
+
+    /**
+     * The periods up to and including the one `$now` is in, oldest first.
+     *
+     * @return list<string> A day or a week as "2026-10-05" (a week by its Monday), a month as "2026-10"
+     */
+    public static function buckets(string $unit, CarbonInterface $now): array
+    {
+        $current = CarbonImmutable::instance($now)->startOfDay();
+        $buckets = [];
+        for ($back = self::PERIODS[$unit] - 1; $back >= 0; $back--) {
+            $buckets[] = match ($unit) {
+                'day' => $current->subDays($back)->format('Y-m-d'),
+                'week' => $current->startOfWeek(CarbonInterface::MONDAY)->subWeeks($back)->format('Y-m-d'),
+                // From the first of the month: stepping back from the 31st would skip the short months.
+                'month' => $current->startOfMonth()->subMonthsNoOverflow($back)->format('Y-m'),
+            };
+        }
+
+        return $buckets;
+    }
+
+    /** The first moment the chart covers. */
+    public static function since(string $unit, CarbonInterface $now): CarbonImmutable
+    {
+        $first = self::buckets($unit, $now)[0];
+
+        return CarbonImmutable::parse($unit === 'month' ? "{$first}-01" : $first, $now->getTimezone())->startOfDay();
+    }
+
+    /** Which period a day ("2026-10-09") belongs to. */
+    public static function bucketOf(string $unit, string $day): string
+    {
+        return match ($unit) {
+            'day' => substr($day, 0, 10),
+            'week' => CarbonImmutable::parse(substr($day, 0, 10))->startOfWeek(CarbonInterface::MONDAY)->format('Y-m-d'),
+            'month' => substr($day, 0, 7),
+        };
+    }
+
+    /**
+     * Counts per day, added up into the chart's periods. A period with nothing in it is
+     * still there, as zero: a gap in a chart should look like a gap.
+     *
+     * @param  iterable<array{0: string, 1: int}>  $perDay  Pairs of day and count
+     * @return list<array{bucket: string, count: int}>
+     */
+    public static function series(string $unit, CarbonInterface $now, iterable $perDay): array
+    {
+        $counts = array_fill_keys(self::buckets($unit, $now), 0);
+        foreach ($perDay as [$day, $count]) {
+            $bucket = self::bucketOf($unit, $day);
+            if (isset($counts[$bucket])) {
+                $counts[$bucket] += $count;
+            }
+        }
+
+        return array_map(fn (string $bucket, int $count) => ['bucket' => $bucket, 'count' => $count], array_keys($counts), array_values($counts));
+    }
+}