Form Builder Add-on Guide for Larapen

Build any form your site needs by dragging fields onto a canvas, no code, no template edits. Show and hide fields based on what the visitor answers, collect file uploads, and read every response in a searchable inbox you can export to CSV.

Use Cases

Contact and enquiry forms

The classic case, with the parts that usually need a developer already built in.

• Ask a different follow-up question depending on the enquiry type.
• Reply automatically to the visitor while notifying the right inbox internally.
• Keep spam out with a CAPTCHA, a hidden trap field and a per-visitor rate limit.

Quote requests and project briefs

Longer forms where what you ask depends on what the visitor is buying.

• Reveal budget and deadline questions only once a project type is chosen.
• Accept a specification document as a file upload.
• Push every brief straight into your CRM through a webhook.

Surveys and feedback

Star ratings, sliders and multiple choice, with an optional follow-up.

• Ask for an email address only when the respondent asks to be contacted.
• Group questions with headings, text blocks and dividers.
• Export the results to CSV and analyse them in a spreadsheet.

Registrations, applications and sign-ups

Any form that collects structured data and a document.

• Limit a form to one submission per email address.
• Close it automatically on a date, or once a number of responses is reached.
• Require visitors to sign in before they can submit.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Form Builder in the list and click Activate. Its migrations and permissions are set up automatically, and a ready-to-use Contact us form is created so you have something to look at immediately.

Step 3: Open the Builder

Navigate to Admin → Forms → All Forms and click a form to open the builder. See Quick Start.

Purchase Code (License Key)

Form Builder is sold as a separate product, so it has its own purchase code (license key), distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Form Builder in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

Platform / Marketplace	How you get the purchase code	Where to find it again
bedigit.com Store In-site purchase (Shop)	Generated automatically when the order is paid, then sent by email, either in its own license email, or inside the order confirmation email.	My Account → My Licenses on bedigit.com
Gumroad	Created as soon as Gumroad notifies us of the sale, then sent in a separate email, in addition to the Gumroad receipt.	The license email, your Gumroad Library, and My Account → My Licenses on bedigit.com
Envato Market CodeCanyon	Issued by Envato, not by us, and never sent by email: you download it yourself from your Envato account.	Envato account → Downloads → License certificate & purchase code

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit: buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library in your Gumroad account.
• The key is recorded on your bedigit.com account as well, under My Account → My Licenses.

3. Envato Market (CodeCanyon)

• Envato issues the purchase code itself. We never send it by email, because we do not receive it.
• Get it from your Envato account: Downloads → find the item → License certificate & purchase code (the text or PDF version both contain it).
• It looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Quick Start

Building and publishing a working form takes about two minutes.

1. Go to Admin → Forms → All Forms and click New form.
2. Give it an internal name, only you see this, and save. You land straight on the builder.
3. Click field types in the left palette to add them, or drag them onto the canvas.
4. Click a field on the canvas to open its settings on the right: label, required, width, validation, logic.
5. Click Save changes (or press Ctrl/Cmd + S).
6. Click Preview to try the real form, then open Form settings to set who gets notified.

Your form is now live at /forms/<slug>. To put it inside an existing page instead, see Embedding a Form.

The Builder

The builder has three panes: the field palette on the left, the canvas in the middle, and the settings of the selected field on the right.

Adding and Arranging Fields

• Add a field: click it in the palette to append it to the end, or drag it to a precise position on the canvas.
• Reorder: drag a field by the handle on its left edge.
• Duplicate or delete: use the buttons that appear on the field when you hover or select it. Deleting a field also removes any logic rule that pointed at it.
• Select: click anywhere on a field to load it into the settings pane.

Each field on the canvas shows its type, its machine name, its width, and badges for Required, Logic and hidden fields, so you can read the whole form at a glance.

Field Settings

The settings pane has three tabs.

Tab	What it holds
Field	Label, machine name, placeholder, help text, default value, choices, width, required, and whether the field is shown at all.
Rules	Validation for that field type: minimum and maximum length, numeric bounds, date range, rows, accepted file types and sizes, or a regular expression.
Logic	Show or hide the field depending on other answers. See Conditional Logic.

The machine name is the key the answer is stored under. It appears as a column header in the CSV export, as a key in the webhook payload, and as the field you point logic rules at. It is generated from the label, and you can edit it: renaming it updates every logic rule that referenced it.

