Refactor publication commands and create actions

monorepo/HydeStan/HydeStan.php

@@ -31,8 +31,10 @@ public function __destruct()
             number_format(count($this->files)))
         );
 
-        // Forward warnings to GitHub Actions
-        $this->console->line(sprintf("\n%s", implode("\n", self::$warnings)));
+        if (count(self::$warnings) > 0) {
+            // Forward warnings to GitHub Actions
+            $this->console->line(sprintf("\n%s", implode("\n", self::$warnings)));
+        }
     }
 
     public function run(): void

packages/framework/src/Console/Commands/MakePublicationCommand.php

@@ -4,10 +4,11 @@
 
 namespace Hyde\Console\Commands;
 
-use Exception;
 use Hyde\Console\Commands\Interfaces\CommandHandleInterface;
 use Hyde\Console\Concerns\ValidatingCommand;
 use Hyde\Framework\Actions\CreatesNewPublicationFile;
+use Hyde\Framework\Features\Publications\Models\PublicationFieldType;
+use Hyde\Framework\Features\Publications\Models\PublicationType;
 use Hyde\Framework\Features\Publications\PublicationService;
 use Illuminate\Support\Str;
 use InvalidArgumentException;
@@ -17,82 +18,47 @@
 /**
  * Hyde Command to create a new publication for a given publication type.
  *
+ * @see \Hyde\Framework\Actions\CreatesNewPublicationFile
  * @see \Hyde\Framework\Testing\Feature\Commands\MakePublicationCommandTest
  */
 class MakePublicationCommand extends ValidatingCommand implements CommandHandleInterface
 {
     /** @var string */
     protected $signature = 'make:publication
-		{publicationType? : The name of the PublicationType to create a publication for}';
+		{publicationType? : The name of the PublicationType to create a publication for}
+        {--force : Should the generated file overwrite existing publications with the same filename?}';
 
     /** @var string */
     protected $description = 'Create a new publication item';
 
-    public function handle(): int
+    public function safeHandle(): int
     {
         $this->title('Creating a new Publication!');
 
-        $pubTypes = PublicationService::getPublicationTypes();
-        if ($pubTypes->isEmpty()) {
-            $this->output->error('Unable to locate any publication types. Did you create any?');
-
-            return Command::FAILURE;
-        }
-
-        $pubType = $this->argument('publicationType');
-        if (! $pubType) {
-            $this->output->writeln('<bg=magenta;fg=white>Now please choose the Publication Type to create an item for:</>');
-            $offset = 0;
-            foreach ($pubTypes as $pubType) {
-                $offset++;
-                $this->line("  $offset: $pubType->name");
-            }
-            $selected = (int) $this->askWithValidation('selected', "Publication type (1-$offset)", ['required', 'integer', "between:1,$offset"]);
-            $pubType = $pubTypes->{$pubTypes->keys()[$selected - 1]};
-        }
-
-        $mediaFiles = PublicationService::getMediaForPubType($pubType);
-        $fieldData = Collection::create();
-        $this->output->writeln('<bg=magenta;fg=white>Now please enter the field data:</>');
-        foreach ($pubType->fields as $field) {
-            $fieldData->{$field['name']} = $this->captureFieldInput((object) $field, $mediaFiles);
-        }
+        $pubType = $this->getPubTypeSelection($this->getPublicationTypes());
+        $fieldData = $this->collectFieldData($pubType);
 
-        try {
-            $creator = new CreatesNewPublicationFile($pubType, $fieldData, output: $this->output);
-            $creator->create();
-        } catch (InvalidArgumentException $exception) { // FIXME: provide a properly typed exception
-            $msg = $exception->getMessage();
-            // Useful for debugging
-            //$this->output->writeln("xxx " . $exception->getTraceAsString());
-            $this->output->writeln("<bg=red;fg=white>$msg</>");
-            $overwrite = $this->askWithValidation(
-                'overwrite',
-                'Do you wish to overwrite the existing file (y/n)',
-                ['required', 'string', 'in:y,n'],
-                'n'
-            );
-            if (strtolower($overwrite) == 'y') {
-                $creator = new CreatesNewPublicationFile($pubType, $fieldData, true, $this->output);
-                $creator->create();
+        $creator = new CreatesNewPublicationFile($pubType, $fieldData, $this->hasForceOption(), $this->output);
+        if ($creator->hasFileConflict()) {
+            $this->error('Error: A publication already exists with the same canonical field value');
+            if ($this->confirm('Do you wish to overwrite the existing file?')) {
+                $creator->force();
             } else {
                 $this->output->writeln('<bg=magenta;fg=white>Exiting without overwriting existing publication file!</>');
-            }
-        } catch (Exception $exception) {
-            $this->error("Error: {$exception->getMessage()} at {$exception->getFile()}:{$exception->getLine()}");
 
-            return Command::FAILURE;
+                return ValidatingCommand::USER_EXIT;
+            }
         }
 
+        $creator->create();
+
         $this->info('Publication created successfully!');
 
         return Command::SUCCESS;
     }
 
-    protected function captureFieldInput(object $field, Collection $mediaFiles): string|array
+    protected function captureFieldInput(PublicationFieldType $field, Collection $mediaFiles): string|array
     {
-        $rulesPerType = $this->getValidationRulesPerType();
-
         if ($field->type === 'text') {
             $lines = [];
             $this->output->writeln($field->name." (end with a line containing only '<<<')");
@@ -135,7 +101,7 @@ protected function captureFieldInput(object $field, Collection $mediaFiles): str
         }
 
         // Fields which are not of type array, text or image
-        $fieldRules = $rulesPerType->{$field->type};
+        $fieldRules = Collection::create(PublicationFieldType::DEFAULT_RULES)->{$field->type};
         if ($fieldRules->contains('between')) {
             $fieldRules->forget($fieldRules->search('between'));
             if ($field->min && $field->max) {
@@ -156,16 +122,59 @@ protected function captureFieldInput(object $field, Collection $mediaFiles): str
         return $this->askWithValidation($field->name, $field->name, $fieldRules);
     }
 
-    protected function getValidationRulesPerType(): Collection
+    /**
+     * @param  \Rgasch\Collection\Collection<string, \Hyde\Framework\Features\Publications\Models\PublicationType>  $pubTypes
+     * @return \Hyde\Framework\Features\Publications\Models\PublicationType
+     */
+    protected function getPubTypeSelection(Collection $pubTypes): PublicationType
+    {
+        $pubTypeSelection = $this->argument('publicationType') ?? $pubTypes->keys()->get(
+            (int) $this->choice('Which publication type would you like to create a publication item for?',
+                $pubTypes->keys()->toArray()
+            )
+        );
+
+        if ($pubTypes->has($pubTypeSelection)) {
+            $this->line("<info>Creating a new publication of type</info> [<comment>$pubTypeSelection</comment>]");
+
+            return $pubTypes->get($pubTypeSelection);
+        }
+
+        throw new InvalidArgumentException("Unable to locate publication type [$pubTypeSelection]");
+    }
+
+    /**
+     * @param  \Hyde\Framework\Features\Publications\Models\PublicationType  $pubType
+     * @return \Rgasch\Collection\Collection<string, string|array>
+     */
+    protected function collectFieldData(PublicationType $pubType): Collection
+    {
+        $this->output->writeln("\n<bg=magenta;fg=white>Now please enter the field data:</>");
+
+        $mediaFiles = PublicationService::getMediaForPubType($pubType);
+
+        return Collection::make($pubType->fields)->mapWithKeys(function ($field) use ($mediaFiles) {
+            return [$field['name'] => $this->captureFieldInput(PublicationFieldType::fromArray($field), $mediaFiles)];
+        });
+    }
+
+    /**
+     * @return \Rgasch\Collection\Collection<string, PublicationType>
+     *
+     * @throws \InvalidArgumentException
+     */
+    protected function getPublicationTypes(): Collection
+    {
+        $pubTypes = PublicationService::getPublicationTypes();
+        if ($pubTypes->isEmpty()) {
+            throw new InvalidArgumentException('Unable to locate any publication types. Did you create any?');
+        }
+
+        return $pubTypes;
+    }
+
+    protected function hasForceOption(): bool
     {
-        return Collection::create([
-            'string'   => ['required', 'string', 'between'],
-            'boolean'  => ['required', 'boolean'],
-            'integer'  => ['required', 'integer', 'between'],
-            'float'    => ['required', 'numeric', 'between'],
-            'datetime' => ['required', 'datetime', 'between'],
-            'url'      => ['required', 'url'],
-            'text'     => ['required', 'string', 'between'],
-        ]);
+        return (bool) $this->option('force');
     }
 }

packages/framework/src/Console/Commands/MakePublicationTypeCommand.php

@@ -16,6 +16,7 @@
 /**
  * Hyde Command to create a new publication type.
  *
+ * @see \Hyde\Framework\Actions\CreatesNewPublicationType
  * @see \Hyde\Framework\Testing\Feature\Commands\MakePublicationTypeCommandTest
  */
 class MakePublicationTypeCommand extends ValidatingCommand implements CommandHandleInterface
@@ -35,7 +36,7 @@ public function handle(): int
         if (! $title) {
             $title = trim($this->askWithValidation('name', 'Publication type name', ['required', 'string']));
             $dirname = PublicationService::formatNameForStorage($title);
-            if (file_exists($dirname)) {
+            if (file_exists($dirname) && is_dir($dirname) && count(scandir($dirname)) > 2) {
                 throw new InvalidArgumentException("Storage path [$dirname] already exists");
             }
         }

packages/framework/src/Console/Concerns/ValidatingCommand.php

@@ -6,11 +6,13 @@
 
 use function array_keys;
 use function array_values;
+use Exception;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\Str;
 use LaravelZero\Framework\Commands\Command;
 use RuntimeException;
+use function str_ends_with;
 use function str_replace;
 use function ucfirst;
 
@@ -21,20 +23,40 @@
  */
 class ValidatingCommand extends Command
 {
+    public const USER_EXIT = 130;
+
     /** @var int How many times can the validation loop run? Guards against infinite loops. */
     protected final const MAX_RETRIES = 30;
 
+    /**
+     * @return int The exit code.
+     */
+    public function handle(): int
+    {
+        try {
+            return $this->safeHandle();
+        } catch (Exception $exception) {
+            return $this->handleException($exception);
+        }
+    }
+
+    /**
+     * This method can be overridden by child classes to provide automatic exception handling.
+     * Existing code can be converted simply by renaming the handle() method to safeHandle().
+     *
+     * @return int The exit code.
+     */
+    protected function safeHandle(): int
+    {
+        return Command::SUCCESS;
+    }
+
     /**
      * Ask for a CLI input value until we pass validation rules.
      *
-     * @param  string  $name
-     * @param  string  $question
-     * @param  \Illuminate\Contracts\Support\Arrayable|array  $rules
-     * @param  mixed|null  $default
      * @param  int  $retryCount  How many times has the question been asked?
-     * @return mixed
      *
-     * @throws RuntimeException
+     * @throws RuntimeException If the validation fails after MAX_RETRIES attempts.
      */
     public function askWithValidation(
         string $name,
@@ -65,7 +87,25 @@ public function askWithValidation(
             throw new RuntimeException(sprintf("Too many validation errors trying to validate '$name' with rules: [%s]", implode(', ', $rules)));
         }
 
-        return $this->askWithValidation($name, $question, $rules, null, $retryCount);
+        return $this->askWithValidation($name, $question, $rules, $default, $retryCount);
+    }
+
+    /**
+     * Handle an exception that occurred during command execution.
+     *
+     * @param  string|null  $file  The file where the exception occurred. Leave null to auto-detect.
+     * @return int The exit code
+     */
+    public function handleException(Exception $exception, ?string $file = null, ?int $line = null): int
+    {
+        // If the exception was thrown from the same file as a command, then we don't need to show which file it was thrown from.
+        if (str_ends_with($file ?? $exception->getFile(), 'Command.php')) {
+            $this->error("Error: {$exception->getMessage()}");
+        } else {
+            $this->error(sprintf('Error: %s at ', $exception->getMessage()).sprintf('%s:%s', $file ?? $exception->getFile(), $line ?? $exception->getLine()));
+        }
+
+        return Command::FAILURE;
     }
 
     protected function translate($name, string $error): string

packages/framework/src/Framework/Actions/Concerns/CreateAction.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Actions\Concerns;
+
+use function file_exists;
+use Hyde\Framework\Actions\Contracts\CreateActionContract;
+use Hyde\Framework\Concerns\InteractsWithDirectories;
+use Hyde\Framework\Exceptions\FileConflictException;
+use Hyde\Hyde;
+use Illuminate\Support\Str;
+
+/**
+ * @see \Hyde\Framework\Testing\Feature\CreateActionTest
+ *
+ * @internal This class is experimental and is not meant to be used outside the Hyde framework.
+ */
+abstract class CreateAction implements CreateActionContract
+{
+    use InteractsWithDirectories;
+
+    protected string $outputPath;
+    protected bool $force = false;
+
+    abstract protected function handleCreate(): void;
+
+    /** @inheritDoc */
+    public function create(): void
+    {
+        if ($this->hasFileConflict()) {
+            throw new FileConflictException($this->outputPath);
+        }
+
+        $this->handleCreate();
+    }
+
+    /** @inheritDoc */
+    public function force(bool $force = true): static
+    {
+        $this->force = $force;
+
+        return $this;
+    }
+
+    /** @inheritDoc */
+    public function setOutputPath(string $outputPath): static
+    {
+        $this->outputPath = $outputPath;
+
+        return $this;
+    }
+
+    /** @inheritDoc */
+    public function getOutputPath(): string
+    {
+        return $this->outputPath;
+    }
+
+    /** @inheritDoc */
+    public function getAbsoluteOutputPath(): string
+    {
+        return Hyde::path($this->getOutputPath());
+    }
+
+    /** @inheritDoc */
+    public function fileExists(): bool
+    {
+        return file_exists($this->getAbsoluteOutputPath());
+    }
+
+    /** @inheritDoc */
+    public function hasFileConflict(): bool
+    {
+        return $this->fileExists() && ! $this->force;
+    }
+
+    protected function save(string $contents): void
+    {
+        $this->needsParentDirectory($this->getAbsoluteOutputPath());
+        \Safe\file_put_contents($this->getAbsoluteOutputPath(), $contents);
+    }
+
+    protected function formatStringForStorage(string $string): string
+    {
+        return Str::slug($string);
+    }
+}