get ready to implement background job

Author: tobimori

blueprints/pages/form.php

@@ -5,7 +5,7 @@
 use tobimori\DreamForm\DreamForm;
 use tobimori\DreamForm\Support\Htmx;
 
-return fn () => [
+return fn() => [
 	'title' => 'dreamform.form',
 	'image' => [
 		'icon' => 'survey',
@@ -97,6 +97,13 @@
 								'type' => 'toggle',
 								'help' => 'dreamform.form.continueOnError.help',
 								'width' => '1/2'
+							],
+							'runWorkflowInQueue' => [
+								'label' => 'dreamform.form.runWorkflowInQueue.label',
+								'type' => class_exists('tobimori\Queues\Job') ? 'toggle' : 'hidden',
+								'default' => 'true',
+								'help' => 'dreamform.form.runWorkflowInQueue.help',
+								'width' => '1/2'
 							]
 						]
 					],

classes/Actions/AbortAction.php

@@ -10,7 +10,7 @@ class AbortAction extends Action
 	public const TYPE = 'abort';
 
 	/**
-	 * Returns the Blocks fieldset blueprint for the actions' settings
+	 * @inheritDoc
 	 */
 	public static function blueprint(): array
 	{
@@ -44,7 +44,7 @@ public static function blueprint(): array
 	}
 
 	/**
-	 * Run the action
+	 * @inheritDoc
 	 */
 	public function run(): void
 	{
@@ -54,4 +54,12 @@ public function run(): void
 			$this->success();
 		}
 	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function supportsQueues(): bool
+	{
+		return false;
+	}
 }

classes/Actions/Action.php

@@ -22,9 +22,7 @@ abstract class Action extends Performer
 	 * Create a new Action instance.
 	 * @internal
 	 */
-	public function __construct(private Block $block, private SubmissionPage $submission, private bool $force = false)
-	{
-	}
+	public function __construct(private Block $block, private SubmissionPage $submission, private bool $force = false) {}
 
 	/**
 	 * Returns the submission the performer is being run on
@@ -108,6 +106,14 @@ protected function silentCancel(string|null $message = null, array|bool|null $lo
 		);
 	}
 
+	/**
+	 * Whether the action supports background processing via queues
+	 */
+	public function supportsQueues(): bool
+	{
+		return true;
+	}
+
 	/**
 	 * Finish the form submission early
 	 */

classes/Actions/BrevoAction.php

@@ -8,14 +8,21 @@
 use Kirby\Toolkit\Str;
 use Kirby\Toolkit\V;
 use tobimori\DreamForm\DreamForm;
-use tobimori\DreamForm\Models\FormPage;
 
