### Install PHP Dependencies with Composer

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

Installs all required PHP dependencies, including Kirby 4, DreamForm, and other utility plugins like DotEnv and Ray, using Composer. This command fetches and sets up all necessary packages for the project.

```bash
composer install
```

--------------------------------

### Start PHP Development Server

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

Initiates the PHP development server, making the DreamForm site accessible locally, typically at `http://localhost:8000`. This allows for local testing and development.

```bash
composer start
```

--------------------------------

### Clone DreamForm Plainkit Repository

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

Clones the `dreamform-plainkit` repository from GitHub into a new directory named `df-plainkit` and then navigates into that directory, preparing the environment for further setup.

```bash
git clone https://github.com/tobimori/dreamform-plainkit df-plainkit && cd df-plainkit
```

--------------------------------

### Configure Manual DreamForm Installation with YAML

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/0_installation.md

For manual installation, create a forms.txt (or forms.en.txt) file in your content/forms directory and add this YAML content to define the UUID for the forms page.

```yaml
Uuid: forms
```

--------------------------------

### Install Kirby DreamForm via Composer

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/0_installation.md

Use Composer, the recommended method, to install the Kirby DreamForm plugin by running this command in your terminal.

```bash
composer require tobimori/kirby-dreamform
```

--------------------------------

### Example PHP Configuration for Kirby DreamForm

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/2_configuration.md

Demonstrates how to configure Kirby DreamForm settings within the `site/config/config.php` file. This example sets a secret from an environment variable, changes the submission mode to HTMX, disables debug, customizes layouts, and defines available guards.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'secret' => fn () => env('DREAMFORM_SECRET'),
    'mode' => 'htmx',
    'debug' => false,
    'layouts' => ['1/1', '1/2, 1/2', '1/3, 1/3, 1/3'],
    'guards' => [
      'available' => ['csrf', 'honeypot', 'turnstile']
    ]
  ]
];
```

--------------------------------

### Configure Kirby DreamForm for Headless CMS Setup

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/3_advanced-configuration.md

Set up Kirby DreamForm to work seamlessly in a headless CMS environment where the site's URL is configured as '/'. DreamForm automatically uses the `HTTP_HOST` server variable as a fallback for referer validation, ensuring secure form submissions even when `$site->host()` returns empty, which is common in headless setups.

```php
// site/config/config.php
return [
  'url' => '/', // Headless setup
  'tobimori.dreamform' => [
    // DreamForm will automatically use HTTP_HOST for referer validation
  ]
];
```

--------------------------------

### Example HTML structure of a DreamForm form

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/2_styling.md

This HTML snippet provides an example of the default structural output of a DreamForm form. It illustrates the nesting of elements like form, error, row, column, field, label, input, textarea, select, and button, showing how different form elements are organized within the DreamForm's rendering.

```html
<form>
	<error data-error="true">
	<row>
		<column style="grid: half;">
			<field data-has-error>
				<label>
				<input>
				<error data-error="key">
			</field>
			<field>
				<label>
				<textarea>
				<error data-error="key">
			</field>
		</column>
		<column style="grid: half;">
			<field>
				<label>
				<select>
				<error data-error="key">
			</field>
			<field>
				<row>
					<input type="radio">
					<label>
				</row>
				<row>
					<input type="radio">
					<label>
				</row>
				<row>
					<input type="radio">
					<label>
				</row>
				<error data-error="key">
			</field>
		</column>
	</row>
	<row>
		<column style="grid: full;">
			<field>
				<button>
			</field>
		</column>
	</row>
</form>
```

--------------------------------

### Add DreamForm Entry to Kirby Panel Sidebar Menu

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/0_installation.md

Integrate the DreamForm 'forms' entry into the Kirby panel sidebar menu by modifying your site/config/config.php file. Utilize the provided Menu helper class for easy configuration.

```php
// site/config/config.php

use tobimori\DreamForm\Support\Menu;

return [
  // Custom menu to show forms in the panel sidebar
  'panel.menu' => fn () => [
    'site' => Menu::site(),
    'forms' => Menu::forms(),
    'users',
    'system'
    // [...]
  ]
];
```

--------------------------------

### Kirby Page Blueprint for Form Selection

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

This YAML blueprint, located at `/site/blueprints/pages/default.yml`, defines the structure for a default Kirby page. It includes a `dreamform/fields/form` panel field, allowing content editors to select a specific form, which is then rendered by the corresponding PHP template.

```yaml
title: Default Page

columns:
  main:
    width: 2/3
    sections:
      fields:
        type: fields
        fields:
          text:
            toolbar:
              inline: false
            type: writer
            inline: true
          form: dreamform/fields/form
  sidebar:
    width: 1/3
    sections:
      pages:
        type: pages
        template: default
      files:
        type: files