Layout and Widths

Every field has a width, so two or three can share a row: 1/1, 2/3, 1/2, 1/3 and 1/4. On phones every field takes the full width regardless.

Three field types carry no answer and exist purely to structure the form:

• Heading: a section title.
• Text block: a paragraph of explanation.
• Divider: a horizontal rule.

Field Types

Group	Type	What it collects
Text	Single line	A short answer. Optional minimum and maximum length, and a regular expression.
	Paragraph	A longer answer, with a configurable number of rows.
	Email	A validated email address. Can be used as the reply-to and auto-reply target.
	Phone	A phone number, with an optional pattern.
	Website	A validated URL.
	Number	A number, with optional minimum, maximum and step.
Choices	Dropdown	One value from a list.
	Radio buttons	One value from a list, all options visible.
	Checkboxes	Several values, with optional minimum and maximum selections.
	Consent	A single tick box for a statement. When required it must actually be ticked.
Advanced	Date	A date, with optional earliest and latest bounds.
	Time	A time of day.
	Rating	A star rating; you choose how many stars.
	Slider	A value on a scale, with minimum, maximum and step.
	File upload	One or more files. See Uploaded Files.
	Hidden	A fixed value submitted with the form but never shown.
Layout	Heading	Nothing: a section title.
	Text block	Nothing: a paragraph of explanation.
	Divider	Nothing: a horizontal rule.

Conditional Logic

Any field can be shown or hidden depending on what the visitor answered elsewhere. Open the field’s Logic tab, switch on Only show this field sometimes, and add one or more conditions.

A rule reads as a sentence:

Show this field  when  all  of these match:
    [ Reason ]  [ is ]  [ support ]

• Show or Hide: what happens when the conditions match.
• all or any: whether every condition must match, or just one of them.
• Conditions can point at any other field that carries an answer. Layout blocks cannot be tested.

Operators

Operator	Matches when the tested field…
is	…equals the value. For checkboxes, when the value is among those ticked.
is not	…does not equal the value.
contains	…contains the value as text.
does not contain	…does not contain the value as text.
is greater than	…is numerically larger. For checkboxes, when more than that many boxes are ticked.
is less than	…is numerically smaller.
is empty	…has no answer at all.
is not empty	…has any answer.
is checked	…is a ticked consent box, or a checkbox group with at least one selection.
is not checked	…is an unticked consent box, or an empty checkbox group.

Comparisons ignore letter case, so a rule typed as support still matches an answer stored as Support. is empty, is not empty, is checked and is not checked test nothing else, so they take no value.

Examples

Ask a follow-up question only when it applies

On a contact form, ask for an order reference only from people choosing technical support:

Field:  Order reference   (required)
Logic:  Show this field when all of these match:
            Reason  is  support

Anyone picking a different reason never sees the field, and the form submits without it.

Reveal a field when a box is ticked

On a feedback form, only ask for an email address from people who want a reply:

Field:  Where should we reply?   (required)
Logic:  Show this field when all of these match:
            I would like someone to get back to me  is checked

Catch the "other" case

Field:  Tell us what you have in mind   (required)
Logic:  Show this field when all of these match:
            Project type  is  other

Chained conditions

Rules can point at fields that are themselves conditional. If the field a rule tests is hidden, it counts as having no answer, so the dependent field hides too. You can chain several levels without anything special to configure.

Form Settings

Open a form and click Form settings. Settings are grouped into six tabs.

General

Setting	What it does
Internal name	How the form is listed in the admin. Visitors never see it.
URL slug	The address of the public page, under /forms/. Generated from the name if left empty.
Public title and description	Shown above the form. Translated per language.
Button label	The text on the submit button.
After submission	Show a thank-you message, or redirect to a URL of your choice.

Behaviour

Setting	What it does
Form is live	Off takes the form offline everywhere at once, including anywhere it is embedded.
Give it a public page	Off means the form exists only where you embed it, no page of its own.
Require sign-in	Only signed-in visitors can see and submit the form.
One submission per email address	Blocks a second submission from an address already used.
Maximum submissions	The form closes itself once it reaches this number.
Opens at / Closes at	A window outside which the form is closed.
Closed message	What a visitor sees when the form is closed. Translated per language.
Store submissions	Off still emails you and fires webhooks, but keeps nothing on the server.
Store IP address	Off leaves the IP column empty on every new submission.

