diff --git a/content/collections/pages/php-actions.md b/content/collections/pages/php-actions.md new file mode 100644 index 000000000..108dc1d57 --- /dev/null +++ b/content/collections/pages/php-actions.md @@ -0,0 +1,72 @@ +--- +id: aea5645d-cffa-4029-b04e-58efcd4303e4 +blueprint: page +title: Actions +intro: Actions are classes that perform discrete tasks outside of the HTTP request lifecycle, making them reusable across controllers, console commands, Livewire components, and more. +related_entries: + - bbea4454-efa2-4372-842b-b295376230f7 + - 02261135-24fa-4d2f-9bc5-a7d2f5e6a975 +--- + +## Overview {#overview} + +Actions are classes that perform specific tasks, like submitting a form. + +Since they're not tied to a controller or the request lifecycle, you can use them anywhere: console commands, API endpoints, Livewire components — wherever you need them. + +## Available Actions + +### SubmitForm + +The `SubmitForm` action handles form submission, including file uploads, honeypot validation, event dispatching and sending emails. + +```php +use Statamic\Facades\Form; +use Statamic\Facades\Site; +use Statamic\Forms\SubmitForm; +use Statamic\Exceptions\SilentFormFailureException; +use Illuminate\Validation\ValidationException; + +$form = Form::find('contact'); + +try { + $submission = app(SubmitForm::class)->submit( + form: $form, + data: ['name' => 'John', 'email' => 'john@example.com'], + files: [], // Optional + site: Site::current(), // Optional + ); +} catch (ValidationException $e) { + return back()->withErrors($e->errors()); +} catch (SilentFormFailureException $e) { + // Honeypot triggered or event listener rejected + // $e->submission() contains the submission data + + return back()->with('success', 'Form submitted successfully!'); +} + +return back()->with('success', 'Form submitted successfully!'); +``` + +#### Validation + +The `->submit()` method validates inputs automatically before saving. If you'd prefer to handle validation yourself, you may call the `->validator()` method which returns a Laravel `Validator` instance: + +```php +app(SubmitForm::class)->validator($form, $data); +``` + +#### Exceptions + +The action may throw a `SilentFormFailureException` when the honeypot is triggered or a `FormSubmitted` event listener returns `false`. This exception contains the submission via `$e->submission()`. + +When handling this exception, you should return a fake success response to avoid tipping off bots. + +#### Arguments + +| Argument | Type | Description | +|----------|------|-------------| +| `form` | `Form` | The form to submit to. | +| `data` | `array` | The submission data. | +| `files` | `array` | Uploaded files, keyed by field handle. Defaults to `[]`. | +| `site` | `Site` | The site context, used for email localization. Defaults to `Site::default()`. | diff --git a/content/collections/resource_apis/form-submission-repository.md b/content/collections/resource_apis/form-submission-repository.md index 44f34e782..369e8eae0 100644 --- a/content/collections/resource_apis/form-submission-repository.md +++ b/content/collections/resource_apis/form-submission-repository.md @@ -7,6 +7,7 @@ related_entries: - fdb45b84-3568-437d-84f7-e3c93b6da3e6 - e4f4f91e-a442-4e15-9e16-3b9880a25522 - bbea4454-efa2-4372-842b-b295376230f7 + - aea5645d-cffa-4029-b04e-58efcd4303e4 --- To work with the Form Submissions Repository, use the following Facade: @@ -82,3 +83,5 @@ Finally, save it. It'll return a boolean for whether it succeeded. ```php $submission->save(); // true or false ``` + +Form submissions may also be created using the [`SubmitForm` action](/backend-apis/php-actions#submitform), which handles file uploads, honeypot validation, event dispatching and sending emails. diff --git a/content/trees/collections/pages.yaml b/content/trees/collections/pages.yaml index 7515a4f2b..dfbc94e7c 100644 --- a/content/trees/collections/pages.yaml +++ b/content/trees/collections/pages.yaml @@ -305,6 +305,8 @@ tree: entry: 0267eb5a-f54b-4e3f-bef0-1f16762720b1 - entry: 6843f6e9-ac62-4128-8d50-887560f201ca + - + entry: aea5645d-cffa-4029-b04e-58efcd4303e4 - entry: 290e9a74-7c6b-4fd0-a90a-23f7ac38d0c5 -