```

--------------------------------

### Generate Random Encryption Secret using OpenSSL

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/0_installation.md

Generate a strong, random 32-byte base64 encoded secret using the OpenSSL command-line tool. This secret can be used for DreamForm's encryption.

```bash
openssl rand -base64 32
```

--------------------------------

### Kirby Configuration for Enabling DreamForm Guards

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This configuration snippet for `site/config/config.php` shows how to enable specific DreamForm guards, including the custom 'calc' guard. By adding 'calc' to the `tobimori.dreamform.guards.available` array, the guard becomes active and usable within the Kirby DreamForm setup.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform.guards' => [
    'available' => ['calc', 'csrf', 'honeypot'],
  ]
];
```

--------------------------------

### Configure Akismet API Key in Kirby Dreamform

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/1_akismet.md

This snippet shows how to add your Akismet API key to the Kirby Dreamform configuration. It's recommended to load the key from an environment variable for security, as demonstrated in the example.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['akismet', /* other guards here */ ],
      'akismet' => [
        'apiKey' => fn () => env('AKISMET_API_KEY')
      ]
    ],
  ],
];
```

--------------------------------

### PHP Template for DreamForm Rendering

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

This PHP snippet, part of `site/templates/default.php`, renders a selected DreamForm instance. It utilizes the `dreamform/form` snippet and applies extensive Tailwind CSS classes to various form elements (rows, fields, labels, inputs, buttons, errors, radio, checkbox, file inputs) for consistent styling.

```php
<?php
    /* Render the form selected in the page */
    snippet('dreamform/form', [
      'form' => $page->form()->toPage(),
      'attr' => [
        'row' => ['class' => 'gap-4 mb-4'],
        'field' => ['class' => 'group flex flex-col items-start mb-4 last:mb-0'],
        'label' => ['class' => 'text-sm font-medium text-slate-600 mb-1'],
        'input' => ['class' => 'peer group-data-[has-error]:placeholder-shown:mb-2 shadow-sm group-data-[has-error]:placeholder-shown:border-red-500 w-full border border-gray-200 rounded p-2'],
        'button' => ['class' => 'ml-auto bg-indigo-600 text-white py-2 px-4 rounded shadow-sm hover:bg-indigo-800 transition-colors duration-200'],
        'error' => ['class' => 'peer-[:not(:placeholder-shown)]:hidden text-red-500 text-sm'],
        'radio' => [
          'label' => ['class' => 'text-sm font-medium text-slate-600 mb-2'],
          'input' => ['class' => 'w-4 rounded-full mr-2 shadow-sm border border-gray-200 '],
          'error' => ['class' => 'group-has-[:checked]:hidden text-red-500 text-sm'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        ],
        'checkbox' =>  [
          'label' => ['class' => 'text-sm font-medium text-slate-600 mb-2'],
          'input' => ['class' => 'w-4 mr-2 shadow-sm border border-gray-200 rounded'],
          'error' => ['class' => 'group-has-[:checked]:hidden text-red-500 text-sm'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        ],
        'file' => [
          'input' => ['class' => 'mt-1 w-full border border-gray-200 group-data-[has-error]:mb-2 group-data-[has-error]:border-red-500 text-gray-600 shadow-sm rounded file:cursor-pointer file:transition-colors file:bg-gray-100 file:border-0 file:mr-3 file:py-2 file:px-4 file:hover:bg-gray-200'],
          'row' => ['class' => 'flex items-center mb-1 text-sm']
        ]
      }
    ]); ?>
```

--------------------------------

### PHP `$_FILES` Array Structure for Uploads

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/5_hooks.md

An example of the array structure for the `$file` parameter passed to the `dreamform.upload:before` hook, mirroring the content received from the PHP `$_FILES` superglobal.

```php
[
  "name" => "MyFile.jpg",
  "type" => "image/jpeg",
  "tmp_name" => "/tmp/php/php6hst32",
  "error" => UPLOAD_ERR_OK,
  "size" => 98174
]
```

--------------------------------

### Configure DreamForm Encryption Secret in Kirby PHP Config

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/0_installation.md

Set up an encryption secret in your site/config/config.php file for HTMX or API submission modes. It's recommended to load this secret from an environment variable using a plugin like kirby-dotenv.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    // encryption secret for htmx attributes
    'secret' => fn () => env('DREAMFORM_SECRET')
  ]
];
```

--------------------------------

### Configure DreamForm Permissions for Editor Role (YAML)

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/0_demo.md

This YAML snippet defines the permissions for the 'Editor' user role within the Kirby CMS. It specifically restricts editors from creating or updating forms by setting a global 'false' permission for the 'tobimori.dreamform' plugin, while explicitly granting them access to view existing forms and submissions.

```YAML
title: Editor
permissions:
  tobimori.dreamform:
    "*": false
    accessForms: true
    accessSubmissions: true
```

--------------------------------

### Disable CSRF Guard in Kirby DreamForm Plugin (PHP)

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/2_csrf.md

This PHP configuration snippet demonstrates how to disable the CSRF guard in the Kirby DreamForm plugin. By setting the 'available' guards to ['honeypot'] within the 'tobimori.dreamform' configuration array in 'site/config/config.php', the CSRF protection is removed, allowing the page to be cached. This is useful for sessionless setups but requires careful consideration of security implications.

```PHP
// site/config/config.php

return [
  // Settings for the DreamForm plugin
  'tobimori.dreamform' => [
    'guards' => [
      // disable csrf since we want to be sessionless
      // so that the page can be cached
      'available' => ['honeypot']
    ]
  ]
];
```

--------------------------------

### Create a Basic Kirby Plugin for DreamForm Action

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/8_custom.md

This snippet demonstrates how to set up the foundational `index.php` file for a Kirby plugin, which will host the custom DreamForm action. It initializes the plugin using `Kirby::plugin()` and prepares the environment for action class definition.

```PHP
// site/plugins/discord-action/index.php

use Kirby\Cms\App as Kirby;

Kirby::plugin('tobimori/discord-action', []);
```

--------------------------------

### DreamForm Configuration Options Reference

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/2_configuration.md

Detailed reference for all available configuration options in Kirby DreamForm, including their default values, accepted types, and descriptions. This table covers both required and optional settings for customizing form behavior.

```APIDOC
Option: tobimori.dreamform.secret
  Default: null
  Accepts: string|callable
  Description: Encryption secret for published values (required for HTMX and API modes)

Option: tobimori.dreamform.mode
  Default: 'prg'
  Accepts: 'prg'|'api'|'htmx'
  Description: Set the submission mode for all form submissions

Option: tobimori.dreamform.multiStep
  Default: true
  Accepts: boolean
  Description: Enable or disable multi-step forms

Option: tobimori.dreamform.storeSubmissions
  Default: true
  Accepts: boolean
  Description: Whether to store submissions as pages in Kirby

Option: tobimori.dreamform.debug
  Default: fn () => option('debug')
  Accepts: boolean|callable
  Description: If enabled, sensitive errors are shown on form submission

Option: tobimori.dreamform.layouts
  Default: ['1/1', '1/2, 1/2']
  Accepts: array
  Description: Enabled layouts for the form builder

Option: tobimori.dreamform.page
  Default: page://forms
  Accepts: string
  Description: The page where all forms are stored

Option: tobimori.dreamform.integrations.gravatar
  Default: true
  Accepts: boolean
  Description: If enabled, submissions with email fields fetch an avatar from Gravatar to show in the panel

Option: tobimori.dreamform.refererPageResolver
  Default: callable
  Accepts: callable
  Description: Custom callback to resolve pages with custom URLs
```

--------------------------------

### Kirby Dreamform Actions Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/0_what-are-actions.md

Documentation for the configuration options related to actions in Kirby Dreamform, detailing their default values, accepted types, and descriptions.

```APIDOC
Option: tobimori.dreamform.actions.available
  Default: true
  Accepts: boolean|array
  Description: Available actions, true enables all actions
```

--------------------------------

### DreamForm Rate Limit Guard Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/6_ratelimit.md

This section details the available configuration options for the `ratelimit` guard within DreamForm, including their default values, accepted types, and descriptions. These options are set under `tobimori.dreamform.guards.ratelimit` in the `config.php` file.

```APIDOC
tobimori.dreamform.guards.ratelimit.limit:
  Description: Limit of requests per interval
  Type: int
  Default: 10

tobimori.dreamform.guards.ratelimit.interval:
  Description: Interval in minutes
  Type: int
  Default: 3
```

--------------------------------

### DreamForm Honeypot Guard Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/3_honeypot.md

API documentation for the configuration options available for the DreamForm Honeypot guard, detailing the 'availableFields' setting.

```APIDOC
Option: tobimori.dreamform.guards.honeypot.availableFields
  Default: [...]
  Accepts: array
  Description: Available field keys for the honeypot field
```

--------------------------------

### DreamForm Action Class Methods Reference

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/8_custom.md

This section provides a reference for the core methods available when creating a custom DreamForm action class. It details the purpose, return types, and parameters for `blueprint()`, `type()`, `group()`, `run()`, and `isAvailable()` methods, which define the action's behavior and panel integration.

```APIDOC
Action Class Methods:
- public static function blueprint(): array
  Returns an array with the blueprint definition used in the panel
- public static function type(): string
  Returns the type of the field used internally, also used for accessing the snippet
- public static function group(): string
  Customize the group of the action in the panel
- public function run(): void
  The logic that's executed when the action is running
- public static function isAvailable(FormPage|null $form = null): bool
  Whether the action should be available, used for checking global configuration details, like API keys
```

--------------------------------

### Initialize Kirby Plugin for Custom Guard

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This snippet demonstrates how to initialize a basic Kirby plugin for a custom DreamForm guard. It defines the plugin's namespace and prepares it for autoloading.

```PHP
// site/plugins/calc-guard/index.php

use Kirby\Cms\App as Kirby;

Kirby.plugin('tobimori/calc-guard', []);
```

--------------------------------

### PHP Code for Registering DreamForm Guard and Snippet

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This PHP code demonstrates how to register a custom `CalcGuard` class with the DreamForm plugin and how to register its associated snippet with Kirby. It ensures that the `CalcGuard.php` file is loaded and that the 'dreamform/guards/calc' snippet path points to the correct file.

```PHP
// [...]

@include_once __DIR__ . '/CalcGuard.php'; // Tell PHP to load our class

DreamForm::register(CalcGuard::class); // Register the class with DreamForm

Kirby::plugin('tobimori/calc-guard', [
  'snippets' => [
    'dreamform/guards/calc' => __DIR__ . '/snippets/calc.php' // Register the Guard snippet with Kirby
  ]
]);
```

--------------------------------

### Configure Available Actions in Kirby Dreamform

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/0_what-are-actions.md

This PHP snippet demonstrates how to specify or limit the actions available within the Kirby Dreamform plugin by modifying the `config.php` file. This allows developers to control which actions can be used in the form builder.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'actions' => [
      'available' => ['abort', 'conditional', 'redirect', 'webhook', /* other actions here */ ],
    ],
  ],
];
```

--------------------------------

### DreamForm Turnstile Configuration Options Reference

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/4_turnstile.md

Detailed documentation for the configuration options available for the Cloudflare Turnstile integration within the DreamForm plugin. Each option includes its default value, accepted data types, and a description of its purpose.

```APIDOC
Option: tobimori.dreamform.guards.turnstile.siteKey
  Default: null
  Accepts: string|callback
  Description: The Turnstile sitekey is used to invoke Turnstile on your site