+use function intval;
+use function count;
+
+/**
+ * Action for subscribing a user to a Brevo newsletter list
+ *
+ * @see https://developers.brevo.com/docs/getting-started
+ */
 class BrevoAction extends Action
 {
 	public const TYPE = 'brevo';
 
 	/**
-	 * Returns the Blocks fieldset blueprint for the actions' settings
+	 * @inheritDoc
 	 */
 	public static function blueprint(): array
 	{
@@ -46,7 +53,7 @@ public static function blueprint(): array
 						'list' => [
 							'label' => t('dreamform.actions.brevo.list.label'),
 							'type' => 'select',
-							'options' => A::reduce(static::getLists(), fn ($prev, $list) => A::merge($prev, [
+							'options' => A::reduce(static::getLists(), fn($prev, $list) => A::merge($prev, [
 								"id-{$list['id']}" => $list['name']
 							]), []),
 							'required' => true,
@@ -63,7 +70,7 @@ public static function blueprint(): array
 							'type' => count(static::getTemplates()) > 0 ? 'select' : 'info',
 							'width' => '1/2',
 							'required' => count(static::getTemplates()) > 0,
-							'options' => A::reduce(static::getTemplates(), fn ($prev, $template) => A::merge($prev, [
+							'options' => A::reduce(static::getTemplates(), fn($prev, $template) => A::merge($prev, [
 								"id-{$template['id']}" => $template['name']
 							]), []),
 							'help' => count(static::getTemplates()) > 0
@@ -166,7 +173,7 @@ public function run(): void
 		}
 
 		$listId = intval(Str::replace($list, 'id-', ''));
-		$listEntry = A::find(static::getLists(), fn ($entry) => $entry['id'] === $listId);
+		$listEntry = A::find(static::getLists(), fn($entry) => $entry['id'] === $listId);
 
 		$this->log(
 			[
@@ -188,7 +195,7 @@ protected static function getLists(): array
 	{
 		$response = static::cache(
 			'lists',
-			fn () => static::request('GET', '/contacts/lists')?->json()
+			fn() => static::request('GET', '/contacts/lists')?->json()
 		);
 
 		return $response['lists'] ?? [];
@@ -201,7 +208,7 @@ protected static function getTemplates(): array
 	{
 		$response = static::cache(
 			'templates',
-			fn () => static::request('GET', '/smtp/templates?limit=1000')?->json()
+			fn() => static::request('GET', '/smtp/templates?limit=1000')?->json()
 		);
 
 		return $response['templates'] ?? [];
@@ -215,7 +222,7 @@ protected static function getAttributeFields(): array
 	{
 		$response = static::cache(
 			'attributes',
-			fn () => static::request('GET', '/contacts/attributes')?->json()
+			fn() => static::request('GET', '/contacts/attributes')?->json()
 		);
 
 		$attributes = $response['attributes'] ?? [];
@@ -262,14 +269,14 @@ public static function request(string $method, string $url, array $data = []): R
 	{
 		if ($method !== 'GET') {
 			$params = [
-				'data' => Json::encode(A::filter($data, fn ($value) => $value !== null)),
+				'data' => Json::encode(A::filter($data, fn($value) => $value !== null)),
 				'headers' => [
 					'Content-Type' => 'application/json',
 				]
 			];
 		}
 
-		return Remote::$method('https://api.brevo.com/v3/' . $url, A::merge(
+		return Remote::$method("https://api.brevo.com/v3/{$url}", A::merge(
 			$params ?? [],
 			[
 				'headers' => [
@@ -289,15 +296,15 @@ public static function isAvailable(): bool
 	}
 
 	/**
-	 * Returns the actions' blueprint group
+	 * @inheritDoc
 	 */
 	public static function group(): string
 	{
 		return 'newsletter';
 	}
 
 	/**
-	 * Returns the base log settings for the action
+	 * @inheritDoc
 	 */
 	protected function logSettings(): array|bool
 	{

classes/Actions/ButtondownAction.php

@@ -10,9 +10,13 @@
 use Kirby\Toolkit\V;
 use tobimori\DreamForm\DreamForm;
 
+use function count;
+use function is_string;
+
 /**
- * Action for subscribing a user to a Buttondown newsletter list.
- * Docs: https://api.buttondown.email/v1/docs
+ * Action for subscribing a user to a Buttondown newsletter list
+ *
+ * @see https://docs.buttondown.com/api-introduction
  */
 class ButtondownAction extends Action
 {
@@ -86,7 +90,7 @@ protected static function tagsBlueprint(): array
 				'label' => ' ',
 				'type' => 'multiselect',
 				'width' => '2/3',
-				'options' => A::map(static::tags(), fn ($tag) => [
+				'options' => A::map(static::tags(), fn($tag) => [
 					'text' => $tag['name'],
 					'value' => $tag['id']
 				]),
@@ -158,7 +162,7 @@ public function run(): void
 			'metadata' => static::metadata(),
 			'tags' => static::submissionTags(),
 			'referrer_url' => $this->submission()->referer(),
-		], fn ($value) => $value !== null);
+		], fn($value) => $value !== null);
 
 		$logData = ['template' => ['email' => $email]];
 
@@ -168,13 +172,13 @@ public function run(): void
 			'utm_campaign' => $this->submission()->valueFor('utm_campaign')?->value(),
 			'utm_medium' => $this->submission()->valueFor('utm_medium')?->value(),
 			'utm_source' => $this->submission()->valueFor('utm_source')?->value()
-		], fn ($value) => $value !== null)));
+		], fn($value) => $value !== null)));
 
 		// some error occurred, check for next steps
 		if ($subscribeRequest->code() !== 201) {
 			// update subscriber data if email already exists
 			if (!static::simpleMode() && $subscribeRequest->json()['code'] === 'email_already_exists') {
-				$updateRequest = static::request('PATCH', "/subscribers/{$email}", array_filter($data, fn ($key) => $key !== 'email', ARRAY_FILTER_USE_KEY));
+				$updateRequest = static::request('PATCH', "/subscribers/{$email}", array_filter($data, fn($key) => $key !== 'email', ARRAY_FILTER_USE_KEY));
 
 				// send reminder if subscriber is unactivated
 				if ($updateRequest->json()['subscriber_type'] === 'unactivated') {
@@ -261,15 +265,15 @@ public static function isAvailable(): bool
 	}
 
 	/**
-	 * Returns the actions' blueprint group
+	 * @inheritDoc
 	 */
 	public static function group(): string
 	{
 		return 'newsletter';
 	}
 
 	/**
-	 * Returns the base log settings for the action
+	 * @inheritDoc
 	 */
 	protected function logSettings(): array|bool
 	{

classes/Actions/ConditionalAction.php

@@ -3,12 +3,15 @@
 namespace tobimori\DreamForm\Actions;
 
 /**
- * Action for conditionally running other actions.
+ * Action for conditionally running other actions
  */
 class ConditionalAction extends Action
 {
 	public const TYPE = 'conditional';
 
+	/**
+	 * @inheritDoc
+	 */
 	public static function blueprint(): array
 	{
 		return [
@@ -122,11 +125,24 @@ public function conditionsMet(): bool
 		return true;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public function run(): void
 	{
 		$collection = $this->conditionsMet() ? $this->block()->thatActions() : $this->block()->elseActions();
 		foreach ($this->submission()->createActions($collection->toBlocks()) as $action) {
 			$action->run();
 		}
 	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function supportsQueues(): bool
+	{
+		// for now, let's execute anything inside conditions immediately
+		// TODO: implement queue support for conditional actions
+		return false;
+	}
 }

classes/Actions/DiscordWebhookAction.php

@@ -9,14 +9,14 @@
 use tobimori\DreamForm\DreamForm;
 
 /**
- * Action for sending a message in a discord channel.
+ * Action for sending a message in a discord channel
  */
 class DiscordWebhookAction extends Action
 {
 	public const TYPE = 'discord-webhook';
 
 	/**
-	 * Returns the Blocks fieldset blueprint for the actions' settings
+	 * @inheritDoc
 	 */
 	public static function blueprint(): array
 	{
@@ -82,7 +82,7 @@ protected function content(): string
 	}
 
 	/**
-	 * Run the action
+	 * @inheritDoc
 	 */
 	public function run(): void
 	{
@@ -132,15 +132,15 @@ public function run(): void
 	}
 
 	/**
-	 * Returns the actions' blueprint group
+	 * @inheritDoc
 	 */
 	public static function group(): string
 	{
 		return 'notifications';
 	}
 
 	/**
-	 * Returns the base log settings for the action
+	 * @inheritDoc
 	 */
 	protected function logSettings(): array|bool
 	{