create-nevela 0.1.5 → 0.3.0

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

@@ -1,124 +1,186 @@
-<?php
-
-namespace Nevela\Laravel\Console;
-
-use Illuminate\Console\Command;
-use Illuminate\Database\UniqueConstraintViolationException;
-use Illuminate\Support\Facades\DB;
-use Illuminate\Support\Str;
-use InvalidArgumentException;
-use Nevela\Laravel\Nevela;
-use Nevela\Laravel\Support\Descriptor;
-use Nevela\Laravel\Support\Fake;
-use Symfony\Component\Console\Helper\ProgressBar;
-use Throwable;
-
-final class SeedCommand extends Command
-{
-    protected $signature = 'nevela:seed
-        {name : The resource to fill, e.g. Product}
-        {--count=1000 : How many records to create}
-        {--chunk=500 : Rows per insert statement}
-        {--fresh : Delete the resource\'s existing records first}';
-
-    protected $description = 'Fill a resource with plausible records, and say how long it took';
-
-    private const MAX_COUNT = 5_000_000;
-
-    /** 400 blocks of MAX_COUNT stay under 2^31, so a unique integer column can hold the numbers. */
-    private const BLOCKS = 400;
-
-    private const ATTEMPTS = 5;
-
-    public function handle(): int
-    {
-        try {
-            $resource = Nevela::resource(Str::studly($this->argument('name')));
-        } catch (InvalidArgumentException $e) {
-            $this->components->error($e->getMessage());
-
-            return self::FAILURE;
-        }
-
-        $count = filter_var($this->option('count'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => self::MAX_COUNT]]);
-        $chunk = filter_var($this->option('chunk'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 5000]]);
-        if ($count === false || $chunk === false) {
-            $this->components->error('--count must be between 1 and 5,000,000, and --chunk between 1 and 5,000.');
-
-            return self::FAILURE;
-        }
-
-        // SQLite allows 32,766 bound values per statement; stay well inside it on wide tables.
-        $chunk = min($chunk, max(1, intdiv(30_000, count($resource->fields) + 3)));
-        $fresh = (bool) $this->option('fresh');
-
-        $existing = $fresh ? 0 : (int) DB::table($resource->table)->count();
-        foreach ($resource->fields as $field) {
-            $capacity = Fake::capacity($field);
-            if ($capacity !== null && $existing + $count > $capacity) {
-                $room = number_format(max(0, $capacity - $existing));
-                $this->components->error("\"{$field->name}\" is unique and can only hold ".number_format($capacity)." different values, so there is room for {$room} more {$resource->pluralLabel}, not ".number_format($count).'.');
-
-                return self::FAILURE;
-            }
-        }
-
-        $started = microtime(true);
-        $removed = 0;
-        $bar = $this->output->createProgressBar($count);
-        try {
-            for ($attempt = 1; ; $attempt++) {
-                // Unique fields are numbered from a block of MAX_COUNT picked per run (a run is at
-                // most that long). Two runs only meet if they pick the same block; then the insert
-                // fails, the transaction rolls back and another block is picked.
-                $offset = $fresh && $attempt === 1 ? 0 : mt_rand(0, self::BLOCKS - 1) * self::MAX_COUNT;
-                $bar->start();
-                try {
-                    $removed = DB::transaction(fn () => $this->fill($resource, $count, $chunk, $offset, $fresh, $bar));
-                    break;
-                } catch (UniqueConstraintViolationException $e) {
-                    if ($attempt === self::ATTEMPTS) {
-                        throw $e;
-                    }
-                }
-            }
-            $bar->finish();
-            $this->newLine(2);
-        } catch (Throwable $e) {
-            $this->newLine(2);
-            $this->components->error("Seeding {$resource->pluralLabel} failed, and the table is as it was: ".Str::limit($e->getMessage(), 300));
-
-            return self::FAILURE;
-        }
-        if ($fresh) {
-            $this->components->info('Removed '.number_format($removed)." existing {$resource->pluralLabel}.");
-        }
-
-        $seconds = microtime(true) - $started;
-        $time = $seconds < 1 ? round($seconds * 1000).' ms' : number_format($seconds, 2).' s';
-        $rate = number_format($count / max($seconds, 0.001));
-        $this->components->info('Seeded '.number_format($count)." {$resource->pluralLabel} in {$time} ({$rate} rows/s).");
-        $this->components->twoColumnDetail("{$resource->pluralLabel} in the database", number_format(DB::table($resource->table)->count()));
-
-        return self::SUCCESS;
-    }
-
-    /** Runs inside the transaction: the optional delete and every insert succeed or fail together. */
-    private function fill(Descriptor $resource, int $count, int $chunk, int $offset, bool $fresh, ProgressBar $bar): int
-    {
-        $removed = $fresh ? DB::table($resource->table)->delete() : 0;
-        $now = time();
-        for ($done = 0; $done < $count; $done += $chunk) {
-            $rows = [];
-            for ($i = $done; $i < min($count, $done + $chunk); $i++) {
-                // Spread over the last 60 days, so the dashboard's "this week" and trend have something to show.
-                $created = date('Y-m-d H:i:s', $now - mt_rand(0, 60 * 86400));
-                $rows[] = ['id' => (string) Str::uuid7()] + Fake::row($resource, $offset + $i + 1) + ['created_at' => $created, 'updated_at' => $created];
-            }
-            DB::table($resource->table)->insert($rows);
-            $bar->advance(count($rows));
-        }
-
-        return $removed;
-    }
-}
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Database\UniqueConstraintViolationException;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+use InvalidArgumentException;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Fake;
+use Symfony\Component\Console\Helper\ProgressBar;
+use Throwable;
+
+final class SeedCommand extends Command
+{
+    protected $signature = 'nevela:seed
+        {name : The resource to fill, e.g. Product}
+        {--count=1000 : How many records to create}
+        {--chunk=500 : Rows per insert statement}
+        {--fresh : Delete the resource\'s existing records first}';
+
+    protected $description = 'Fill a resource with plausible records, and say how long it took';
+
+    private const MAX_COUNT = 5_000_000;
+
+    /** 400 blocks of MAX_COUNT stay under 2^31, so a unique integer column can hold the numbers. */
+    private const BLOCKS = 400;
+
+    private const ATTEMPTS = 5;
+
+    public function handle(): int
+    {
+        try {
+            $resource = Nevela::resource(Str::studly($this->argument('name')));
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $count = filter_var($this->option('count'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => self::MAX_COUNT]]);
+        $chunk = filter_var($this->option('chunk'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 5000]]);
+        if ($count === false || $chunk === false) {
+            $this->components->error('--count must be between 1 and 5,000,000, and --chunk between 1 and 5,000.');
+
+            return self::FAILURE;
+        }
+
+        // SQLite allows 32,766 bound values per statement; stay well inside it on wide tables.
+        $chunk = min($chunk, max(1, intdiv(30_000, count($resource->fields) + 3)));
+        $fresh = (bool) $this->option('fresh');
+
+        $existing = $fresh ? 0 : (int) DB::table($resource->table)->count();
+        foreach ($resource->fields as $field) {
+            $capacity = Fake::capacity($field);
+            if ($capacity !== null && $existing + $count > $capacity) {
+                $room = number_format(max(0, $capacity - $existing));
+                $this->components->error("\"{$field->name}\" is unique and can only hold ".number_format($capacity)." different values, so there is room for {$room} more {$resource->pluralLabel}, not ".number_format($count).'.');
+
+                return self::FAILURE;
+            }
+        }
+
+        // --fresh deletes first, and a record others are required to belong to can't be deleted.
+        // Said here, before any placeholder pictures are made for a run that can't happen.
+        if ($fresh) {
+            foreach (Nevela::all() as $other) {
+                foreach ($other->fields as $field) {
+                    if ($field->kind === 'belongsTo' && $field->target === $resource->name && $field->required && $other->name !== $resource->name
+                        && ($children = (int) DB::table($other->table)->count()) > 0) {
+                        $this->components->error(number_format($children)." {$other->pluralLabel} belong to the {$resource->pluralLabel} that --fresh would delete. Remove them first, or seed without --fresh.");
+
+                        return self::FAILURE;
+                    }
+                }
+            }
+        }
+
+        $started = microtime(true);
+        try {
+            $pools = $this->pools($resource);
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+        $removed = 0;
+        $bar = $this->output->createProgressBar($count);
+        try {
+            for ($attempt = 1; ; $attempt++) {
+                // Unique fields are numbered from a block of MAX_COUNT picked per run (a run is at
+                // most that long). Two runs only meet if they pick the same block; then the insert
+                // fails, the transaction rolls back and another block is picked.
+                $offset = $fresh && $attempt === 1 ? 0 : mt_rand(0, self::BLOCKS - 1) * self::MAX_COUNT;
+                $bar->start();
+                try {
+                    $removed = DB::transaction(fn () => $this->fill($resource, $count, $chunk, $offset, $fresh, $bar, $pools));
+                    break;
+                } catch (UniqueConstraintViolationException $e) {
+                    if ($attempt === self::ATTEMPTS) {
+                        throw $e;
+                    }
+                }
+            }
+            $bar->finish();
+            $this->newLine(2);
+        } catch (Throwable $e) {
+            $this->newLine(2);
+            $this->components->error("Seeding {$resource->pluralLabel} failed, and the table is as it was: ".Str::limit($e->getMessage(), 300));
+
+            return self::FAILURE;
+        }
+        if ($fresh) {
+            $this->components->info('Removed '.number_format($removed)." existing {$resource->pluralLabel}.");
+        }
+
+        $seconds = microtime(true) - $started;
+        $time = $seconds < 1 ? round($seconds * 1000).' ms' : number_format($seconds, 2).' s';
+        $rate = number_format($count / max($seconds, 0.001));
+        $this->components->info('Seeded '.number_format($count)." {$resource->pluralLabel} in {$time} ({$rate} rows/s).");
+        $this->components->twoColumnDetail("{$resource->pluralLabel} in the database", number_format(DB::table($resource->table)->count()));
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * What a relation or an image field can be filled with: the records that exist to point
+     * at, and a handful of pictures made for the purpose.
+     *
+     * @return array<string, list<string>>
+     *
+     * @throws InvalidArgumentException when a required field has nothing to draw from
+     */
+    private function pools(Descriptor $resource): array
+    {
+        $pools = [];
+        foreach ($resource->fields as $field) {
+            if ($field->kind === 'belongsTo') {
+                $target = $field->target === $resource->name ? $resource : Nevela::resource((string) $field->target);
+                $ids = DB::table($target->table)->inRandomOrder()->limit(1000)->pluck('id')->map(fn ($id) => (string) $id)->all();
+                if ($field->unique) {
+                    throw new InvalidArgumentException("\"{$field->name}\" is unique, so each {$target->label} can be used once. The seeder doesn't fill one-to-one relations; add those records yourself.");
+                }
+                if ($ids === [] && $field->required && $target->name !== $resource->name) {
+                    throw new InvalidArgumentException("Every {$resource->label} needs a {$target->label}, and there are none yet. Seed them first: php artisan nevela:seed {$target->name}");
+                }
+                $pools[$field->name] = $ids;
+            } elseif ($field->kind === 'file') {
+                $pools[$field->name] = $field->isImage() ? Uploads::placeholders($resource, $field) : [];
+                if ($pools[$field->name] === [] && $field->required) {
+                    throw new InvalidArgumentException($field->isImage()
+                        ? "\"{$field->name}\" is a required image, and PHP's GD extension isn't installed to make placeholder pictures with."
+                        : "\"{$field->name}\" is a required file, which the seeder can't make up. Make it optional ({$field->name}:file(…)?) or add records yourself.");
+                }
+            }
+        }
+
+        return $pools;
+    }
+
+    /**
+     * Runs inside the transaction: the optional delete and every insert succeed or fail together.
+     *
+     * @param  array<string, list<string>>  $pools
+     */
+    private function fill(Descriptor $resource, int $count, int $chunk, int $offset, bool $fresh, ProgressBar $bar, array $pools = []): int
+    {
+        $removed = $fresh ? DB::table($resource->table)->delete() : 0;
+        $now = time();
+        for ($done = 0; $done < $count; $done += $chunk) {
+            $rows = [];
+            for ($i = $done; $i < min($count, $done + $chunk); $i++) {
+                // Spread over the last 60 days, so the dashboard's "this week" and trend have something to show.
+                $created = date('Y-m-d H:i:s', $now - mt_rand(0, 60 * 86400));
+                $rows[] = ['id' => (string) Str::uuid7()] + Fake::row($resource, $offset + $i + 1, $pools) + ['created_at' => $created, 'updated_at' => $created];
+            }
+            DB::table($resource->table)->insert($rows);
+            $bar->advance(count($rows));
+        }
+
+        return $removed;
+    }
+}

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

@@ -30,7 +30,7 @@ final class StatusCommand extends Command
         $latest = Releases::latest();
         $row('Nevela', Nevela::VERSION.match (true) {
             $latest === null => ' <fg=gray>(couldn\'t check for a newer one)</>',
-            version_compare($latest, Nevela::VERSION, '>') => " <fg=yellow>({$latest} is out: php nevela update)</>",
+            version_compare($latest, Nevela::VERSION, '>') => " <fg=yellow>({$latest} is out: php nevela upgrade)</>",
             default => ' <fg=green>(latest)</>',
         });
         $row('Laravel / PHP', app()->version().' / '.PHP_VERSION);
@@ -99,7 +99,7 @@ final class StatusCommand extends Command
             // What this app has made its own. An update leaves every one of these alone.
             $changes = $state->yourChanges($web);
             if ($changes === null) {
-                $row('Your dashboard changes', '<fg=gray>not tracked yet: php nevela update records them</>');
+                $row('Your dashboard changes', '<fg=gray>not tracked yet: php nevela upgrade records them</>');
             } else {
                 $count = count($changes['changed']) + count($changes['deleted']);
                 $row('Your dashboard changes', $count === 0 ? 'none' : "{$count} file(s), kept on every update");

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

@@ -16,12 +16,18 @@ use Throwable;
 
 final class UpdateCommand extends Command
 {
-    protected $signature = 'nevela:update
+    protected $signature = 'nevela:upgrade
         {--check : Show what would change, and change nothing}
-        {--skip-package : Leave the nevela/laravel package as it is; update only the dashboard}
-        {--undo : Put the dashboard back as it was before the last update}';
+        {--skip-package : Leave the nevela/laravel package as it is; upgrade only the dashboard}
+        {--undo : Put the dashboard back as it was before the last upgrade}';
 
-    protected $description = 'Update Nevela: the package, the generated code and the dashboard';
+    /**
+     * The name this command had before 0.3.0, and still answers to. As in Grit, "update"
+     * is now what the nevela command does to itself, and "upgrade" is what it does to an app.
+     */
+    protected $aliases = ['nevela:update'];
+
+    protected $description = 'Bring this app to the latest Nevela: the package, the generated code and the dashboard';
 
     /** Apps created before the dashboard recorded its version all came from this template. */
     private const FIRST_TRACKED = '0.1.1';
@@ -45,7 +51,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,15 +162,35 @@ 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
         // rest runs on the new code instead of a mix of old and new.
         $php = (new PhpExecutableFinder)->find(false) ?: 'php';
-        $rest = new Process([$php, 'artisan', 'nevela:update', '--skip-package'], base_path(), null, null, null);
+        $rest = new Process([$php, 'artisan', 'nevela:upgrade', '--skip-package'], base_path(), null, null, null);
         $rest->run(fn ($type, $buffer) => $this->output->write($buffer));
 
         return $rest->getExitCode() ?? self::FAILURE;
@@ -251,7 +318,7 @@ final class UpdateCommand extends Command
             $state->write($web);
 
             if ($touched) {
-                $this->line("  Every file this replaced was copied to <fg=cyan>{$this->relative($web)}/{$backup}</> first. To put it all back: <fg=cyan>php nevela update --undo</>");
+                $this->line("  Every file this replaced was copied to <fg=cyan>{$this->relative($web)}/{$backup}</> first. To put it all back: <fg=cyan>php nevela upgrade --undo</>");
             }
         }
         if ($done[DashboardUpdate::CONFLICT] !== []) {