Option: tobimori.dreamform.guards.turnstile.secretKey
  Default: null
  Accepts: string|callable
  Description: The Turnstile secret key allows communication between DreamForm and Cloudflare to response

Option: tobimori.dreamform.guards.turnstile.injectScript
  Default: true
  Accepts: boolean
  Description: Whether the client-side script should be injected implicitly by the plugin

Option: tobimori.dreamform.guards.turnstile.theme
  Default: 'auto'
  Accepts: 'auto'|'light'|'dark'
  Description: Theme to render the captcha with
```

--------------------------------

### Akismet Guard Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/1_akismet.md

This section details the available configuration options for the Akismet guard in Kirby Dreamform, including their default values, accepted data types, and a brief description for each setting.

```APIDOC
tobimori.dreamform.guards.akismet.apiKey:
  Default: null
  Accepts: string|callback
  Description: The Akismet API key from your account page
tobimori.dreamform.guards.akismet.fields.comment_author:
  Default: [...]
  Accepts: array
  Description: Fields to use for the author name param
tobimori.dreamform.guards.akismet.fields.comment_author_email:
  Default: [...]
  Accepts: array
  Description: Fields to use for the email param
tobimori.dreamform.guards.akismet.fields.comment_author_url:
  Default: [...]
  Accepts: array
  Description: Fields to use for the url/website param
