Kirby Uniform

Guards are the spam protection mechanism in Uniform. By default, if no guard is explicitly specified, the HoneypotGuard is used. You can chain multiple guards together to provide layered protection. If you need to bypass all spam protection for a specific form instance, you can use the withoutGuards() method before calling any other actions.

use Uniformorm;

$form = new Form;
if (kirby()->request()->is('POST')) {
    $form->honeypotGuard()
        ->calcGuard(['option' => 'value'])
        // more guards or call actions
}

The Honeypot Guard detects bot submissions by using a camouflaged form field. This field is visually hidden from human users but remains visible to bots. If the field contains any content upon submission, the guard rejects the request.

By default, the field is named website and uses the CSS class uniform__potty to hide itself. You must ensure the uniform__potty class is defined in your CSS to prevent human users from seeing the field.

Actions are used to process submitted web form data. They are only executed if the form data passes all configured guards. Multiple actions can be chained together, but if any action fails, the subsequent actions in the chain will not be executed.

If no guard is explicitly called, the first action in the chain will automatically execute the default HoneypotGuard.

To chain actions, call them sequentially on the Uniform\ Form instance:

use Uniform\Form;

$form = new Form;
if (kirby()->request()->is('POST')) {
    $form->emailAction([/* options */])
        ->logAction([/* options */])
        ->webhookAction([/* options */]);
}

Uniform v4 uses Kirby 3's native email handling via PHPMailer. You can no longer define custom email services within Uniform actions.

To configure transport settings (like SMTP), use the standard Kirby configuration. You must remove the service and service-options keys from the EmailAction options array.

String templating in Uniform v4 (Kirby 3) uses double curly braces {{ }} for variables instead of single braces { }.

Note on missing variables: In Uniform v4, if a variable in a template has no replacement, it will be removed from the string entirely rather than being left as literal text.

$form->emailAction([
    // ...
    'subject' => 'New request from {{firstname}} {{lastname}}',
]);

Install the Kirby Uniform plugin using Composer to add it to your Kirby project.

composer require mzur/kirby-uniform

When using Uniform, keep the following requirements in mind:

• Disable Kirby cache: For pages where you use Uniform, you must disable the Kirby cache to ensure forms are generated dynamically.
• Session Cookies: Uniform utilizes Kirby sessions, which requires a session cookie to be correctly set in the user's browser.

The uploadAction handles one or more uploaded files and moves them to a specified directory.

Important Security Note: The uploadAction does not perform any validation (such as file size or MIME type) by itself. You must use Uniform validation rules (like file, mime, and filesize) to ensure uploaded files are safe and meet your requirements. Always use a whitelist of allowed MIME types and a maximum file size.

$form->uploadAction(['fields' => [
    'filefield' => [
        'target' => $target_directory,
        'prefix' => $prefix_string,
    ],
]]);

After installation, perform the following two steps to ensure correct functionality:

1. CSS Setup: Add the following rule to your CSS to hide the honeypot field used for spam protection:

   .uniform__potty {
       position: absolute;
       left: -9999px;
   }

2. Disable Cache: Disable the Kirby cache for any pages where you are using Uniform. This ensures that form instances are generated dynamically and correctly handle state.