The other four tabs are covered under Email Notifications, Auto-reply, Webhooks and Anti-spam.

Public Page

Unless you switch off Give it a public page, every form has its own address:

https://your-site.com/forms/contact-us
https://your-site.com/fr/forms/contact-us

The page uses your active theme, carries its own SEO title and description (set on the SEO tab of the form settings), and is available in every language the form is translated into.

Embedding a Form

To put a form inside a page you already have (a contact page, a landing page, a blog post) paste its embed token into the content:

[form:contact-us]

The token for each form is shown in the Embed token column of Admin → Forms → All Forms; click it to copy. Paste it anywhere content is edited ( a page, a rich-text section, a post) and it is replaced by the live form when the page is viewed.

• The form keeps working exactly as it does on its own page: validation, conditional logic, file uploads, CAPTCHA.
• You can embed the same form on several pages; each one submits independently.
• A token pointing at a form that is deleted or switched off simply disappears: visitors never see the raw text.

Theme developers can also place a form directly in a template:

<x-formbuilder-form slug="contact-us" />
<x-formbuilder-form slug="contact-us" :show-title="false" compact />

Adding to a Menu

To link a form from your header or footer, go to Admin → Menus, open the menu you want, add an item of type Custom URL, and point it at the form’s address (for example /forms/contact-us). The label is translated per language like any other menu item.

Submissions Inbox

Admin → Forms → Submissions lists everything your forms have collected, newest first, with four counters at the top: total, unread, today, and spam.

• Search across the answers, your internal notes and the IP address.
• Filter by form, by status, by date range, or to starred entries only.
• Star anything you want to come back to.
• Select several with the checkboxes to change their status or delete them in one go.
• Auto-refresh the list on an interval while you watch for new entries.

Click a row to open it. The detail page shows every answer against its question, the visitor’s details (when, from where, which language, which browser), a box for internal notes, and arrows to walk to the next or previous submission without going back to the list. Opening an unread submission marks it read.

Statuses

Status	Meaning
New	Not yet opened. Counts towards the unread badge.
Read	Opened by someone on your team.
Replied	You have answered. Set it yourself after replying.
Spam	Junk. Set automatically when the anti-spam checks catch a submission.
Archived	Dealt with, kept for the record.

Deleted submissions go to the Trash, where they can be restored. Emptying the trash deletes them and their uploaded files for good.

CSV Export

The Export CSV button downloads exactly what the list is currently showing: the same form, status, date range and search apply.

• Filtering by a single form gives one column per question, in the order they appear on the form.
• Without a form filter, all the answers of each submission are combined into a single column, because two different forms have no columns in common.
• Choices are exported by their label, not their stored value, so the file reads the way the form does.
• The file opens correctly in Excel, including accented characters.

Uploaded Files

Files attached to a submission appear on its detail page with their original name and size; click one to download it.

What a field accepts (file types, maximum size, how many files) is set per field on its Rules tab, within the site-wide limits under Global Settings. A field can narrow that list, never widen it.

Email Notifications

On the Notifications tab of a form’s settings:

Setting	What it does
Email me new submissions	Switches the notification off without affecting the inbox.
Recipients	One or more addresses, separated by commas. Leave empty to notify every administrator instead.
Notification subject	Your own subject line. Use {form} and {site} as placeholders.
Reply-to field	Which email field belongs to the visitor, so replying to the notification reaches them directly.

The email lists every answer against its question and links straight to the submission in the admin panel. Administrators can also opt out individually under My Account → Notifications, and the whole notification type can be switched off site-wide in the core notification settings.

Auto-reply

An auto-reply confirms to the visitor that their message arrived. On the Auto-reply tab:

• Switch on Send an auto-reply.
• Choose which email field it is sent to, or leave it on automatic detection.
• Write the subject and the message. Both are translated per language, and the visitor gets the language they used.

The message can quote what was submitted. Write the machine name of a field in braces:

Hello {full_name},

Thank you for your quote request. Our team is reviewing your brief
and will send you a costed proposal within two business days.

{form} and {site} are available too. Replies go to the first address in your Recipients list, so a visitor answering the confirmation reaches a real inbox.