tobimori.dreamform.guards.akismet.fields.comment_content:
  Default: [...]
  Accepts: array
  Description: Fields to use for the content param
```

--------------------------------

### Configure IP-based Rate Limiting for DreamForm in PHP

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/6_ratelimit.md

This PHP configuration snippet demonstrates how to enable and customize the IP-based rate limit guard for DreamForm in `site/config/config.php`. It allows setting the maximum `limit` of requests and the `interval` in minutes, with defaults of 10 requests per 3 minutes.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['ratelimit', /* other guards here */ ],
      'ratelimit' => [
        'limit' => 10,
        'interval' => 3
      ]
    ],
  ],
];
```

--------------------------------

### Configure Metadata Collection for Akismet in Kirby Dreamform

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/1_akismet.md

Akismet requires the sender's IP address and user agent for effective spam detection. This configuration snippet demonstrates how to enable the collection of this essential metadata within Kirby Dreamform.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [ /* [...] */ ],
    'metadata' => [
        'collect' => [
            'ip', 
            'userAgent'
        ]
    ],
  ],
];
```

--------------------------------

### Configure Available Guards in PHP

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/0_what-are-guards.md

This PHP configuration snippet demonstrates how to enable or disable guards for Dreamform by listing their types in the 'tobimori.dreamform.guards.available' array within your 'config.php' file. This allows site developers to control which security checks are active.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['csrf', 'honeypot', 'turnstile', 'ratelimit', /* other guards here */ ],
    ],
  ],
];
```

