[6.x] Forms 2: Multi-page forms & SubmitForm action

config/forms.php

@@ -47,6 +47,8 @@
 
     'delete_partial_submissions_after' => 7,
 
+    'garbage_collect_assets' => false,
+
     /*
     |--------------------------------------------------------------------------
     | Exporters

routes/web.php

@@ -27,6 +27,7 @@
 use Statamic\Http\Middleware\AuthGuard;
 use Statamic\Http\Middleware\CP\AuthGuard as CPAuthGuard;
 use Statamic\Http\Middleware\CP\HandleInertiaRequests;
+use Statamic\Http\Middleware\HandleFormPrecognitiveRequests;
 use Statamic\Http\Middleware\RedirectIfTwoFactorSetupIncomplete;
 use Statamic\Http\Middleware\RequireElevatedSession;
 use Statamic\Statamic;
@@ -36,7 +37,7 @@
 
 Route::name('statamic.')->group(function () {
     Route::group(['prefix' => config('statamic.routes.action')], function () {
-        Route::post('forms/{form}', [FormController::class, 'submit'])->middleware([HandlePrecognitiveRequests::class, 'throttle:statamic.forms'])->name('forms.submit');
+        Route::post('forms/{form}', [FormController::class, 'submit'])->middleware([HandleFormPrecognitiveRequests::class, 'throttle:statamic.forms'])->name('forms.submit');
 
         Route::get('protect/password', [PasswordProtectController::class, 'show'])->name('protect.password.show')->middleware([HandleInertiaRequests::class]);
         Route::post('protect/password', [PasswordProtectController::class, 'store'])->name('protect.password.store');

src/Exceptions/SilentFormFailureException.php

@@ -2,7 +2,17 @@
 
 namespace Statamic\Exceptions;
 
+use Statamic\Contracts\Forms\Submission;
+
 class SilentFormFailureException extends \Exception
 {
-    //
+    public function __construct(protected ?Submission $submission = null)
+    {
+        parent::__construct();
+    }
+
+    public function submission(): ?Submission
+    {
+        return $this->submission;
+    }
 }

src/Forms/Fields/FormFields.php

@@ -35,12 +35,13 @@ public function contents(): array
 
     public function pages(): Collection
     {
-        if (isset($this->contents['pages'])) {
-            return collect($this->contents['pages']);
-        }
+        $pages = isset($this->contents['pages'])
+            ? collect($this->contents['pages'])
+            : collect([['sections' => $this->contents['sections'] ?? []]]);
 
-        return collect([
-            ['sections' => $this->contents['sections'] ?? []],
+        return $pages->map(fn (array $page, int $index): array => [
+            ...$page,
+            'id' => $page['id'] ?? ($pages->count() === 1 ? 'main' : 'page_'.($index + 1)),
         ]);
     }
 
@@ -78,8 +79,6 @@ public function toBlueprint(): Blueprint
     {
         $tabs = $this->pages()
             ->mapWithKeys(function (array $page, int $index): array {
-                $id = $page['id'] ?? ($this->pages()->count() === 1 ? 'main' : 'page_'.($index + 1));
-
                 $sections = collect($page['sections'] ?? [])
                     ->map(function (array $section): array {
                         return [
@@ -105,8 +104,8 @@ public function toBlueprint(): Blueprint
                     ->all();
 
                 return [
-                    $id => [
-                        ...$page,
+                    $page['id'] => [
+                        ...Arr::except($page, 'id'),
                         'display' => $page['display'] ?? __('Page :current of :total', ['current' => $index + 1, 'total' => $this->pages()->count()]),
                         'sections' => $sections,
                     ],

src/Forms/Form.php

@@ -218,6 +218,15 @@ private function convertFieldsFromBlueprint(Blueprint $blueprint): array
         return ['sections' => $sections];
     }
 
+    public function hasMultiplePages(): bool
+    {
+        if (! Statamic::formsProInstalled()) {
+            return false;
+        }
+
+        return $this->formFields()->pages()->count() > 1;
+    }
+
     /**
      * Get the blueprint.
      *

src/Forms/JsDrivers/AbstractJsDriver.php

@@ -76,6 +76,18 @@ public function addToRenderableFieldAttributes($field)
         return [];
     }
 
+    /**
+     * Add to renderable page view data.
+     *
+     * @param  \Statamic\Fields\Tab  $page
+     * @param  array  $data
+     * @return array
+     */
+    public function addToRenderablePageData($page, $data)
+    {
+        return [];
+    }
+
     /**
      * Render form html.
      *

src/Forms/JsDrivers/JsDriver.php

@@ -10,6 +10,8 @@ public function addToFormAttributes();
 
     public function addToRenderableFieldData($field, $data);
 
+    // public function addToRenderablePageData($page, array $data): array;
+
     public function addToRenderableFieldAttributes($field);
 
     public function render($html);

src/Forms/Submission.php

@@ -259,6 +259,8 @@ public function finalize()
             // here when submissions aren't stored so developers may continue to
             // listen and modify the submission as needed.
             SubmissionCreated::dispatch($this);
+
+            $this->deleteQuietly();
         }
 
         SubmissionFinalized::dispatch($this);

src/Forms/SubmissionResult.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Statamic\Forms;
+
+use Statamic\Contracts\Forms\Submission;
+
+readonly class SubmissionResult
+{
+    public function __construct(
+        public Submission $submission,
+        public ?string $nextPage = null
+    ) {
+    }
+
+    public function isFinalized(): bool
+    {
+        return $this->submission->status() === 'finalized';
+    }
+}

src/Forms/SubmitForm.php

@@ -0,0 +1,210 @@
+<?php
+
+namespace Statamic\Forms;
+
+use Illuminate\Support\Traits\Localizable;
+use Illuminate\Validation\ValidationException;
+use Statamic\Contracts\Forms\Form;
+use Statamic\Contracts\Forms\Submission;
+use Statamic\Events\FormSubmitted;
+use Statamic\Exceptions\SilentFormFailureException;
+use Statamic\Facades\Asset;
+use Statamic\Facades\Site;
+use Statamic\Rules\AllowedFile;
+use Statamic\Support\Arr;
+
+class SubmitForm
+{
+    use Localizable;
+
+    protected Form $form;
+    protected ?string $page = null;
+    protected ?Submission $submission = null;
+
+    public function form(Form $form): static
+    {
+        $this->form = $form;
+
+        return $this;
+    }
+
+    public function page(string $page): static
+    {
+        $this->page = $page;
+
+        return $this;
+    }
+
+    public function resume(Submission $submission): static
+    {
+        $this->submission = $submission;
+
+        return $this;
+    }
+
+    public function submit(array $data, array $files = []): SubmissionResult
+    {
+        $files = $this->normalizeFiles($files);
+        $values = array_merge($data, $files);
+        $uploadedAssets = [];
+
+        $this->validate($data, $files);
+
+        $this->submission = $this->submission ?? $this->form->makeSubmission()->asPartial()->site($this->site());
+
+        try {
+            if ($this->shouldFinalize()) {
+                throw_if(Arr::get($values, $this->form->honeypot()), new SilentFormFailureException($this->submission));
+            }
+
+            $uploadedAssets = $this->submission->uploadFiles($files);
+
+            $values = array_merge($values, $uploadedAssets);
+
+            $processedValues = $this->form->blueprint()
+                ->fields()
+                ->addValues($values)
+                ->process()
+                ->values()
+                ->when($this->page, fn ($fields) => $fields->only($this->fieldHandles($this->page)));
+
+            $this->submission->merge($processedValues);
+
+            if ($this->shouldFinalize()) {
+                throw_if(FormSubmitted::dispatch($this->submission) === false, new SilentFormFailureException($this->submission));
+            }
+        } catch (ValidationException|SilentFormFailureException $e) {
+            $this->removeUploadedAssets($uploadedAssets);
+
+            throw $e;
+        }
+
+        $this->shouldFinalize() ? $this->submission->finalize() : $this->submission->save();
+
+        // todo: obviously this should depend on logic at some point
+        $pages = $this->form->formFields()->pages();
+        $currentPageIndex = $pages->where('id', $this->page)->keys()->first();
+        $nextPage = $pages->get($currentPageIndex + 1);
+
+        return new SubmissionResult(
+            $this->submission,
+            $nextPage ? $nextPage['id'] : null
+        );
+    }
+
+    /**
+     * Normalize uploaded files to arrays.
+     *
+     * The assets fieldtype expects arrays, even for `max_files: 1`,
+     * but we don't want to force that on the front end.
+     */
+    private function normalizeFiles(array $files): array
+    {
+        $assetFields = $this->form->blueprint()->fields()->all()
+            ->filter(fn ($field) => in_array($field->fieldtype()->handle(), ['assets', 'files']))
+            ->keys();
+
+        foreach ($assetFields as $handle) {
+            if (isset($files[$handle])) {
+                $files[$handle] = Arr::wrap($files[$handle]);
+            }
+        }
+
+        return $files;
+    }
+
+    private function site()
+    {
+        $previousUrl = ($referrer = request()->header('referer'))
+            ? url()->to($referrer)
+            : session()->previousUrl();
+
+        return $previousUrl ? Site::findByUrl($previousUrl) : null;
+    }
+
+    private function shouldFinalize(): bool
+    {
+        if (! $this->form->hasMultiplePages()) {
+            return true;
+        }
+
+        // todo: should take logic into account (the actual last page on the form might not be the user's last page)
+        $pages = $this->form->formFields()->pages();
+
+        return Arr::get($pages->last(), 'id') === $this->page;
+    }
+
+    private function fieldHandles(string $page): array
+    {
+        return $this->form->blueprint()->tabs()
+            ->filter(fn ($tab): bool => $tab->handle() == $page)
+            ->flatMap(fn ($tab): array => $tab->sections()->flatMap(fn ($section) => $section->fields()->items()->pluck('handle'))->all())
+            ->values()
+            ->all();
+    }
+
+    /**
+     * Remove any uploaded assets.
+     *
+     * Triggered by a validation exception or silent failure.
+     */
+    private function removeUploadedAssets(array $assets): void
+    {
+        collect($assets)
+            ->flatten()
+            ->each(function ($id) {
+                if ($asset = Asset::find($id)) {
+                    $asset->delete();
+                }
+            });
+    }
+
+    public function validate(array $data, array $files = [], ?array $only = null): void
+    {
+        $files = $this->normalizeFiles($files);
+        $fields = $this->form->blueprint()->fields()->addValues(array_merge($data, $files));
+
+        $validator = $fields
+            ->validator()
+            ->withRules($this->extraRules($fields))
+            ->validator();
+
+        if (! $only && $this->page) {
+            $only = $this->fieldHandles($this->page);
+        }
+
+        if ($only) {
+            $validator->setRules($this->filterRules($validator->getRulesWithoutPlaceholders(), $only));
+        }
+
+        $this->withLocale($this->site()?->lang(), fn () => $validator->validate());
+    }
+
+    private function extraRules($fields): array
+    {
+        return $fields->all()
+            ->filter(fn ($field): bool => $field->fieldtype()->handle() === 'assets')
+            ->mapWithKeys(fn ($field): array => [$field->handle().'.*' => ['file', new AllowedFile]])
+            ->all();
+    }
+
+    private function filterRules(array $rules, array $only): array
+    {
+        return collect($rules)
+            ->filter(fn ($rule, $attribute): bool => $this->shouldValidate($attribute, $only))
+            ->all();
+    }
+
+    private function shouldValidate(string $attribute, array $only): bool
+    {
+        foreach ($only as $pattern) {
+            $regex = '/^'.str_replace('\*', '[^.]+', preg_quote($pattern, '/')).'$/';
+
+            if (preg_match($regex, $attribute)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}