Webhooks

A webhook sends each submission straight to another system (a CRM, a spreadsheet service, an automation platform, or your own application) as a JSON POST request.

On the Webhook tab of a form’s settings, switch on Send submissions to a webhook and paste the endpoint URL. Then click Send test: a sample payload goes out immediately and the result is reported on screen, so you can wire up the receiving end before a single visitor fills the form.

Signing

Set a signing secret and every request carries a signature your endpoint can verify:

X-Larapen-Signature: sha256=<hmac of the raw body>
X-Larapen-Event:     form.submission.created
X-Larapen-Form:      contact-us
X-Larapen-Delivery:  <unique id for this attempt>

Recompute the HMAC over the raw request body with your secret and compare it to the header. If they differ, the request did not come from your site, or it was altered on the way. The developer documentation has a worked example.

Retries and the delivery log

If the endpoint does not answer with a success code, the delivery is retried automatically, after one minute, then five, then fifteen. Every attempt is recorded under Admin → Forms → Webhook Log, with its status, the HTTP code, how long it took, the exact payload sent and the response received.

• Open any entry to inspect the payload, and copy it for testing against your endpoint.
• Use Send again to replay a failed delivery once the endpoint is fixed: it re-sends exactly what was sent originally.
• Old entries are cleaned up automatically; see Privacy & Retention.

Anti-spam & CAPTCHA

Three defences run on every public form, and they layer: a bot has to get past all of them.

1. The hidden trap

Each form carries a field no human ever sees and a signed record of when the page was rendered. A submission that fills the invisible field, or that comes back faster than a person could type, is treated as automated.

2. Rate limiting

The number of submissions accepted from one visitor per form, and the window it is counted over, are set under Global Settings. Further attempts are refused with a message telling the visitor when to try again.

3. CAPTCHA

Form Builder uses whichever CAPTCHA provider is configured in Admin → Settings → Security: the self-hosted image challenge, reCAPTCHA, hCaptcha or Turnstile. Switch it on for forms globally under Global Settings, and opt individual forms out on their Behaviour tab.

The self-hosted option needs no third-party account and no external request, which keeps the form working on sites that block external services.

Multi-Language

Forms are translated in two places, both driven by a Language selector.

Field labels

In the builder, pick a language in the header and edit the labels, placeholders and help text for it. Save, then switch language and do the next one. Each language is stored separately.

Form settings

In Form settings, one language selector above the tabs governs every translatable setting at once: the public title and description, the button label, the success and closed messages, the auto-reply, and the SEO title and description. Switch language, fill it in, and save once.

Everything else (the labels of the admin panel, validation messages, the buttons on the public form) is already translated into the languages the platform ships with. Untranslated content falls back to your default language, so a partially translated form still works.

Privacy & Retention

Forms often collect personal data, so the add-on gives you direct control over what is kept and for how long.

Control	Where	Effect
Store submissions	Form settings → Behaviour	Off means the notification and the webhook still go out, carrying the data, but nothing is written to your database.
Store IP address	Form settings → Behaviour	Off leaves the IP empty on new submissions.
Delete submissions after	Global settings → Retention	Submissions older than this are deleted automatically, with their uploaded files. 0 keeps them forever.
Delete webhook records after	Global settings → Retention	Delivery log entries older than this are removed. 0 keeps them forever.
Consent field	Any form	A required tick box recording that the visitor agreed, stored with the submission.

Retention runs once a day with your site’s scheduler. To run it by hand, or to see what it would remove without deleting anything:

php artisan formbuilder:prune
php artisan formbuilder:prune --dry-run

Global Settings

Admin → Forms → Settings holds the defaults that apply to every form.

Tab	Setting	Default
Uploads	Allowed file types	pdf, doc, docx, xls, xlsx, csv, txt, zip, jpg, jpeg, png, gif, webp
	Maximum file size	5120 KB per file
Anti-spam	CAPTCHA on forms	Enabled
	Minimum fill time	2 seconds
	Submissions per IP	5
	Time window	10 minutes
Retention	Delete submissions after	0 (keep forever)
	Delete webhook records after	30 days
Page Header	How the header of the public form pages looks, overriding the site-wide page header settings.

Your server’s own upload limit still applies on top of the maximum file size: a value larger than the server allows will not take effect.

Permissions