--------------------------------

### Complete Custom CalcGuard Class Implementation

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This comprehensive PHP snippet presents the full `CalcGuard` class, combining the question generation, validation logic, and required static methods. It demonstrates a complete custom guard for DreamForm.

```PHP
<?php

use Kirby\Cms\App;
use tobimori\DreamForm\Guards\Guard;
use tobimori\DreamForm\Models\SubmissionPage;

class CalcGuard extends Guard
{
  public function run()
  {
    $result = App::instance()->session()->pull('calc-guard-result');
    $value = SubmissionPage::valueFromBody('calc');

    if ($result !== (int) $value) {
      $this->cancel('Sorry, think again! 🤔');
    }
  }

  public static function hasSnippet(): bool
  {
    return true;
  }

  public static function type(): string
  {
    return 'calc';
  }

  public function generate(): string
  {
    [$a, $b] = [rand(0, 9), rand(0, 9)];
    App::instance()->session()->set('calc-guard-result', $a + $b);

    return "What is {$a} + {$b}?";
  }
}
```

--------------------------------

### Configure Honeypot Guard in PHP

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/3_honeypot.md

This PHP configuration snippet demonstrates how to disable the Honeypot guard globally and customize the list of available field keys that the Honeypot guard monitors for spam detection within the 'tobimori.dreamform' plugin settings.

```php
// site/config/config.php

return [
  // Settings for the DreamForm plugin
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['honeypot'],
      'honeypot.availableFields' => ['website', 'email', 'name', 'url', 'birthdate'] 
    ]
  ]
];
```

--------------------------------

### Buttondown DreamForm Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/7_buttondown.md

Configuration options available for the Buttondown integration in Kirby DreamForm, including API key and simple mode settings.

```APIDOC
Option: tobimori.dreamform.fields.buttondown.apiKey
  Default: null
  Accepts: string|callback
  Description: The API key to communicate with Buttondown

Option: tobimori.dreamform.fields.buttondown.simpleMode
  Default: false
  Accepts: boolean
  Description: Simple mode works with the free tier, but does not support updating user data or tags
```

--------------------------------

### DreamForm hCaptcha Guard Configuration Options

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/5_hcaptcha.md

API documentation for the available configuration options for the hCaptcha guard in DreamForm, including site key, secret key, script injection, theme, size, and custom theme settings.

```APIDOC
tobimori.dreamform.guards.hcaptcha.siteKey:
  Default: null
  Accepts: string|callback
  Description: The hCaptcha sitekey is used to render hCaptcha on your site
tobimori.dreamform.guards.hcaptcha.secretKey:
  Default: null
  Accepts: string|callable
  Description: The hCaptcha secret key allows communication between DreamForm and hCaptcha to verify responses
tobimori.dreamform.guards.hcaptcha.injectScript:
  Default: true
  Accepts: boolean
  Description: Whether the client-side script should be injected implicitly by the plugin
tobimori.dreamform.guards.hcaptcha.theme:
  Default: 'auto'
  Accepts: 'auto'|'light'|'dark'|'custom'|array
  Description: Theme to render the captcha with. Can be a string for built-in themes or an array for custom themes
tobimori.dreamform.guards.hcaptcha.size:
  Default: 'normal'
  Accepts: 'normal'|'compact'
  Description: Set the size of the widget
tobimori.dreamform.guards.hcaptcha.customTheme:
  Default: null
  Accepts: array
  Description: Custom theme configuration object (Pro/Enterprise only)
```

--------------------------------

### Enable Partial Submissions in Kirby Dreamform Configuration

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/0_general/4_precognition.md

This PHP configuration snippet enables the 'partialSubmissions' feature within the 'tobimori.dreamform' plugin. When enabled, it automatically saves each field's value as the user fills it out, which helps track progress for abandoned forms and prevents data loss from failed submissions.

```PHP
// site/config/config.php

return [
  	// ...
    'tobimori.dreamform' => [
      'partialSubmissions' => true,
    ],
];
```

--------------------------------

### Define Kirby Plugin for DreamForm Custom Field

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/2_fields/12_custom.md

This PHP snippet shows how to define a basic Kirby plugin. It initializes the plugin `tobimori/linkedin-field` within the `site/plugins/linkedin-field/index.php` file, which is necessary for Kirby to autoload the custom field class.

```php
// site/plugins/linkedin-field/index.php

use Kirby\Cms\App as Kirby;

Kirby::plugin('tobimori/linkedin-field', []);
```

--------------------------------

### Conditional Action Configuration and Logic

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/2_conditional.md

Details the available condition types for the 'conditional' action and its operational logic within the system. All specified conditions must be met for nested actions to execute.

```APIDOC
Conditional Action:
  Description: Allows checking values of certain fields to execute nested actions.
  Supported Condition Types:
    - equals
    - not equals
    - contains
    - not contains
    - starts with
    - ends with
  Execution Logic: All conditions specified in the "Conditions" field must match for nested actions to be executed.
  Limitation: Not possible to nest conditional actions inside conditional actions.
```

--------------------------------

### Output Kirby Dreamform in PHP Snippet

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/1_using-forms.md

This PHP snippet demonstrates how to render a Kirby Dreamform within a block snippet. It calls the `dreamform/form` plugin snippet, passing the selected form's page object as an argument to display the form on the frontend.

```php
// site/snippets/blocks/form.php

<?php snippet('dreamform/form', ['form' => $block->form()->toPage()]); ?>
```

--------------------------------

### Define a Custom DreamForm Action Class

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/8_custom.md

This PHP code defines the `DiscordAction` class, extending `tobimori\DreamForm\Actions\Action`. It implements the `blueprint()` method to define the action's panel fields (e.g., webhookUrl), the `run()` method for its core logic, and the `type()` method to specify its internal identifier.

```PHP
<?php

use tobimori\DreamForm\Actions\Action;

class DiscordAction extends Action
{
  public static function blueprint(): array
  {
    return [
      'title' => 'Discord Message',
      'preview' => 'fields',
      'wysiwyg' => true,
      'icon' => 'discord',
      'fields' => [
        'webhookUrl' => [
          'label' => 'Webhook URL',
          'type' => 'url',
          'placeholder' => 'https://discord.com/api/webhooks/...',
          'width' => '1/3',
          'required' => true
        ]
      ]
    ];
  }

  public function run(): void
  {
    // send the request
  }

  public static function type(): string
  {
    return 'discord';
  }
}
```

--------------------------------

### Define Form Field in Kirby Blueprint (YAML)

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/1_using-forms.md

This YAML snippet defines a 'form' field within a Kirby CMS blueprint, allowing users to select a form. It extends the `dreamform/fields/form` field type, making it suitable for blocks, pages, files, or user blueprints.

```yaml
# site/blueprints/blocks/form.yml

title: Form Block
icon: survey
preview: fields
wysiwyg: true

fields:
  form:
    label: Select your form
    extends: dreamform/fields/form
```

--------------------------------

### Configure DreamForm Turnstile Guard in PHP

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/4_turnstile.md

This PHP snippet demonstrates how to add Cloudflare Turnstile as an available guard in the DreamForm configuration, specifying the site key and secret key. It highlights the best practice of loading these sensitive keys from environment variables to avoid committing them to the repository.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['turnstile', /* other guards here */ ],
      'turnstile' => [
        'siteKey' => fn () => env('TURNSTILE_SITE_KEY'),
        'secretKey' =>  fn () => env('TURNSTILE_SECRET_KEY')
      ]
    ],
  ],
];
```

--------------------------------

### Configure hCaptcha Guard in DreamForm

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/5_hcaptcha.md

This PHP configuration snippet shows how to enable the hCaptcha guard in DreamForm's `config.php` and set the site key and secret key, ideally loaded from environment variables for security.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'guards' => [
      'available' => ['hcaptcha', /* other guards here */ ],
      'hcaptcha' => [
        'siteKey' => fn () => env('HCAPTCHA_SITE_KEY'),
        'secretKey' => fn () => env('HCAPTCHA_SECRET_KEY')
      ]
    ],
  ],
];
```

--------------------------------

### Implement Custom LinkedInField Class for DreamForm

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/2_fields/12_custom.md

This PHP code defines the `LinkedInField` class, extending `tobimori\DreamForm\Fields\Field`. It implements the `blueprint()` method to define the field's appearance and configuration in the Kirby panel, including tabs for field properties and validation. It also defines the `type()` method, returning 'linkedin' for internal identification.

```php
<?php

use tobimori\DreamForm\Fields\Field;

class LinkedInField extends Field
{
  public static function blueprint(): array
  {
    return [
      'title' => 'LinkedIn',
      'label' => '{{ label }}',
      'preview' => 'text-field',
      'wysiwyg' => true,
      'icon' => 'linkedin',
      'tabs' => [
        'field' => [
          'label' => t('dreamform.field'),
          'fields' => [
            'key' => 'dreamform/fields/key',
            'label' => 'dreamform/fields/label',
            'placeholder' => 'dreamform/fields/placeholder'
          ]
        ],
        'validation' => [
          'label' => t('dreamform.validation'),
          'fields' => [
            'required' => 'dreamform/fields/required',
            'errorMessage' => 'dreamform/fields/error-message'
          ]
        ]
      ]
    ];
  }

  public static function type(): string
  {
    return 'linkedin';
  }
}
```