The add-on registers eleven permissions, assignable per role under Admin → Users → Roles.

Permission	Allows
formbuilder.forms.view	See the forms list and the builder.
formbuilder.forms.create	Create and duplicate forms.
formbuilder.forms.edit	Edit forms and their fields, and send webhook tests.
formbuilder.forms.delete	Delete forms and manage the forms trash.
formbuilder.submissions.view	Read submissions and download their files.
formbuilder.submissions.edit	Change status, star, and write internal notes.
formbuilder.submissions.delete	Delete submissions and manage their trash.
formbuilder.submissions.export	Download the CSV export.
formbuilder.webhooks.view	Read the webhook delivery log.
formbuilder.settings.view	Open the global settings page.
formbuilder.settings.edit	Change the global settings.

Updating

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

1. Download the latest .zip file of this add-on.
2. Go to Admin panel → Add-ons and click the Upload button.
3. Select or drag the .zip file into the upload area.
4. A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
5. Go to Admin panel → System Update (/admin/update) to apply any pending database migrations.

Method 2: Manual File Replacement

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

php artisan migrate

Pending migrations run once, so the command is safe to repeat.

Step 3: Clear Caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Step 4: Verify

Visit Admin → Forms → All Forms to confirm the add-on is working correctly, and open one of your forms on the front-end to check it still submits.

Uninstallation

Switching an add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Form Builder and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered, and its public form pages stop answering.
• Embed tokens stop being expanded, so [form:<slug>] in a page simply produces nothing rather than a form.
• Its database tables and all the data they hold are kept, your forms and every submission, and its files stay under extensions/addons/formbuilder/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run, assets are republished, and the add-on picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on's data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Form Builder (see Uninstallation).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on's uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations (this drops its database tables and every row they hold, including all your forms and every submission they have collected) and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/formbuilder/, public/vendor/formbuilder/ and storage/app/public/addons/formbuilder/;
• deletes the add-on directory extensions/addons/formbuilder/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/formbuilder/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on's tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

Troubleshooting

The form does not appear on its page

• Check that Form is live is on, under Form settings → Behaviour.
• Check that Give it a public page is on, with it off, the form only exists where you embed it.
• If Require sign-in is on, the page is only visible to signed-in visitors.
• Make sure the form has at least one field: an empty form shows a notice instead.

The embed token shows as text instead of a form

• Check the slug in the token matches the form exactly, including hyphens: [form:contact-us].
• An unknown or switched-off form makes the token disappear entirely; if you see the raw text, the add-on is not active. Check Admin panel → Add-ons.
• Clear your site cache after activating: Admin → Settings → Cache.

A required field blocks the form even though it is hidden

• This should not happen: a hidden field is never validated. If it does, check the field’s Logic tab: a rule pointing at a field you have since deleted or renamed may no longer match.
• Open Preview in the builder and walk the form: it behaves exactly as the public page does.

Submissions arrive but no email does

• Check Email me new submissions is on, and that Recipients holds a valid address (leave it empty to notify all administrators).
• Send a test email from Admin → Settings → Mail to confirm the site can send at all.
• Check the notification is not switched off site-wide in the core notification settings, or individually under My Account → Notifications.
• Look in the recipient’s spam folder.

Real submissions are being marked as spam

• Lower or disable Minimum fill time under Admin → Forms → Settings → Anti-spam. A very short form can legitimately be filled in a couple of seconds.
• Nothing is lost: filter the inbox by Spam and change the status back.

A file upload is rejected

• Check the file’s extension is in the field’s Accepted extensions, and in the site-wide allow-list under Admin → Forms → Settings → Uploads. A field can narrow that list, never widen it.
• Check the size against the field’s Max size, and against your server’s own upload limit, which always wins.

The webhook never fires

• Use Send test on the form’s Webhook tab: it reports the endpoint’s answer immediately.
• Check Admin → Forms → Webhook Log for the attempts and the responses received.
• Deliveries are queued, so a site with no queue worker sends them on the next queue run. Check your worker is running.
• The endpoint must be an absolute http:// or https:// URL.

A translated label is not showing

• In the builder, pick the language in the header selector and check the label is filled in for it: each language is stored separately.
• Save before switching language: switching reloads the canvas.
• Empty translations fall back to your default language, which is usually what you want.