--------------------------------

### Configure Buttondown API Key in Kirby DreamForm

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/7_buttondown.md

This PHP snippet shows how to add the Buttondown API key to your Kirby DreamForm configuration. It's recommended to load the key from an environment variable for security.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'actions' => [
      'buttondown.apiKey' => fn () => env('BUTTONDOWN_API_KEY')
    ]
  ]
];
```

--------------------------------

### Implement Calc Guard Validation Logic

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This PHP `run()` method retrieves the stored math problem result from the session and the user's submitted answer. It then validates if the answer is correct, canceling the form submission with an error message if it's not.

```PHP
public function run()
{
  $result = App::instance()->session()->pull('calc-guard-result'); // Get result from session, and remove it
  $value = SubmissionPage::valueFromBody('calc'); // Get Field value

  // Check if the value doesn't exists or is not equal to the result
  if (empty($value) || $result !== (int) $value) {
    $this->cancel('Sorry, think again! 🤔');
  }
}
```

--------------------------------

### Send Discord Webhook with PHP using Kirby Remote

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/8_custom.md

This PHP code defines a `DiscordAction` class that extends `Action`. Its `run` method sends a POST request to a Discord webhook URL using Kirby's `Remote::post` method. It constructs a JSON payload from submission values, mapping them to a human-readable string, and handles potential errors by calling `$this->cancel()` if the request fails.

```php
<?php

class DiscordAction extends Action
{
  [...]

  public function run(): void
  {
    try {
      $request = Remote::post($this->block()->webhookUrl()->value(), [
        'headers' => [
          'Content-Type' => 'application/json'
        ],
        'data' => Json::encode([
          'content' => A::join(A::map($this->submission()->values()->toArray(), function ($value, $key) {
            return "**{$key}**: {$value}";
          }), "\n"),
          'embeds' => null,
          'attachments' => []
        ])
      ]);

      if ($request->code() > 299) {
        $this->cancel();
      }
    } catch (Throwable $e) {
      $this->cancel($e->getMessage());
    }
  }
}
```

--------------------------------

### Define Basic DreamForm Guard Class

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This PHP snippet outlines the fundamental structure of a custom DreamForm guard class. It includes the `run()` method for guard logic, `hasSnippet()` to indicate UI presence, and `type()` to define the guard's identifier.

```PHP
// site/plugins/calc-guard/CalcGuard.php

use tobimori\DreamForm\Guards\Guard;

class CalcGuard extends Guard
{
  public function run()
  {
    // $this->cancel('error message!');
  }

  public static function hasSnippet(): bool
  {
    return true;
  }

  public static function type(): string
  {
    return 'calc';
  }
}
```

--------------------------------

### Configure Custom Referer Page Resolution in Kirby DreamForm

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/1_setup/3_advanced-configuration.md

Implement a custom resolver function to correctly identify referer pages when your Kirby site uses custom URL schemes, virtual pages, or custom routes. This function helps DreamForm find the correct page for email actions and post-submission redirects, receiving the referer path and expecting a `\Kirby\Cms\Page` object or `null` in return.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'refererPageResolver' => function (string $referer): ?\Kirby\Cms\Page {
      // Example: Handle custom blog URLs like /blog/my-title/some-uid
      if (preg_match('#^/blog/([^/]+)/([^/]+)$#', $referer, $matches)) {
        $slug = $matches[1];
        $uid = $matches[2];
        
        // Find the page by UID
        return page('blog')->children()->find($uid);
      }
      
      // Example: Handle virtual pages or routes
      if (str_starts_with($referer, '/products/')) {
        $productId = basename($referer);
        // Return your virtual product page
        return page('products')->find($productId);
      }
      
      // Fall back to default resolution
      return \tobimori\DreamForm\DreamForm::findPageOrDraftRecursive($referer);
    }
  ]
];
```

--------------------------------

### Kirby DreamForm Action Class Utility Methods

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/3_actions/8_custom.md

This section documents the core utility methods available within any custom action class in Kirby DreamForm, allowing developers to interact with submission data, form configuration, block settings, and control the flow of the form submission process.

```APIDOC
Action Class:
  - submission(): Submission
    Description: Access the submission object.
  - form(): Form
    Description: Access the form object.
  - block(): Block
    Description: Access the block used to configure the action.
  - success(): void
    Description: End the submission early, and show the success screen.
  - cancel(message: string = null, public: bool = false): void
    Description: Cancel the request with an error message. If 'public' is false, the error message is only shown when debug mode is enabled.
  - silentCancel(message: string = null): void
    Description: Silently cancel the form submission. Submission will be shown as successful to the user, except if debug mode is enabled.
```

--------------------------------

### Configure Available Dreamform Fields in PHP

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/2_fields/0_what-are-fields.md

This PHP configuration snippet demonstrates how to restrict or specify which fields are available for use in Kirby Dreamform. By default, all registered fields are available, but this setting allows developers to define a whitelist of field types.

```php
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'fields' => [
      'available' => ['text', 'textarea', 'select', 'checkboxes', /* other guards here */ ],
    ],
  ],
];
```

--------------------------------

### PHP Hook: `dreamform.upload:after`

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/5_developers/5_hooks.md

This PHP hook is called after a file from a file upload field has been processed and created as a file of the submission page. It provides access to the created Kirby `File` object and the file upload field.

```php
return [
  'hooks' => [
    'dreamform.upload:after' => function (\Kirby\Cms\File $file, \tobimori\DreamForm\Fields\FileUploadField $field) {
      // your code goes here
    }
  ]
];
```

--------------------------------

### Protecting DreamForm Uploaded Files in Kirby CMS

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/2_fields/11_file-upload.md

This PHP code snippet demonstrates how to secure files uploaded through Kirby DreamForm. It implements a file firewall using Kirby's routing system to intercept file access requests, ensuring that files are only downloadable by authenticated users. Additionally, it customizes Kirby's `file::url` and `file::version` components to manage the URLs and versions of protected files, preventing direct public access to sensitive uploads.

```php
<?php

use Kirby\Toolkit\Str;
use Kirby\Uuid\Uuid;
use Kirby\Cms\App;

App::plugin('dreamform/files-firewall', [
  'routes' => [
    [
      'pattern' => '_form/(:any)',
      'action'  => function ($filename) {
        if (
          kirby()->user() &&
          $file = Uuid::for("file://{$filename}")?->model()
        ) {
          /** @var \Kirby\Cms\File $file */
          return $file->download();
        }

        return site()->errorPage();
      },
    ],
  ],
  'components' => [
    'file::url' => function ($kirby, $file) {
      if ($file->template() === 'dreamform-upload') {
        return $kirby->url() . '/_form/' . Str::replace($file->uuid()->toString(), 'file://', '');
      }

      return $file->mediaUrl();
    },
    'file::version' => function ($kirby, $file, array $options = []) {
      static $original;

      // if the file is protected, return the original file
      if ($file->template() === 'dreamform-upload') {
        return $file;
      }

      // if static $original is null, get the original component
      if ($original === null) {
        $original = $kirby->nativeComponent('file::version');
      }

      // and return it with the given options
      return $original($kirby, $file, $options);
    }
  ]
]);
```

--------------------------------

### PHP Snippet for Custom Guard Input Field

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/4_guards/7_custom.md

This PHP snippet defines the HTML structure for a custom 'calc' guard input field within Kirby DreamForm. It includes a label with a dynamically generated question and an input field of type 'number' that is required. The snippet is designed to be placed in `/site/plugins/calc-guard/snippets/calc.php`.

```PHP
// site/plugins/calc-guard/snippets/calc.php

<div <?= attr($attr['field']) ?>> <?php /* $attr includes the classes apply to the fields */ ?>
  <label <?= attr(A::merge($attr['label'], ["for" => "calc"])) ?>>
    <span><?= $guard->generate() ?></span><em>*</em> <?php /* Generate the result and show the question */ ?>
  </label>
  
  <input <?= attr(A::merge($attr['input'], [
    'type' => 'number',
    'id' => 'calc',
    'name' => 'calc',
    'required' => true
  ])) ?>>
</div>
```

--------------------------------

### Populate Hidden Input Fields from URL Parameters with JavaScript

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/2_fields/10_hidden.md

This JavaScript snippet demonstrates how to dynamically populate hidden input fields on a webpage using values extracted from URL parameters. It iterates through the URL's query string, finds corresponding hidden input elements by their `name` attribute, and assigns the URL parameter's value to them. This is particularly useful for scenarios where server-side population is hindered by caching, ensuring client-side data persistence.

```javascript
// Split the URL parameters into key-value pairs
const params = new URLSearchParams(window.location.search.substring(1));

// Loop through each key-value pair
for (const [key, value] of params) {
  // Find the input field with the matching name
  const input = document.querySelector(`input[type="hidden"][name="${key}"]`);

  // If the input field exists, set its value
  if (input) {
    input.value = value;
  }
}
```

--------------------------------

### Enable Precognition in Kirby Dreamform Configuration

Source: https://github.com/tobimori/kirby-dreamform/blob/develop/docs/0_general/4_precognition.md

This PHP configuration snippet enables the 'precognition' feature within the 'tobimori.dreamform' plugin for Kirby CMS. It sets the form mode to 'htmx' and activates real-time field validation, which provides immediate feedback as users type.

```PHP
// site/config/config.php

return [
  'tobimori.dreamform' => [
    'mode' => 'htmx',
    'precognition' => true,
  ],
];
```